Claude MCP 서버 완전 가이드: 설정부터 실전 활용까지

MCP(Model Context Protocol)는 Claude가 외부 도구, 데이터베이스, API에 접근하는 표준 프로토콜이다. 기존에는 Claude에게 파일을 읽거나 GitHub 이슈를 확인하려면 매번 내용을 복사해서 붙여넣어야 했다. MCP를 설정하면 Claude가 직접 파일시스템을 탐색하고, 데이터베이스에 쿼리를 날리고, Slack 메시지를 검색할 수 있다. Anthropic이 공개한 오픈 표준으로, 서드파티 개발자들이 자유롭게 MCP 서버를 만들어 배포한다. 이 가이드는 MCP의 작동 원리부터 Claude Code에서의 설정, 인기 서버 5종 활성화, 커스텀 서버 제작까지 실전 중심으로 다룬다.

MCP란? — Model Context Protocol 개념 정리

MCP는 2024년 말 Anthropic이 공개한 AI 모델과 외부 시스템을 연결하는 오픈 프로토콜이다. 쉽게 말해, Claude에게 "손"과 "눈"을 달아주는 규격이다.

MCP의 핵심 구조

MCP는 세 가지 요소로 구성된다:

MCP 서버는 크게 세 가지 기능을 Claude에게 제공한다:

• Tools — 함수 호출 형태의 실행 가능한 작업 (파일 읽기, API 요청 등)
• Resources — 파일, DB 레코드처럼 읽기 전용으로 노출되는 데이터
• Prompts — 특정 작업에 최적화된 프롬프트 템플릿

MCP가 없으면 어떤 불편함이 있을까?

MCP 없이 Claude와 작업하면:

• GitHub PR 내용을 클립보드로 복사해서 붙여넣어야 한다
• 데이터베이스 조회 결과를 직접 정리해서 전달해야 한다
• 파일 구조를 손으로 나열해 줘야 한다

MCP를 설정하면 Claude가 직접 이 모든 것을 조회·실행한다. 개발자는 "무엇을 할지"만 말하면 되고, "어떻게 가져올지"는 MCP 서버가 담당한다.

Claude Code에서 MCP 서버 활성화하기

Claude Code는 claude mcp 명령어와 .claude/settings.json 두 가지 방법으로 MCP 서버를 관리한다.

방법 1: CLI로 즉시 추가

# MCP 서버 추가 (기본 — 프로젝트 범위)
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /Users/sangmin/projects

# 전역(글로벌) 범위로 추가
claude mcp add --scope global github -- npx -y @modelcontextprotocol/server-github

# 현재 등록된 MCP 서버 목록 확인
claude mcp list

# 특정 서버 상세 정보 확인
claude mcp get filesystem

# 서버 제거
claude mcp remove filesystem

방법 2: settings.json 직접 편집

.claude/settings.json 파일에 mcpServers 블록을 추가한다. 이 방법은 팀 전체가 동일한 MCP 구성을 공유할 때 유용하다.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/sangmin/projects"],
      "env": {}
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_URL": "postgresql://user:password@localhost:5432/mydb"
      }
    }
  }
}

전역 설정 vs 프로젝트 설정

보안 팁: API 키와 비밀번호는 settings.json에 직접 쓰지 말고 환경변수(env 블록)를 통해 주입하라. .claude/settings.json은 팀원과 공유되므로 민감 정보를 넣으면 안 된다.

인기 MCP 서버 5선 — 설정과 활용법

1. Filesystem — 로컬 파일 탐색

claude mcp add filesystem -- \
  npx -y @modelcontextprotocol/server-filesystem /path/to/allowed/directory

설정 후 Claude에게 "프로젝트 디렉토리 구조를 분석해줘"라고 하면 직접 파일을 읽고 정리해준다. 허용할 경로를 좁게 지정하는 것이 보안상 바람직하다.

실전 활용:

• 레거시 코드베이스 분석 ("이 디렉토리에서 TODO 주석 전부 찾아줘")
• 로그 파일 실시간 분석
• 여러 설정 파일을 한 번에 비교

2. GitHub — 이슈·PR·코드 검색

{
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx"
    }
  }
}

실전 활용:

• "오늘 열린 이슈 중 버그 레이블 붙은 것 정리해줘"
• "이번 스프린트 PR 리뷰 상태 요약해줘"
• 코드베이스 검색 + 변경 이력 추적

3. Postgres — 데이터베이스 직접 조회

{
  "postgres": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-postgres"],
    "env": {
      "POSTGRES_URL": "postgresql://user:pass@localhost:5432/proddb"
    }
  }
}

실전 활용:

• "지난 7일 신규 가입자 수와 전환율 계산해줘"
• 스키마 자동 파악 후 복잡한 집계 쿼리 생성
• 느린 쿼리 탐지 및 인덱스 제안

주의: 프로덕션 DB에 write 권한을 주지 마라. 읽기 전용 계정(GRANT SELECT)을 별도로 만들어 연결하라.

4. Slack — 채널 검색과 메시지 조회

{
  "slack": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-slack"],
    "env": {
      "SLACK_BOT_TOKEN": "xoxb-xxxxxxxxxxxx",
      "SLACK_TEAM_ID": "T0XXXXXXX"
    }
  }
}

실전 활용:

• "지난주 #incidents 채널 주요 이슈 요약해줘"
• 특정 키워드가 언급된 대화 스레드 찾기
• 팀 커뮤니케이션 분석 (응답 시간, 채널 활성도 등)

5. Notion — 문서와 데이터베이스 연동

{
  "notion": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-notion"],
    "env": {
      "NOTION_API_KEY": "secret_xxxxxxxxxxxx"
    }
  }
}

실전 활용:

• Notion 로드맵 데이터베이스에서 이번 달 출시 항목 가져오기
• 회의록 페이지 자동 정리 및 액션 아이템 추출
• Notion 내 정보를 코드 작업 중 실시간 참조

커스텀 MCP 서버 만들기 — Node.js 실전 예제

공식 서버가 없는 사내 시스템이나 특수 API가 있다면 직접 MCP 서버를 만들 수 있다. @modelcontextprotocol/sdk 패키지 하나면 충분하다.

설치

mkdir my-mcp-server && cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk

기본 서버 구조 (server.js)

아래는 사내 REST API에서 직원 정보를 조회하는 커스텀 MCP 서버 예제다.

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";

// MCP 서버 인스턴스 생성
const server = new Server(
  { name: "company-hr-api", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

// Claude에게 노출할 도구 목록 정의
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "get_employee",
      description: "직원 ID로 직원 정보를 조회합니다.",
      inputSchema: {
        type: "object",
        properties: {
          employee_id: {
            type: "string",
            description: "조회할 직원의 ID",
          },
        },
        required: ["employee_id"],
      },
    },
    {
      name: "list_team_members",
      description: "팀 이름으로 팀원 목록을 조회합니다.",
      inputSchema: {
        type: "object",
        properties: {
          team_name: {
            type: "string",
            description: "팀 이름 (예: engineering, design)",
          },
        },
        required: ["team_name"],
      },
    },
  ],
}));

// 도구 실행 핸들러
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  if (name === "get_employee") {
    // 실제 구현에서는 내부 API 호출
    const response = await fetch(
      `https://internal-hr.company.com/api/employees/${args.employee_id}`,
      { headers: { Authorization: `Bearer ${process.env.HR_API_TOKEN}` } }
    );
    const employee = await response.json();
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(employee, null, 2),
        },
      ],
    };
  }

  if (name === "list_team_members") {
    const response = await fetch(
      `https://internal-hr.company.com/api/teams/${args.team_name}/members`,
      { headers: { Authorization: `Bearer ${process.env.HR_API_TOKEN}` } }
    );
    const members = await response.json();
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(members, null, 2),
        },
      ],
    };
  }

  throw new Error(`Unknown tool: ${name}`);
});

// stdio 트랜스포트로 서버 시작
const transport = new StdioServerTransport();
await server.connect(transport);
console.error("HR MCP Server running on stdio");

Claude Code에 등록

{
  "mcpServers": {
    "company-hr": {
      "command": "node",
      "args": ["/path/to/my-mcp-server/server.js"],
      "env": {
        "HR_API_TOKEN": "your-internal-api-token"
      }
    }
  }
}

등록 후 Claude에게 "engineering 팀 전체 멤버 목록 알려줘"라고 하면 MCP 서버를 통해 실시간으로 조회해서 답변한다.

보안 고려사항

MCP는 강력한 만큼 잘못 설정하면 보안 위험이 생긴다. 핵심 원칙 네 가지:

1. 최소 권한 원칙(Least Privilege)

• DB 연결은 SELECT 권한만 있는 읽기 전용 계정 사용
• 파일시스템은 필요한 디렉토리만 허용 (/ 전체를 허용하지 마라)

2. 비밀 정보 관리

• API 키와 비밀번호는 settings.json env 블록으로 분리
• .claude/settings.json을 .gitignore에 추가하거나, 환경변수를 .env에서 로드하는 래퍼 스크립트 작성

3. 서드파티 서버 검증

• npx -y로 자동 설치되는 서버는 공식 @modelcontextprotocol 네임스페이스 것만 사용
• 출처 불명의 MCP 서버는 코드를 직접 검토한 후 사용

4. 프롬프트 인젝션 주의

• 외부 데이터(GitHub 이슈 본문, Notion 페이지 등)에 악의적 지시가 포함될 수 있다
• Claude Code의 권한 시스템과 함께 사용해 중요 작업은 항상 승인을 받도록 설정

Claude Code의 자동화 전반을 더 깊이 이해하려면 Claude Code Hooks 완전 가이드도 함께 읽어보길 권한다.

Claude Code + MCP 활용 팁

세션 시작 시 MCP 상태 확인

# 등록된 MCP 서버 상태 확인
claude mcp list

# 특정 서버 디버그 모드로 실행
claude --mcp-debug

MCP와 Hooks 조합

Claude Code 완전 가이드에서 다루듯, Hooks와 MCP를 조합하면 더 강력한 자동화가 가능하다. 예를 들어 PostToolUse Hook으로 MCP를 통한 DB 쓰기 직후 알림을 보내거나, PreToolUse Hook으로 특정 MCP 도구 호출을 조건부로 차단할 수 있다.

실전 프롬프트 예시

MCP 서버들이 모두 활성화된 상태에서 Claude에게 던질 수 있는 프롬프트들:

"GitHub에서 오늘 올라온 PR 목록을 가져와서 
 각 PR에 연관된 이슈 번호와 함께 정리해줘."

"Postgres DB에서 이번 달 MAU와 전월 대비 변화율 계산 후,
 Notion의 'Monthly KPI' 페이지에 업데이트해줘."

"Slack #dev-alerts 채널에서 지난 24시간 동안 ERROR가
 포함된 메시지를 전부 모아서 원인별로 분류해줘."

P1 Power Prompts로 MCP 완전 정복

MCP 설정 자체는 이 가이드로 충분하지만, Claude에게 MCP 도구를 최대한 활용하게 만드는 프롬프트 전략은 별도의 연습이 필요하다. P1 Power Prompts for Claude Code는 GitHub MCP, Postgres MCP, 커스텀 서버를 실전에서 제어하는 20개 검증된 프롬프트 패턴을 포함한다. MCP 설정 후 "이제 뭘 시켜야 하지?"라는 막막함을 없애준다.

Frequently Asked Questions

MCP 서버와 Claude Code 플러그인은 같은 것인가요?

다르다. MCP 서버는 Anthropic이 정의한 오픈 프로토콜 표준으로, Claude Code 외에 Claude Desktop, 서드파티 AI 클라이언트 등 다양한 호스트에서 동작한다. Claude Code 플러그인(스킬)은 Claude Code 전용 자동화 기능이다. MCP는 외부 시스템과의 연결에 집중하고, 스킬은 Claude Code 내부 워크플로 자동화에 집중한다.

MCP 서버가 연결 안 될 때 디버깅 방법은?

claude --mcp-debug 플래그로 실행하면 MCP 서버와의 통신 로그가 stderr에 출력된다. 가장 흔한 원인은 세 가지다: (1) npx 패키지 설치 실패 — npx -y 옵션 확인, (2) 환경변수 누락 — env 블록에 필요한 키 추가, (3) 경로 오류 — args의 파일/디렉토리 경로를 절대 경로로 변경.

MCP 서버는 프로젝트마다 다르게 설정할 수 있나요?

가능하다. 전역 설정(~/.claude/settings.json)에 공통 서버를 넣고, 프로젝트별 .claude/settings.json에 해당 프로젝트에만 필요한 서버를 추가하면 된다. Claude Code는 두 설정을 병합해서 사용한다. 같은 이름의 서버가 있으면 프로젝트 설정이 우선한다.

커스텀 MCP 서버를 팀 전체에 배포하는 좋은 방법은?

세 가지 옵션이 있다. (1) 서버 코드를 npm 패키지로 배포해 npx로 설치하게 한다, (2) 프로젝트 레포에 서버 코드를 포함시키고 .claude/settings.json에서 상대 경로로 참조한다("command": "node", "args": ["./mcp-servers/hr-api.js"]), (3) 도커 컨테이너로 서버를 실행하고 TCP 트랜스포트를 사용한다. 팀 규모가 작으면 (2)번이 가장 간단하다.

MCP를 사용하면 Claude API 비용이 더 많이 드나요?

MCP 서버가 반환하는 데이터는 Claude의 컨텍스트 창에 추가되므로 입력 토큰이 증가한다. 예를 들어 DB 조회 결과가 크면 토큰이 빠르게 쌓인다. 비용 관리 팁: (1) MCP 도구가 반환하는 데이터 크기를 제한하는 필터 파라미터 추가, (2) 큰 데이터셋은 요약 형태로 반환하도록 서버 로직 작성, (3) 프롬프트 캐싱을 활용해 반복 조회 비용 절감. 구체적인 비용 절감 전략은 P1 Power Prompts에서 다룬다.