​
개요

Model Context Protocol (MCP) 서버는 사용자 정의 도구와 기능으로 Claude Code를 확장합니다. MCP는 외부 프로세스로 실행되거나, HTTP/SSE를 통해 연결되거나, SDK 애플리케이션 내에서 직접 실행될 수 있습니다.

​
구성

​
기본 구성

프로젝트 루트의 .mcp.json에서 MCP 서버를 구성합니다: 
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem"],
      "env": {
        "ALLOWED_PATHS": "/Users/me/projects"
      }
    }
  }
}

​
SDK에서 MCP 서버 사용하기

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

for await (const message of query({
  prompt: "List files in my project",
  options: {
    mcpConfig: ".mcp.json",
    allowedTools: ["mcp__filesystem__list_files"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

​
전송 유형

​
stdio 서버

stdin/stdout을 통해 통신하는 외부 프로세스: 
// .mcp.json 구성
{
  "mcpServers": {
    "my-tool": {
      "command": "node",
      "args": ["./my-mcp-server.js"],
      "env": {
        "DEBUG": "${DEBUG:-false}"
      }
    }
  }
}

​
HTTP/SSE 서버

네트워크 통신을 사용하는 원격 서버: 
// SSE 서버 구성
{
  "mcpServers": {
    "remote-api": {
      "type": "sse",
      "url": "https://api.example.com/mcp/sse",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  }
}

// HTTP 서버 구성
{
  "mcpServers": {
    "http-service": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "headers": {
        "X-API-Key": "${API_KEY}"
      }
    }
  }
}

​
SDK MCP 서버

애플리케이션 내에서 실행되는 인프로세스 서버입니다. 사용자 정의 도구 생성에 대한 자세한 정보는 사용자 정의 도구 가이드를 참조하세요:

​
리소스 관리

MCP 서버는 Claude가 나열하고 읽을 수 있는 리소스를 노출할 수 있습니다: 
import { query } from "@anthropic-ai/claude-agent-sdk";

// 사용 가능한 리소스 나열
for await (const message of query({
  prompt: "What resources are available from the database server?",
  options: {
    mcpConfig: ".mcp.json",
    allowedTools: ["mcp__list_resources", "mcp__read_resource"]
  }
})) {
  if (message.type === "result") console.log(message.result);
}

​
인증

​
환경 변수

// 환경 변수가 포함된 .mcp.json
{
  "mcpServers": {
    "secure-api": {
      "type": "sse",
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}",
        "X-API-Key": "${API_KEY:-default-key}"
      }
    }
  }
}

// 환경 변수 설정
process.env.API_TOKEN = "your-token";
process.env.API_KEY = "your-key";

​
OAuth2 인증

클라이언트 내 OAuth2 MCP 인증은 현재 지원되지 않습니다.

​
오류 처리

MCP 연결 실패를 우아하게 처리합니다: 
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") {
    // MCP 서버 상태 확인
    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");
  }
}

​
관련 리소스