가이드

SDK에서의 MCP

Model Context Protocol 서버를 사용하여 사용자 정의 도구로 Claude Code를 확장하세요

개요

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: "내 프로젝트의 파일들을 나열해줘",
  options: {
    mcpServers: {
      "filesystem": {
        command: "npx",
        args: ["@modelcontextprotocol/server-filesystem"],
        env: {
          ALLOWED_PATHS: "/Users/me/projects"
        }
      }
    },
    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: "데이터베이스 서버에서 사용 가능한 리소스는 무엇인가요?",
  options: {
    mcpServers: {
      "database": {
        command: "npx",
        args: ["@modelcontextprotocol/server-database"]
      }
    },
    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: "데이터 처리",
  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("연결 실패:", failedServers);
    }
  }
  
  if (message.type === "result" && message.subtype === "error_during_execution") {
    console.error("실행 실패");
  }
}

SDK에서의 MCP

Model Context Protocol 서버를 사용하여 사용자 정의 도구로 Claude Code를 확장하세요

개요

구성

기본 구성

프로젝트 루트의 .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: "내 프로젝트의 파일들을 나열해줘",
  options: {
    mcpServers: {
      "filesystem": {
        command: "npx",
        args: ["@modelcontextprotocol/server-filesystem"],
        env: {
          ALLOWED_PATHS: "/Users/me/projects"
        }
      }
    },
    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: "데이터베이스 서버에서 사용 가능한 리소스는 무엇인가요?",
  options: {
    mcpServers: {
      "database": {
        command: "npx",
        args: ["@modelcontextprotocol/server-database"]
      }
    },
    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: "데이터 처리",
  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("연결 실패:", failedServers);
    }
  }
  
  if (message.type === "result" && message.subtype === "error_during_execution") {
    console.error("실행 실패");
  }
}

SDK에서의 MCP

개요

구성

기본 구성

SDK에서 MCP 서버 사용하기

전송 유형

stdio 서버

HTTP/SSE 서버

SDK MCP 서버

리소스 관리

인증

환경 변수

OAuth2 인증

오류 처리

관련 리소스

SDK에서의 MCP

개요

구성

기본 구성

SDK에서 MCP 서버 사용하기

전송 유형

stdio 서버

HTTP/SSE 서버

SDK MCP 서버

리소스 관리

인증

환경 변수

OAuth2 인증

오류 처리

관련 리소스