MCP로 외부 도구에 연결하기

Model Context Protocol (MCP)은 AI 에이전트를 외부 도구 및 데이터 소스에 연결하기 위한 개방형 표준입니다. MCP를 사용하면 에이전트가 데이터베이스를 쿼리하고, Slack 및 GitHub와 같은 API와 통합하며, 커스텀 도구 구현을 작성하지 않고도 다른 서비스에 연결할 수 있습니다.

MCP 서버는 로컬 프로세스로 실행하거나, HTTP를 통해 연결하거나, SDK 애플리케이션 내에서 직접 실행할 수 있습니다.

빠른 시작

이 예제는 HTTP 전송을 사용하여 Claude Code 문서 MCP 서버에 연결하고, 와일드카드와 함께 allowedTools를 사용하여 서버의 모든 도구를 허용합니다.

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Use the docs MCP server to explain what hooks are in Claude Code",
  options: {
    mcpServers: {
      "claude-code-docs": {
        type: "http",
        url: "https://code.claude.com/docs/mcp"
      }
    },
    allowedTools: ["mcp__claude-code-docs__*"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

에이전트는 문서 서버에 연결하여 hooks에 대한 정보를 검색하고 결과를 반환합니다.

MCP 서버 추가

query()를 호출할 때 코드에서 MCP 서버를 구성하거나, SDK가 자동으로 로드하는 .mcp.json 파일에서 구성할 수 있습니다.

코드에서

mcpServers 옵션에 MCP 서버를 직접 전달합니다:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "List files in my project",
  options: {
    mcpServers: {
      "filesystem": {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
      }
    },
    allowedTools: ["mcp__filesystem__*"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

설정 파일에서

프로젝트 루트에 .mcp.json 파일을 생성합니다. SDK가 이를 자동으로 로드합니다:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
    }
  }
}

MCP 도구 허용

MCP 도구는 Claude가 사용하기 전에 명시적인 권한이 필요합니다. 권한이 없으면 Claude는 도구가 사용 가능하다는 것을 볼 수 있지만 호출할 수는 없습니다.

도구 명명 규칙

MCP 도구는 mcp__<server-name>__<tool-name> 명명 패턴을 따릅니다. 예를 들어, "github"라는 이름의 GitHub 서버에 list_issues 도구가 있으면 mcp__github__list_issues가 됩니다.

allowedTools로 접근 권한 부여

allowedTools를 사용하여 Claude가 사용할 수 있는 MCP 도구를 지정합니다:

options: {
  mcpServers: { /* your servers */ },
  allowedTools: [
    "mcp__github__*",              // github 서버의 모든 도구
    "mcp__db__query",              // db 서버의 query 도구만
    "mcp__slack__send_message"     // slack 서버의 send_message만
  ]
}

와일드카드(*)를 사용하면 각 도구를 개별적으로 나열하지 않고도 서버의 모든 도구를 허용할 수 있습니다.

대안: 권한 모드 변경

허용된 도구를 나열하는 대신, 권한 모드를 변경하여 더 넓은 접근 권한을 부여할 수 있습니다:

• permissionMode: "acceptEdits": 도구 사용을 자동으로 승인합니다 (파괴적 작업에 대해서는 여전히 프롬프트 표시)
• permissionMode: "bypassPermissions": 파일 삭제나 셸 명령 실행과 같은 파괴적 작업을 포함한 모든 안전 프롬프트를 건너뜁니다. 특히 프로덕션 환경에서는 주의하여 사용하세요. 이 모드는 Task 도구에 의해 생성된 하위 에이전트에도 전파됩니다.

options: {
  mcpServers: { /* your servers */ },
  permissionMode: "acceptEdits"  // allowedTools 불필요
}

권한 모드에 대한 자세한 내용은 권한을 참조하세요.

사용 가능한 도구 확인

MCP 서버가 제공하는 도구를 확인하려면 서버의 문서를 확인하거나 서버에 연결하여 system init 메시지를 검사합니다:

for await (const message of query({ prompt: "...", options })) {
  if (message.type === "system" && message.subtype === "init") {
    console.log("Available MCP tools:", message.mcp_servers);
  }
}

전송 유형

MCP 서버는 다양한 전송 프로토콜을 사용하여 에이전트와 통신합니다. 서버가 지원하는 전송 방식을 확인하려면 서버의 문서를 확인하세요:

• 문서에서 실행할 명령어를 제공하는 경우 (예: npx @modelcontextprotocol/server-github), stdio를 사용합니다
• 문서에서 URL을 제공하는 경우, HTTP 또는 SSE를 사용합니다
• 코드에서 직접 도구를 빌드하는 경우, SDK MCP 서버를 사용합니다

stdio 서버

stdin/stdout을 통해 통신하는 로컬 프로세스입니다. 동일한 머신에서 실행하는 MCP 서버에 사용합니다:

HTTP/SSE 서버

클라우드 호스팅 MCP 서버 및 원격 API에는 HTTP 또는 SSE를 사용합니다:

HTTP(비스트리밍)의 경우 "type": "http"을 대신 사용합니다.

SDK MCP 서버

별도의 서버 프로세스를 실행하는 대신 애플리케이션 코드에서 직접 커스텀 도구를 정의합니다. 구현 세부 사항은 커스텀 도구 가이드를 참조하세요.

MCP 도구 검색

많은 MCP 도구가 구성되어 있으면 도구 정의가 컨텍스트 윈도우의 상당 부분을 차지할 수 있습니다. MCP 도구 검색은 모든 도구를 미리 로드하는 대신 필요에 따라 동적으로 도구를 로드하여 이 문제를 해결합니다.

작동 방식

도구 검색은 기본적으로 auto 모드로 실행됩니다. MCP 도구 설명이 컨텍스트 윈도우의 10% 이상을 차지할 때 활성화됩니다. 트리거되면:

1. MCP 도구가 컨텍스트에 미리 로드되는 대신 defer_loading: true로 표시됩니다
2. Claude가 필요할 때 검색 도구를 사용하여 관련 MCP 도구를 발견합니다
3. Claude가 실제로 필요한 도구만 컨텍스트에 로드됩니다

도구 검색은 tool_reference 블록을 지원하는 모델이 필요합니다: Sonnet 4 이상 또는 Opus 4 이상. Haiku 모델은 도구 검색을 지원하지 않습니다.

도구 검색 구성

ENABLE_TOOL_SEARCH 환경 변수로 도구 검색 동작을 제어합니다:

env 옵션에서 값을 설정합니다:

const options = {
  mcpServers: { /* your MCP servers */ },
  env: {
    ENABLE_TOOL_SEARCH: "auto:5"  // 5% 임계값에서 활성화
  }
};

인증

대부분의 MCP 서버는 외부 서비스에 접근하기 위해 인증이 필요합니다. 서버 구성에서 환경 변수를 통해 자격 증명을 전달합니다.

환경 변수를 통한 자격 증명 전달

env 필드를 사용하여 API 키, 토큰 및 기타 자격 증명을 MCP 서버에 전달합니다:

디버그 로깅이 포함된 완전한 작동 예제는 리포지토리에서 이슈 목록 조회를 참조하세요.

원격 서버용 HTTP 헤더

HTTP 및 SSE 서버의 경우, 서버 구성에서 직접 인증 헤더를 전달합니다:

OAuth2 인증

MCP 사양은 OAuth 2.1을 인가에 지원합니다. SDK는 OAuth 플로우를 자동으로 처리하지 않지만, 애플리케이션에서 OAuth 플로우를 완료한 후 헤더를 통해 액세스 토큰을 전달할 수 있습니다:

// 앱에서 OAuth 플로우 완료 후
const accessToken = await getAccessTokenFromOAuthFlow();

const options = {
  mcpServers: {
    "oauth-api": {
      type: "http",
      url: "https://api.example.com/mcp",
      headers: {
        Authorization: `Bearer ${accessToken}`
      }
    }
  },
  allowedTools: ["mcp__oauth-api__*"]
};

예제

리포지토리에서 이슈 목록 조회

이 예제는 GitHub MCP 서버에 연결하여 최근 이슈를 나열합니다. 이 예제에는 MCP 연결 및 도구 호출을 확인하기 위한 디버그 로깅이 포함되어 있습니다.

실행하기 전에 repo 스코프가 있는 GitHub 개인 액세스 토큰을 생성하고 환경 변수로 설정합니다:

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "List the 3 most recent issues in anthropics/claude-code",
  options: {
    mcpServers: {
      "github": {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-github"],
        env: {
          GITHUB_TOKEN: process.env.GITHUB_TOKEN
        }
      }
    },
    allowedTools: ["mcp__github__list_issues"]
  }
})) {
  // MCP 서버가 성공적으로 연결되었는지 확인
  if (message.type === "system" && message.subtype === "init") {
    console.log("MCP servers:", message.mcp_servers);
  }

  // Claude가 MCP 도구를 호출할 때 로그
  if (message.type === "assistant") {
    for (const block of message.content) {
      if (block.type === "tool_use" && block.name.startsWith("mcp__")) {
        console.log("MCP tool called:", block.name);
      }
    }
  }

  // 최종 결과 출력
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

데이터베이스 쿼리

이 예제는 Postgres MCP 서버를 사용하여 데이터베이스를 쿼리합니다. 연결 문자열은 서버에 인수로 전달됩니다. 에이전트는 자동으로 데이터베이스 스키마를 발견하고, SQL 쿼리를 작성하며, 결과를 반환합니다:

import { query } from "@anthropic-ai/claude-agent-sdk";

// 환경 변수에서 연결 문자열 가져오기
const connectionString = process.env.DATABASE_URL;

for await (const message of query({
  // 자연어 쿼리 - Claude가 SQL을 작성합니다
  prompt: "How many users signed up last week? Break it down by day.",
  options: {
    mcpServers: {
      "postgres": {
        command: "npx",
        // 서버에 연결 문자열을 인수로 전달
        args: ["-y", "@modelcontextprotocol/server-postgres", connectionString]
      }
    },
    // 읽기 쿼리만 허용, 쓰기는 불허
    allowedTools: ["mcp__postgres__query"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

오류 처리

MCP 서버는 다양한 이유로 연결에 실패할 수 있습니다: 서버 프로세스가 설치되지 않았거나, 자격 증명이 유효하지 않거나, 원격 서버에 접근할 수 없을 수 있습니다.

SDK는 각 쿼리 시작 시 init 하위 유형의 system 메시지를 발행합니다. 이 메시지에는 각 MCP 서버의 연결 상태가 포함됩니다. 에이전트가 작업을 시작하기 전에 연결 실패를 감지하려면 status 필드를 확인하세요:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Process data",
  options: {
    mcpServers: {
      "data-processor": dataServer
    }
  }
})) {
  if (message.type === "system" && message.subtype === "init") {
    const failedServers = message.mcp_servers.filter(
      s => s.status !== "connected"
    );

    if (failedServers.length > 0) {
      console.warn("Failed to connect:", failedServers);
    }
  }

  if (message.type === "result" && message.subtype === "error_during_execution") {
    console.error("Execution failed");
  }
}

문제 해결

서버가 "failed" 상태를 표시

init 메시지를 확인하여 어떤 서버가 연결에 실패했는지 확인합니다:

if (message.type === "system" && message.subtype === "init") {
  for (const server of message.mcp_servers) {
    if (server.status === "failed") {
      console.error(`Server ${server.name} failed to connect`);
    }
  }
}

일반적인 원인:

• 환경 변수 누락: 필요한 토큰과 자격 증명이 설정되어 있는지 확인하세요. stdio 서버의 경우, env 필드가 서버가 기대하는 것과 일치하는지 확인하세요.
• 서버 미설치: npx 명령의 경우, 패키지가 존재하고 Node.js가 PATH에 있는지 확인하세요.
• 잘못된 연결 문자열: 데이터베이스 서버의 경우, 연결 문자열 형식을 확인하고 데이터베이스에 접근 가능한지 확인하세요.
• 네트워크 문제: 원격 HTTP/SSE 서버의 경우, URL에 접근 가능하고 방화벽이 연결을 허용하는지 확인하세요.

도구가 호출되지 않음

Claude가 도구를 볼 수 있지만 사용하지 않는 경우, allowedTools로 권한을 부여했거나 권한 모드를 변경했는지 확인하세요:

options: {
  mcpServers: { /* your servers */ },
  allowedTools: ["mcp__servername__*"]  // Claude가 도구를 사용하기 위해 필요
}

연결 시간 초과

MCP SDK는 서버 연결에 대해 기본 60초 시간 초과를 가지고 있습니다. 서버가 시작하는 데 더 오래 걸리면 연결이 실패합니다. 시작 시간이 더 필요한 서버의 경우 다음을 고려하세요:

• 가능하다면 더 가벼운 서버 사용
• 에이전트를 시작하기 전에 서버를 미리 워밍업
• 느린 초기화 원인에 대한 서버 로그 확인

관련 리소스

• 커스텀 도구 가이드: SDK 애플리케이션 내에서 인프로세스로 실행되는 자체 MCP 서버 빌드
• 권한: allowedTools 및 disallowedTools로 에이전트가 사용할 수 있는 MCP 도구 제어
• TypeScript SDK 레퍼런스: MCP 구성 옵션을 포함한 전체 API 레퍼런스
• Python SDK 레퍼런스: MCP 구성 옵션을 포함한 전체 API 레퍼런스
• MCP 서버 디렉토리: 데이터베이스, API 등을 위한 사용 가능한 MCP 서버 탐색