MessagesMCP

MCP 커넥터

Claude의 "Model Context Protocol", 즉 MCP 커넥터 기능을 사용하면 별도의 MCP 클라이언트 없이 Messages API에서 직접 원격 MCP 서버에 연결할 수 있습니다.

현재 버전: 이 기능을 사용하려면 베타 헤더가 필요합니다: "anthropic-beta": "mcp-client-2025-11-20"

이전 버전(mcp-client-2025-04-04)은 더 이상 사용되지 않습니다. 더 이상 사용되지 않는 버전: mcp-client-2025-04-04를 참조하세요.

이 기능은 Zero Data Retention (ZDR) 대상이 아닙니다. 데이터는 해당 기능의 표준 보존 정책에 따라 보존됩니다.

주요 기능

직접 API 통합: MCP 클라이언트를 구현하지 않고 MCP 서버에 연결
도구 호출 지원: Messages API를 통해 MCP 도구에 접근
유연한 도구 구성: 모든 도구 활성화, 특정 도구 허용 목록 지정, 또는 원치 않는 도구 차단 목록 지정
도구별 구성: 개별 도구를 사용자 지정 설정으로 구성
OAuth 인증: 인증이 필요한 서버를 위한 OAuth Bearer 토큰 지원
다중 서버: 단일 요청에서 여러 MCP 서버에 연결

Claude가 MCP 도구를 사용하는 경우

MCP 서버가 연결되면, Claude는 사용자의 요청이 도구의 설명된 기능에 매핑될 때 해당 도구를 호출합니다. 이는 명시적인 경우("Jira에서 열린 버그 검색")일 수도 있고 암시적인 경우(Jira 서버가 연결된 상태에서 "릴리스를 막고 있는 것이 무엇인가요?")일 수도 있습니다.

Claude는 연결된 서비스에 대한 일반적인 지식 질문에는 MCP 도구를 호출하지 않습니다. Notion 서버가 연결된 상태에서 "Notion 데이터베이스는 어떻게 작동하나요?"라고 물으면 직접 답변하지만, "내 Projects 데이터베이스에 무엇이 있나요?"라고 물으면 도구가 트리거됩니다.

시스템 프롬프트를 통해 Claude가 MCP 도구를 얼마나 적극적으로 호출할지 조정할 수 있습니다. 일반적인 지침과 예시 문구는 Claude가 도구를 사용하는 경우를 참조하세요.

제한 사항

MCP 사양의 기능 세트 중 현재는 도구 호출만 지원됩니다.
서버는 HTTP를 통해 공개적으로 노출되어야 합니다(Streamable HTTP 및 SSE 전송 모두 지원). 로컬 STDIO 서버는 직접 연결할 수 없습니다.
MCP 커넥터는 Claude API, AWS의 Claude Platform, Microsoft Foundry에서 사용할 수 있습니다. 현재 Amazon Bedrock 또는 Vertex AI에서는 사용할 수 없습니다.

Messages API에서 MCP 커넥터 사용하기

MCP 커넥터는 두 가지 구성 요소를 사용합니다:

MCP 서버 정의 (mcp_servers 배열): 서버 연결 세부 정보(URL, 인증)를 정의합니다
MCP Toolset (tools 배열): 활성화할 도구와 구성 방법을 설정합니다

기본 예제

이 예제는 기본 구성으로 MCP 서버의 모든 도구를 활성화합니다:

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=1000,
    messages=[{"role": "user", "content": "What tools do you have available?"}],
    mcp_servers=[
        {
            "type": "url",
            "url": "https://example-server.modelcontextprotocol.io/sse",
            "name": "example-mcp",
            "authorization_token": "YOUR_TOKEN",
        }
    ],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "example-mcp"}],
    betas=["mcp-client-2025-11-20"],
)

print(response)

MCP 서버 구성

mcp_servers 배열의 각 MCP 서버는 연결 세부 정보를 정의합니다:

{
  "type": "url",
  "url": "https://example-server.modelcontextprotocol.io/sse",
  "name": "example-mcp",
  "authorization_token": "YOUR_TOKEN"
}

필드 설명

속성	타입	필수	설명
`type`	string	예	현재 "url"만 지원됩니다.
`url`	string	예	MCP 서버의 URL입니다. https://로 시작해야 합니다.
`name`	string	예	이 MCP 서버의 고유 식별자입니다. `tools` 배열에서 정확히 하나의 MCPToolset에 의해 참조되어야 합니다.
`authorization_token`	string	아니요	MCP 서버에서 요구하는 경우 OAuth 인증 토큰입니다. MCP 사양을 참조하세요.

MCP toolset 구성

MCPToolset은 tools 배열에 위치하며 MCP 서버에서 어떤 도구를 활성화하고 어떻게 구성할지 설정합니다.

기본 구조

{
  "type": "mcp_toolset",
  "mcp_server_name": "example-mcp",
  "default_config": {
    "enabled": true,
    "defer_loading": false
  },
  "configs": {
    "specific_tool_name": {
      "enabled": true,
      "defer_loading": true
    }
  }
}

필드 설명

속성	타입	필수	설명
`type`	string	예	"mcp_toolset"이어야 합니다.
`mcp_server_name`	string	예	`mcp_servers` 배열에 정의된 서버 이름과 일치해야 합니다.
`default_config`	object	아니요	이 세트의 모든 도구에 적용되는 기본 구성입니다. `configs`의 개별 도구 구성이 이 기본값을 재정의합니다.
`configs`	object	아니요	도구별 구성 재정의입니다. 키는 도구 이름이고 값은 구성 객체입니다.
`cache_control`	object	아니요	이 toolset에 대한 프롬프트 캐싱 캐시 중단점 구성입니다.

도구 구성 옵션

각 도구(default_config 또는 configs에서 구성되는지 여부와 관계없이)는 다음 필드를 지원합니다:

속성	타입	기본값	설명
`enabled`	boolean	`true`	이 도구의 활성화 여부입니다.
`defer_loading`	boolean	`false`	true인 경우 도구 설명이 초기에 모델로 전송되지 않습니다. Tool search tool과 함께 사용됩니다.

Anthropic에서 제공하는 도구의 전체 디렉터리와 defer_loading과 같은 선택적 속성은 도구 참조를 참조하세요. 대규모 도구 세트 검색에 대해서는 Tool search tool을 참조하세요.

구성 병합

구성 값은 다음 우선순위(높은 순서에서 낮은 순서)로 병합됩니다:

configs의 도구별 설정
세트 수준의 default_config
시스템 기본값

예제:

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "default_config": {
    "defer_loading": true
  },
  "configs": {
    "search_events": {
      "enabled": false
    }
  }
}

결과:

search_events: enabled: false (configs에서), defer_loading: true (default_config에서)
다른 모든 도구: enabled: true (시스템 기본값), defer_loading: true (default_config에서)

일반적인 구성 패턴

기본 구성으로 모든 도구 활성화

가장 간단한 패턴 - 서버의 모든 도구를 활성화합니다:

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp"
}

허용 목록: 특정 도구만 활성화

기본값으로 enabled: false를 설정한 다음 특정 도구를 명시적으로 활성화합니다:

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "default_config": {
    "enabled": false
  },
  "configs": {
    "search_events": {
      "enabled": true
    },
    "create_event": {
      "enabled": true
    }
  }
}

차단 목록: 특정 도구 비활성화

기본적으로 모든 도구를 활성화한 다음 원치 않는 도구를 명시적으로 비활성화합니다. 읽기 전용 어시스턴트를 구축하거나 상태 변경 전에 사람의 확인 단계를 원하는 경우 쓰기 또는 파괴적인 도구를 차단 목록에 추가하는 것이 권장됩니다:

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "configs": {
    "delete_all_events": {
      "enabled": false
    },
    "share_calendar_publicly": {
      "enabled": false
    }
  }
}

혼합: 도구별 구성이 포함된 허용 목록

허용 목록과 각 도구에 대한 사용자 지정 구성을 결합합니다:

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "default_config": {
    "enabled": false,
    "defer_loading": true
  },
  "configs": {
    "search_events": {
      "enabled": true,
      "defer_loading": false
    },
    "list_events": {
      "enabled": true
    }
  }
}

이 예제에서:

search_events는 defer_loading: false로 활성화됩니다
list_events는 defer_loading: true로 활성화됩니다 (default_config에서 상속됨)
다른 모든 도구는 비활성화됩니다

유효성 검사 규칙

API는 다음 유효성 검사 규칙을 적용합니다:

서버가 존재해야 함: MCPToolset의 mcp_server_name은 mcp_servers 배열에 정의된 서버와 일치해야 합니다
서버가 사용되어야 함: mcp_servers에 정의된 모든 MCP 서버는 정확히 하나의 MCPToolset에 의해 참조되어야 합니다
서버당 고유한 toolset: 각 MCP 서버는 하나의 MCPToolset에 의해서만 참조될 수 있습니다
알 수 없는 도구 이름: configs의 도구 이름이 MCP 서버에 존재하지 않는 경우 백엔드 경고가 기록되지만 오류는 반환되지 않습니다 (MCP 서버는 동적 도구 가용성을 가질 수 있음)

응답 콘텐츠 타입

Claude가 MCP 도구를 사용할 때 응답에는 두 가지 새로운 콘텐츠 블록 타입이 포함됩니다:

MCP tool use 블록

{
  "type": "mcp_tool_use",
  "id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
  "name": "echo",
  "server_name": "example-mcp",
  "input": { "param1": "value1", "param2": "value2" }
}

MCP tool result 블록

{
  "type": "mcp_tool_result",
  "tool_use_id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
  "is_error": false,
  "content": [
    {
      "type": "text",
      "text": "Hello"
    }
  ]
}

다중 MCP 서버

mcp_servers에 여러 서버 정의를 포함하고 tools 배열에 각각에 해당하는 MCPToolset을 포함하여 여러 MCP 서버에 연결할 수 있습니다:

{
  "model": "claude-opus-4-8",
  "max_tokens": 1000,
  "messages": [
    {
      "role": "user",
      "content": "Use tools from both mcp-server-1 and mcp-server-2 to complete this task"
    }
  ],
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.example1.com/sse",
      "name": "mcp-server-1",
      "authorization_token": "TOKEN1"
    },
    {
      "type": "url",
      "url": "https://mcp.example2.com/sse",
      "name": "mcp-server-2",
      "authorization_token": "TOKEN2"
    }
  ],
  "tools": [
    {
      "type": "mcp_toolset",
      "mcp_server_name": "mcp-server-1"
    },
    {
      "type": "mcp_toolset",
      "mcp_server_name": "mcp-server-2",
      "default_config": {
        "defer_loading": true
      }
    }
  ]
}

많은 도구가 사용 가능한 경우 Claude는 도구 이름과 설명을 기반으로 선택합니다. 명확하고 구체적인 도구 설명은 선택 정확도를 향상시킵니다. 대규모 도구 세트(여러 서버에 걸쳐 수십 개의 도구)의 경우, 쿼리당 관련 도구만 표시되도록 Tool search tool과 함께 defer_loading을 활성화하는 것을 고려하세요.

인증

OAuth 인증이 필요한 MCP 서버의 경우 액세스 토큰을 얻어야 합니다. MCP 커넥터 베타는 MCP 서버 정의에서 authorization_token 매개변수 전달을 지원합니다. API 사용자는 API 호출을 하기 전에 OAuth 플로우를 처리하고 액세스 토큰을 얻어야 하며, 필요에 따라 토큰을 갱신해야 합니다.

테스트용 액세스 토큰 얻기

MCP inspector는 테스트 목적으로 액세스 토큰을 얻는 과정을 안내할 수 있습니다.

다음 명령으로 inspector를 실행하세요. 컴퓨터에 Node.js가 설치되어 있어야 합니다.
```
npx @modelcontextprotocol/inspector
```
왼쪽 사이드바에서 "Transport type"으로 "SSE" 또는 "Streamable HTTP"를 선택하세요.
MCP 서버의 URL을 입력하세요.
오른쪽 영역에서 "Need to configure authentication?" 뒤에 있는 "Open Auth Settings" 버튼을 클릭하세요.
"Quick OAuth Flow"를 클릭하고 OAuth 화면에서 인증하세요.
inspector의 "OAuth Flow Progress" 섹션의 단계를 따라 "Authentication complete"에 도달할 때까지 "Continue"를 클릭하세요.
access_token 값을 복사하세요.
MCP 서버 구성의 authorization_token 필드에 붙여넣으세요.

액세스 토큰 사용하기

앞서 설명한 OAuth 플로우 중 하나를 사용하여 액세스 토큰을 얻은 후 MCP 서버 구성에서 사용할 수 있습니다:

{
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://example-server.modelcontextprotocol.io/sse",
      "name": "authenticated-server",
      "authorization_token": "YOUR_ACCESS_TOKEN_HERE"
    }
  ]
}

OAuth 플로우에 대한 자세한 설명은 MCP 사양의 Authorization 섹션을 참조하세요.

클라이언트 측 MCP 헬퍼

자체 MCP 클라이언트 연결을 관리하는 경우(예: 로컬 stdio 서버, MCP 프롬프트 또는 MCP 리소스 사용), SDK는 MCP 타입과 Claude API 타입 간에 변환하는 헬퍼 함수를 제공합니다. 이를 통해 MCP SDK(예: TypeScript MCP SDK)를 Anthropic SDK와 함께 사용할 때 수동 변환 코드가 필요하지 않습니다.

이러한 헬퍼는 Python, TypeScript, Java, Go, Ruby, PHP SDK에서 사용할 수 있습니다. C# SDK에서는 아직 사용할 수 없습니다. 이 섹션의 예제는 TypeScript를 사용합니다. 다른 언어에서는 다음에서 동등한 헬퍼를 가져오세요:

Python: anthropic.lib.tools.mcp (pip install anthropic[mcp]로 설치)
Java: anthropic-java-mcp 모듈의 com.anthropic.mcp.BetaMcp
Go: github.com/anthropics/anthropic-sdk-go/mcp
Ruby: Anthropic::Mcp (mcp gem 필요)
PHP: Anthropic\Lib\Tools\BetaMcp

URL로 접근 가능한 원격 서버가 있고 도구 지원만 필요한 경우 mcp_servers API 매개변수를 사용하세요. 로컬 서버, 프롬프트, 리소스가 필요하거나 기본 SDK로 연결을 더 세밀하게 제어해야 하는 경우 클라이언트 측 헬퍼를 사용하세요.

설치

Anthropic SDK와 MCP SDK를 모두 설치하세요:

npm install @anthropic-ai/sdk @modelcontextprotocol/sdk

사용 가능한 헬퍼

베타 네임스페이스에서 헬퍼를 가져오세요:

import {
  mcpTools,
  mcpMessages,
  mcpResourceToContent,
  mcpResourceToFile
} from "@anthropic-ai/sdk/helpers/beta/mcp";

헬퍼	설명
`mcpTools(tools, mcpClient)`	`client.beta.messages.toolRunner()`와 함께 사용하기 위해 MCP 도구를 Claude API 도구로 변환합니다
`mcpMessages(messages)`	MCP 프롬프트 메시지를 Claude API 메시지 형식으로 변환합니다
`mcpResourceToContent(resource)`	MCP 리소스를 Claude API 콘텐츠 블록으로 변환합니다
`mcpResourceToFile(resource)`	MCP 리소스를 업로드용 파일 객체로 변환합니다

MCP 도구 사용하기

도구 실행을 자동으로 처리하는 SDK의 tool runner와 함께 사용하기 위해 MCP 도구를 변환하세요:

import { mcpTools } from "@anthropic-ai/sdk/helpers/beta/mcp";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const anthropic = new Anthropic();

// MCP 서버에 연결
const transport = new StdioClientTransport({ command: "mcp-server", args: [] });
const mcpClient = new Client({ name: "my-client", version: "1.0.0" });
await mcpClient.connect(transport);

// 도구를 나열하고 Claude API 용으로 변환
const { tools } = await mcpClient.listTools();
const finalMessage = await anthropic.beta.messages.toolRunner({
  model: "claude-opus-4-8",
  max_tokens: 1024,
  messages: [{ role: "user", content: "What tools do you have available?" }],
  tools: mcpTools(tools, mcpClient)
});

console.log(finalMessage);

MCP 프롬프트 사용하기

MCP 프롬프트 메시지를 Claude API 메시지 형식으로 변환하세요:

import { mcpMessages } from "@anthropic-ai/sdk/helpers/beta/mcp";

const { messages } = await mcpClient.getPrompt({ name: "my-prompt" });
const response = await anthropic.beta.messages.create({
  model: "claude-opus-4-8",
  max_tokens: 1024,
  messages: mcpMessages(messages)
});

console.log(response);

MCP 리소스 사용하기

MCP 리소스를 메시지에 포함할 콘텐츠 블록으로 변환하거나 업로드용 파일 객체로 변환하세요:

import { mcpResourceToContent, mcpResourceToFile } from "@anthropic-ai/sdk/helpers/beta/mcp";

// 메시지의 콘텐츠 블록으로
const resource = await mcpClient.readResource({ uri: "file:///path/to/doc.txt" });
await anthropic.beta.messages.create({
  model: "claude-opus-4-8",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content: [
        mcpResourceToContent(resource),
        { type: "text", text: "Summarize this document" }
      ]
    }
  ]
});

// 파일 업로드로
const fileResource = await mcpClient.readResource({ uri: "file:///path/to/data.json" });
await anthropic.beta.files.upload({ file: mcpResourceToFile(fileResource) });

오류 처리

변환 함수는 MCP 값이 Claude API에서 지원되지 않는 경우 UnsupportedMCPValueError를 발생시킵니다. 이는 지원되지 않는 콘텐츠 타입, MIME 타입 또는 HTTP가 아닌 리소스 링크에서 발생할 수 있습니다.

배치 요청

Message Batches API 요청에 mcp_servers를 포함할 수 있습니다. Batches API를 통한 MCP 도구 호출은 일반 Messages API 요청과 동일하게 가격이 책정됩니다.

데이터 보존

MCP 커넥터는 ZDR 계약의 적용을 받지 않습니다. 도구 정의 및 실행 결과를 포함하여 MCP 서버와 교환되는 데이터는 Anthropic의 표준 데이터 보존 정책에 따라 보존됩니다.

모든 기능에 대한 ZDR 적격성은 API 및 데이터 보존을 참조하세요.

마이그레이션 가이드

더 이상 사용되지 않는 mcp-client-2025-04-04 베타 헤더를 사용하고 있다면 이 가이드를 따라 새 버전으로 마이그레이션하세요.

주요 변경 사항

새 베타 헤더: mcp-client-2025-04-04에서 mcp-client-2025-11-20으로 변경
도구 구성 이동: 도구 구성이 이제 MCP 서버 정의가 아닌 tools 배열에 MCPToolset 객체로 위치합니다
더 유연한 구성: 새 패턴은 허용 목록, 차단 목록 및 도구별 구성을 지원합니다

마이그레이션 단계

이전 (더 이상 사용되지 않음):

{
  "model": "claude-opus-4-8",
  "max_tokens": 1000,
  "messages": [
    // ...
  ],
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.example.com/sse",
      "name": "example-mcp",
      "authorization_token": "YOUR_TOKEN",
      "tool_configuration": {
        "enabled": true,
        "allowed_tools": ["tool1", "tool2"]
      }
    }
  ]
}

이후 (현재):

{
  "model": "claude-opus-4-8",
  "max_tokens": 1000,
  "messages": [
    // ...
  ],
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.example.com/sse",
      "name": "example-mcp",
      "authorization_token": "YOUR_TOKEN"
    }
  ],
  "tools": [
    {
      "type": "mcp_toolset",
      "mcp_server_name": "example-mcp",
      "default_config": {
        "enabled": false
      },
      "configs": {
        "tool1": {
          "enabled": true
        },
        "tool2": {
          "enabled": true
        }
      }
    }
  ]
}

일반적인 마이그레이션 패턴

이전 패턴	새 패턴
`tool_configuration` 없음 (모든 도구 활성화)	`default_config` 또는 `configs`가 없는 MCPToolset
`tool_configuration.enabled: false`	`default_config.enabled: false`가 있는 MCPToolset
`tool_configuration.allowed_tools: [...]`	`default_config.enabled: false`와 `configs`에서 특정 도구가 활성화된 MCPToolset

더 이상 사용되지 않는 버전: mcp-client-2025-04-04

이 버전은 더 이상 사용되지 않습니다. 앞의 마이그레이션 가이드를 사용하여 mcp-client-2025-11-20으로 마이그레이션하세요.

이전 버전의 MCP 커넥터는 도구 구성을 MCP 서버 정의에 직접 포함했습니다:

{
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://example-server.modelcontextprotocol.io/sse",
      "name": "example-mcp",
      "authorization_token": "YOUR_TOKEN",
      "tool_configuration": {
        "enabled": true,
        "allowed_tools": ["example_tool_1", "example_tool_2"]
      }
    }
  ]
}

더 이상 사용되지 않는 필드 설명

속성	타입	설명
`tool_configuration`	object	더 이상 사용되지 않음: 대신 `tools` 배열에서 MCPToolset을 사용하세요
`tool_configuration.enabled`	boolean	더 이상 사용되지 않음: MCPToolset에서 `default_config.enabled`를 사용하세요
`tool_configuration.allowed_tools`	array	더 이상 사용되지 않음: MCPToolset에서 `configs`를 사용한 허용 목록 패턴을 사용하세요

Was this page helpful?

MessagesMCP

MCP 커넥터

Claude의 "Model Context Protocol", 즉 MCP 커넥터 기능을 사용하면 별도의 MCP 클라이언트 없이 Messages API에서 직접 원격 MCP 서버에 연결할 수 있습니다.

현재 버전: 이 기능을 사용하려면 베타 헤더가 필요합니다: "anthropic-beta": "mcp-client-2025-11-20"

이전 버전(mcp-client-2025-04-04)은 더 이상 사용되지 않습니다. 더 이상 사용되지 않는 버전: mcp-client-2025-04-04를 참조하세요.

이 기능은 Zero Data Retention (ZDR) 대상이 아닙니다. 데이터는 해당 기능의 표준 보존 정책에 따라 보존됩니다.

주요 기능

직접 API 통합: MCP 클라이언트를 구현하지 않고 MCP 서버에 연결
도구 호출 지원: Messages API를 통해 MCP 도구에 접근
유연한 도구 구성: 모든 도구 활성화, 특정 도구 허용 목록 지정, 또는 원치 않는 도구 차단 목록 지정
도구별 구성: 개별 도구를 사용자 지정 설정으로 구성
OAuth 인증: 인증이 필요한 서버를 위한 OAuth Bearer 토큰 지원
다중 서버: 단일 요청에서 여러 MCP 서버에 연결

Claude가 MCP 도구를 사용하는 경우

제한 사항

MCP 사양의 기능 세트 중 현재는 도구 호출만 지원됩니다.
서버는 HTTP를 통해 공개적으로 노출되어야 합니다(Streamable HTTP 및 SSE 전송 모두 지원). 로컬 STDIO 서버는 직접 연결할 수 없습니다.
MCP 커넥터는 Claude API, AWS의 Claude Platform, Microsoft Foundry에서 사용할 수 있습니다. 현재 Amazon Bedrock 또는 Vertex AI에서는 사용할 수 없습니다.

Messages API에서 MCP 커넥터 사용하기

MCP 커넥터는 두 가지 구성 요소를 사용합니다:

MCP 서버 정의 (mcp_servers 배열): 서버 연결 세부 정보(URL, 인증)를 정의합니다
MCP Toolset (tools 배열): 활성화할 도구와 구성 방법을 설정합니다

기본 예제

이 예제는 기본 구성으로 MCP 서버의 모든 도구를 활성화합니다:

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=1000,
    messages=[{"role": "user", "content": "What tools do you have available?"}],
    mcp_servers=[
        {
            "type": "url",
            "url": "https://example-server.modelcontextprotocol.io/sse",
            "name": "example-mcp",
            "authorization_token": "YOUR_TOKEN",
        }
    ],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "example-mcp"}],
    betas=["mcp-client-2025-11-20"],
)

print(response)

MCP 서버 구성

mcp_servers 배열의 각 MCP 서버는 연결 세부 정보를 정의합니다:

{
  "type": "url",
  "url": "https://example-server.modelcontextprotocol.io/sse",
  "name": "example-mcp",
  "authorization_token": "YOUR_TOKEN"
}

필드 설명

속성	타입	필수	설명
`type`	string	예	현재 "url"만 지원됩니다.
`url`	string	예	MCP 서버의 URL입니다. https://로 시작해야 합니다.
`name`	string	예	이 MCP 서버의 고유 식별자입니다. `tools` 배열에서 정확히 하나의 MCPToolset에 의해 참조되어야 합니다.
`authorization_token`	string	아니요	MCP 서버에서 요구하는 경우 OAuth 인증 토큰입니다. MCP 사양을 참조하세요.

MCP toolset 구성

MCPToolset은 tools 배열에 위치하며 MCP 서버에서 어떤 도구를 활성화하고 어떻게 구성할지 설정합니다.

기본 구조

{
  "type": "mcp_toolset",
  "mcp_server_name": "example-mcp",
  "default_config": {
    "enabled": true,
    "defer_loading": false
  },
  "configs": {
    "specific_tool_name": {
      "enabled": true,
      "defer_loading": true
    }
  }
}

필드 설명

속성	타입	필수	설명
`type`	string	예	"mcp_toolset"이어야 합니다.
`mcp_server_name`	string	예	`mcp_servers` 배열에 정의된 서버 이름과 일치해야 합니다.
`default_config`	object	아니요	이 세트의 모든 도구에 적용되는 기본 구성입니다. `configs`의 개별 도구 구성이 이 기본값을 재정의합니다.
`configs`	object	아니요	도구별 구성 재정의입니다. 키는 도구 이름이고 값은 구성 객체입니다.
`cache_control`	object	아니요	이 toolset에 대한 프롬프트 캐싱 캐시 중단점 구성입니다.

도구 구성 옵션

각 도구(default_config 또는 configs에서 구성되는지 여부와 관계없이)는 다음 필드를 지원합니다:

속성	타입	기본값	설명
`enabled`	boolean	`true`	이 도구의 활성화 여부입니다.
`defer_loading`	boolean	`false`	true인 경우 도구 설명이 초기에 모델로 전송되지 않습니다. Tool search tool과 함께 사용됩니다.

구성 병합

구성 값은 다음 우선순위(높은 순서에서 낮은 순서)로 병합됩니다:

configs의 도구별 설정
세트 수준의 default_config
시스템 기본값

예제:

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "default_config": {
    "defer_loading": true
  },
  "configs": {
    "search_events": {
      "enabled": false
    }
  }
}

결과:

search_events: enabled: false (configs에서), defer_loading: true (default_config에서)
다른 모든 도구: enabled: true (시스템 기본값), defer_loading: true (default_config에서)

일반적인 구성 패턴

기본 구성으로 모든 도구 활성화

가장 간단한 패턴 - 서버의 모든 도구를 활성화합니다:

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp"
}

허용 목록: 특정 도구만 활성화

기본값으로 enabled: false를 설정한 다음 특정 도구를 명시적으로 활성화합니다:

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "default_config": {
    "enabled": false
  },
  "configs": {
    "search_events": {
      "enabled": true
    },
    "create_event": {
      "enabled": true
    }
  }
}

차단 목록: 특정 도구 비활성화

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "configs": {
    "delete_all_events": {
      "enabled": false
    },
    "share_calendar_publicly": {
      "enabled": false
    }
  }
}

혼합: 도구별 구성이 포함된 허용 목록

허용 목록과 각 도구에 대한 사용자 지정 구성을 결합합니다:

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "default_config": {
    "enabled": false,
    "defer_loading": true
  },
  "configs": {
    "search_events": {
      "enabled": true,
      "defer_loading": false
    },
    "list_events": {
      "enabled": true
    }
  }
}

이 예제에서:

search_events는 defer_loading: false로 활성화됩니다
list_events는 defer_loading: true로 활성화됩니다 (default_config에서 상속됨)
다른 모든 도구는 비활성화됩니다

유효성 검사 규칙

API는 다음 유효성 검사 규칙을 적용합니다:

서버가 존재해야 함: MCPToolset의 mcp_server_name은 mcp_servers 배열에 정의된 서버와 일치해야 합니다
서버가 사용되어야 함: mcp_servers에 정의된 모든 MCP 서버는 정확히 하나의 MCPToolset에 의해 참조되어야 합니다
서버당 고유한 toolset: 각 MCP 서버는 하나의 MCPToolset에 의해서만 참조될 수 있습니다
알 수 없는 도구 이름: configs의 도구 이름이 MCP 서버에 존재하지 않는 경우 백엔드 경고가 기록되지만 오류는 반환되지 않습니다 (MCP 서버는 동적 도구 가용성을 가질 수 있음)

응답 콘텐츠 타입

Claude가 MCP 도구를 사용할 때 응답에는 두 가지 새로운 콘텐츠 블록 타입이 포함됩니다:

MCP tool use 블록

{
  "type": "mcp_tool_use",
  "id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
  "name": "echo",
  "server_name": "example-mcp",
  "input": { "param1": "value1", "param2": "value2" }
}

MCP tool result 블록

{
  "type": "mcp_tool_result",
  "tool_use_id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
  "is_error": false,
  "content": [
    {
      "type": "text",
      "text": "Hello"
    }
  ]
}

다중 MCP 서버

mcp_servers에 여러 서버 정의를 포함하고 tools 배열에 각각에 해당하는 MCPToolset을 포함하여 여러 MCP 서버에 연결할 수 있습니다:

{
  "model": "claude-opus-4-8",
  "max_tokens": 1000,
  "messages": [
    {
      "role": "user",
      "content": "Use tools from both mcp-server-1 and mcp-server-2 to complete this task"
    }
  ],
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.example1.com/sse",
      "name": "mcp-server-1",
      "authorization_token": "TOKEN1"
    },
    {
      "type": "url",
      "url": "https://mcp.example2.com/sse",
      "name": "mcp-server-2",
      "authorization_token": "TOKEN2"
    }
  ],
  "tools": [
    {
      "type": "mcp_toolset",
      "mcp_server_name": "mcp-server-1"
    },
    {
      "type": "mcp_toolset",
      "mcp_server_name": "mcp-server-2",
      "default_config": {
        "defer_loading": true
      }
    }
  ]
}

인증

테스트용 액세스 토큰 얻기

MCP inspector는 테스트 목적으로 액세스 토큰을 얻는 과정을 안내할 수 있습니다.

다음 명령으로 inspector를 실행하세요. 컴퓨터에 Node.js가 설치되어 있어야 합니다.
```
npx @modelcontextprotocol/inspector
```
왼쪽 사이드바에서 "Transport type"으로 "SSE" 또는 "Streamable HTTP"를 선택하세요.
MCP 서버의 URL을 입력하세요.
오른쪽 영역에서 "Need to configure authentication?" 뒤에 있는 "Open Auth Settings" 버튼을 클릭하세요.
"Quick OAuth Flow"를 클릭하고 OAuth 화면에서 인증하세요.
inspector의 "OAuth Flow Progress" 섹션의 단계를 따라 "Authentication complete"에 도달할 때까지 "Continue"를 클릭하세요.
access_token 값을 복사하세요.
MCP 서버 구성의 authorization_token 필드에 붙여넣으세요.

액세스 토큰 사용하기

앞서 설명한 OAuth 플로우 중 하나를 사용하여 액세스 토큰을 얻은 후 MCP 서버 구성에서 사용할 수 있습니다:

{
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://example-server.modelcontextprotocol.io/sse",
      "name": "authenticated-server",
      "authorization_token": "YOUR_ACCESS_TOKEN_HERE"
    }
  ]
}

OAuth 플로우에 대한 자세한 설명은 MCP 사양의 Authorization 섹션을 참조하세요.

클라이언트 측 MCP 헬퍼

Python: anthropic.lib.tools.mcp (pip install anthropic[mcp]로 설치)
Java: anthropic-java-mcp 모듈의 com.anthropic.mcp.BetaMcp
Go: github.com/anthropics/anthropic-sdk-go/mcp
Ruby: Anthropic::Mcp (mcp gem 필요)
PHP: Anthropic\Lib\Tools\BetaMcp

설치

Anthropic SDK와 MCP SDK를 모두 설치하세요:

npm install @anthropic-ai/sdk @modelcontextprotocol/sdk

사용 가능한 헬퍼

베타 네임스페이스에서 헬퍼를 가져오세요:

import {
  mcpTools,
  mcpMessages,
  mcpResourceToContent,
  mcpResourceToFile
} from "@anthropic-ai/sdk/helpers/beta/mcp";

헬퍼	설명
`mcpTools(tools, mcpClient)`	`client.beta.messages.toolRunner()`와 함께 사용하기 위해 MCP 도구를 Claude API 도구로 변환합니다
`mcpMessages(messages)`	MCP 프롬프트 메시지를 Claude API 메시지 형식으로 변환합니다
`mcpResourceToContent(resource)`	MCP 리소스를 Claude API 콘텐츠 블록으로 변환합니다
`mcpResourceToFile(resource)`	MCP 리소스를 업로드용 파일 객체로 변환합니다

MCP 도구 사용하기

도구 실행을 자동으로 처리하는 SDK의 tool runner와 함께 사용하기 위해 MCP 도구를 변환하세요:

import { mcpTools } from "@anthropic-ai/sdk/helpers/beta/mcp";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const anthropic = new Anthropic();

// MCP 서버에 연결
const transport = new StdioClientTransport({ command: "mcp-server", args: [] });
const mcpClient = new Client({ name: "my-client", version: "1.0.0" });
await mcpClient.connect(transport);

// 도구를 나열하고 Claude API 용으로 변환
const { tools } = await mcpClient.listTools();
const finalMessage = await anthropic.beta.messages.toolRunner({
  model: "claude-opus-4-8",
  max_tokens: 1024,
  messages: [{ role: "user", content: "What tools do you have available?" }],
  tools: mcpTools(tools, mcpClient)
});

console.log(finalMessage);

MCP 프롬프트 사용하기

MCP 프롬프트 메시지를 Claude API 메시지 형식으로 변환하세요:

import { mcpMessages } from "@anthropic-ai/sdk/helpers/beta/mcp";

const { messages } = await mcpClient.getPrompt({ name: "my-prompt" });
const response = await anthropic.beta.messages.create({
  model: "claude-opus-4-8",
  max_tokens: 1024,
  messages: mcpMessages(messages)
});

console.log(response);

MCP 리소스 사용하기

MCP 리소스를 메시지에 포함할 콘텐츠 블록으로 변환하거나 업로드용 파일 객체로 변환하세요:

import { mcpResourceToContent, mcpResourceToFile } from "@anthropic-ai/sdk/helpers/beta/mcp";

// 메시지의 콘텐츠 블록으로
const resource = await mcpClient.readResource({ uri: "file:///path/to/doc.txt" });
await anthropic.beta.messages.create({
  model: "claude-opus-4-8",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content: [
        mcpResourceToContent(resource),
        { type: "text", text: "Summarize this document" }
      ]
    }
  ]
});

// 파일 업로드로
const fileResource = await mcpClient.readResource({ uri: "file:///path/to/data.json" });
await anthropic.beta.files.upload({ file: mcpResourceToFile(fileResource) });

오류 처리

배치 요청

Message Batches API 요청에 mcp_servers를 포함할 수 있습니다. Batches API를 통한 MCP 도구 호출은 일반 Messages API 요청과 동일하게 가격이 책정됩니다.

데이터 보존

모든 기능에 대한 ZDR 적격성은 API 및 데이터 보존을 참조하세요.

마이그레이션 가이드

더 이상 사용되지 않는 mcp-client-2025-04-04 베타 헤더를 사용하고 있다면 이 가이드를 따라 새 버전으로 마이그레이션하세요.

주요 변경 사항

새 베타 헤더: mcp-client-2025-04-04에서 mcp-client-2025-11-20으로 변경
도구 구성 이동: 도구 구성이 이제 MCP 서버 정의가 아닌 tools 배열에 MCPToolset 객체로 위치합니다
더 유연한 구성: 새 패턴은 허용 목록, 차단 목록 및 도구별 구성을 지원합니다

마이그레이션 단계

이전 (더 이상 사용되지 않음):

{
  "model": "claude-opus-4-8",
  "max_tokens": 1000,
  "messages": [
    // ...
  ],
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.example.com/sse",
      "name": "example-mcp",
      "authorization_token": "YOUR_TOKEN",
      "tool_configuration": {
        "enabled": true,
        "allowed_tools": ["tool1", "tool2"]
      }
    }
  ]
}

이후 (현재):

{
  "model": "claude-opus-4-8",
  "max_tokens": 1000,
  "messages": [
    // ...
  ],
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.example.com/sse",
      "name": "example-mcp",
      "authorization_token": "YOUR_TOKEN"
    }
  ],
  "tools": [
    {
      "type": "mcp_toolset",
      "mcp_server_name": "example-mcp",
      "default_config": {
        "enabled": false
      },
      "configs": {
        "tool1": {
          "enabled": true
        },
        "tool2": {
          "enabled": true
        }
      }
    }
  ]
}

일반적인 마이그레이션 패턴

이전 패턴	새 패턴
`tool_configuration` 없음 (모든 도구 활성화)	`default_config` 또는 `configs`가 없는 MCPToolset
`tool_configuration.enabled: false`	`default_config.enabled: false`가 있는 MCPToolset
`tool_configuration.allowed_tools: [...]`	`default_config.enabled: false`와 `configs`에서 특정 도구가 활성화된 MCPToolset

더 이상 사용되지 않는 버전: mcp-client-2025-04-04

이 버전은 더 이상 사용되지 않습니다. 앞의 마이그레이션 가이드를 사용하여 mcp-client-2025-11-20으로 마이그레이션하세요.

이전 버전의 MCP 커넥터는 도구 구성을 MCP 서버 정의에 직접 포함했습니다:

{
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://example-server.modelcontextprotocol.io/sse",
      "name": "example-mcp",
      "authorization_token": "YOUR_TOKEN",
      "tool_configuration": {
        "enabled": true,
        "allowed_tools": ["example_tool_1", "example_tool_2"]
      }
    }
  ]
}

더 이상 사용되지 않는 필드 설명

속성	타입	설명
`tool_configuration`	object	더 이상 사용되지 않음: 대신 `tools` 배열에서 MCPToolset을 사용하세요
`tool_configuration.enabled`	boolean	더 이상 사용되지 않음: MCPToolset에서 `default_config.enabled`를 사용하세요
`tool_configuration.allowed_tools`	array	더 이상 사용되지 않음: MCPToolset에서 `configs`를 사용한 허용 목록 패턴을 사용하세요

Was this page helpful?

주요 기능

Claude가 MCP 도구를 사용하는 경우

제한 사항

Messages API에서 MCP 커넥터 사용하기

기본 예제

MCP 서버 구성

필드 설명

MCP toolset 구성

기본 구조

필드 설명

도구 구성 옵션

구성 병합

일반적인 구성 패턴

기본 구성으로 모든 도구 활성화

허용 목록: 특정 도구만 활성화

차단 목록: 특정 도구 비활성화

혼합: 도구별 구성이 포함된 허용 목록

유효성 검사 규칙

응답 콘텐츠 타입

MCP tool use 블록

MCP tool result 블록

다중 MCP 서버

인증

테스트용 액세스 토큰 얻기

액세스 토큰 사용하기

클라이언트 측 MCP 헬퍼

설치

사용 가능한 헬퍼

MCP 도구 사용하기

MCP 프롬프트 사용하기

MCP 리소스 사용하기

오류 처리

배치 요청

데이터 보존

마이그레이션 가이드

주요 변경 사항

마이그레이션 단계

일반적인 마이그레이션 패턴

더 이상 사용되지 않는 버전: mcp-client-2025-04-04

더 이상 사용되지 않는 필드 설명

주요 기능

Claude가 MCP 도구를 사용하는 경우

제한 사항

Messages API에서 MCP 커넥터 사용하기

기본 예제

MCP 서버 구성

필드 설명

MCP toolset 구성

기본 구조

필드 설명

도구 구성 옵션

구성 병합

일반적인 구성 패턴

기본 구성으로 모든 도구 활성화

허용 목록: 특정 도구만 활성화

차단 목록: 특정 도구 비활성화

혼합: 도구별 구성이 포함된 허용 목록

유효성 검사 규칙

응답 콘텐츠 타입

MCP tool use 블록

MCP tool result 블록

다중 MCP 서버

인증

테스트용 액세스 토큰 얻기

액세스 토큰 사용하기

클라이언트 측 MCP 헬퍼

설치

사용 가능한 헬퍼

MCP 도구 사용하기

MCP 프롬프트 사용하기

MCP 리소스 사용하기

오류 처리

배치 요청

데이터 보존

마이그레이션 가이드

주요 변경 사항

마이그레이션 단계

일반적인 마이그레이션 패턴

더 이상 사용되지 않는 버전: mcp-client-2025-04-04

더 이상 사용되지 않는 필드 설명

주요 기능

Claude가 MCP 도구를 사용하는 경우

제한 사항

Messages API에서 MCP 커넥터 사용하기

기본 예제

MCP 서버 구성

필드 설명

MCP toolset 구성

기본 구조

필드 설명

도구 구성 옵션

구성 병합

일반적인 구성 패턴

기본 구성으로 모든 도구 활성화

허용 목록: 특정 도구만 활성화

차단 목록: 특정 도구 비활성화

혼합: 도구별 구성이 포함된 허용 목록

유효성 검사 규칙

응답 콘텐츠 타입

MCP tool use 블록

MCP tool result 블록

다중 MCP 서버

인증

테스트용 액세스 토큰 얻기

액세스 토큰 사용하기

클라이언트 측 MCP 헬퍼

설치

사용 가능한 헬퍼

MCP 도구 사용하기

MCP 프롬프트 사용하기

MCP 리소스 사용하기

오류 처리

배치 요청

데이터 보존

마이그레이션 가이드

주요 변경 사항

마이그레이션 단계

일반적인 마이그레이션 패턴

더 이상 사용되지 않는 버전: mcp-client-2025-04-04

더 이상 사용되지 않는 필드 설명

주요 기능

Claude가 MCP 도구를 사용하는 경우

제한 사항

Messages API에서 MCP 커넥터 사용하기

기본 예제

MCP 서버 구성

필드 설명

MCP toolset 구성

기본 구조

필드 설명

도구 구성 옵션

구성 병합

일반적인 구성 패턴

기본 구성으로 모든 도구 활성화

허용 목록: 특정 도구만 활성화

차단 목록: 특정 도구 비활성화

혼합: 도구별 구성이 포함된 허용 목록

유효성 검사 규칙

응답 콘텐츠 타입

MCP tool use 블록

MCP tool result 블록

다중 MCP 서버

인증

테스트용 액세스 토큰 얻기

액세스 토큰 사용하기

클라이언트 측 MCP 헬퍼

설치

사용 가능한 헬퍼

MCP 도구 사용하기

MCP 프롬프트 사용하기

MCP 리소스 사용하기

오류 처리

배치 요청

데이터 보존

마이그레이션 가이드

주요 변경 사항

마이그레이션 단계

일반적인 마이그레이션 패턴

더 이상 사용되지 않는 버전: mcp-client-2025-04-04

더 이상 사용되지 않는 필드 설명