---
title: MCP 커넥터
url: https://platform.claude.com/docs/ko/agents-and-tools/mcp-connector
description: MCP 클라이언트 없이 Messages API에서 원격 MCP 서버에 직접 연결하고, 개별 도구를 허용 목록에 추가하거나 차단 목록에 추가하거나 구성할 수 있습니다.
featureMetadata:
status: beta
betaHeader: mcp-client-2025-11-20
zdr: not-eligible
supportedPlatforms:
Claude API: beta
Claude Platform on AWS: beta
Microsoft Foundry: beta
---
Claude의 "Model Context Protocol", 즉 MCP 커넥터 기능을 사용하면 별도의 MCP 클라이언트 없이 Messages API에서 원격 MCP 서버에 직접 연결할 수 있습니다.
이 기능의 이전 버전(`mcp-client-2025-04-04`)은 지원 중단되었습니다. [지원 중단된 버전: mcp-client-2025-04-04](https://platform.claude.com/docs/ko/agents-and-tools/mcp-connector#deprecated-version-mcp-client-2025-04-04)를 참조하세요.
## 주요 기능
* **직접 API 통합:** MCP 클라이언트를 구현하지 않고 MCP 서버에 연결
* **도구 호출 지원:** Messages API를 통해 MCP 도구에 접근
* **유연한 도구 구성:** 모든 도구를 활성화하거나, 특정 도구를 허용 목록에 추가하거나, 원하지 않는 도구를 차단 목록에 추가
* **도구별 구성:** 사용자 지정 설정으로 개별 도구 구성
* **OAuth 인증:** 인증이 필요한 서버를 위한 OAuth Bearer 토큰 지원
* **다중 서버:** 단일 요청에서 여러 MCP 서버에 연결
## Claude가 MCP 도구를 사용하는 경우
MCP 서버가 연결되면, Claude는 사용자의 요청이 도구에 설명된 기능과 일치할 때 해당 도구를 호출합니다. 이는 명시적일 수도 있고("Jira에서 열려 있는 버그를 검색해 줘"), 암시적일 수도 있습니다(Jira 서버가 연결된 상태에서 "릴리스를 막고 있는 게 뭐야?").
Claude는 연결된 서비스에 대한 일반 지식 질문에는 MCP 도구를 호출하지 **않습니다**. Notion 서버가 연결된 상태에서 "Notion 데이터베이스는 어떻게 작동해?"라고 물으면 직접 답변하고, "내 Projects 데이터베이스에 뭐가 있어?"라고 물으면 도구가 트리거됩니다.
"system prompt"(시스템 프롬프트)를 통해 Claude가 MCP 도구를 얼마나 적극적으로 호출할지 조정할 수 있습니다. 일반적인 지침과 예시 문구는 [Claude가 도구를 사용하는 경우](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/overview#when-claude-uses-tools)를 참조하세요.
## 제한 사항
* [MCP 사양](https://modelcontextprotocol.io/introduction#explore-mcp)의 기능 중 현재는 [도구 호출](https://modelcontextprotocol.io/docs/concepts/tools)만 지원됩니다.
* 서버는 HTTP를 통해 공개적으로 노출되어야 합니다(Streamable HTTP 및 SSE 전송 모두 지원). 로컬 STDIO 서버는 직접 연결할 수 없습니다.
## Messages API에서 MCP 커넥터 사용하기
MCP 커넥터는 두 가지 구성 요소를 사용합니다:
1. **MCP 서버 정의** (`mcp_servers` 배열): 서버 연결 세부 정보(URL, 인증)를 정의합니다
2. **MCP 도구 세트** (`tools` 배열): 활성화할 도구와 구성 방법을 설정합니다
### 기본 예시
이 예시는 기본 구성으로 MCP 서버의 모든 도구를 활성화합니다:
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "Content-Type: application/json" \
-H "X-API-Key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: mcp-client-2025-11-20" \
-d '{
"model": "claude-opus-5-5",
"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"
}
]
}'
```
```bash CLI
ant beta:messages create --beta mcp-client-2025-11-20 <<'YAML'
model: claude-opus-5-5
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
YAML
```
```python Python
client = anthropic.Anthropic()
response = client.beta.messages.create(
model="claude-opus-5-5",
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)
```
```typescript TypeScript
const anthropic = new Anthropic();
const response = await anthropic.beta.messages.create({
model: "claude-opus-5-5",
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"]
});
console.log(response);
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1000,
Messages = new List
{
new() { Role = Role.User, Content = "What tools do you have available?" }
},
McpServers = new List
{
new()
{
Url = "https://example-server.modelcontextprotocol.io/sse",
Name = "example-mcp",
AuthorizationToken = "YOUR_TOKEN"
}
},
Tools = new List
{
new BetaMcpToolset("example-mcp")
},
Betas = [AnthropicBeta.McpClient2025_11_20]
};
var message = await client.Beta.Messages.Create(parameters);
Console.WriteLine(message);
```
```go Go
client := anthropic.NewClient()
response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1000,
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("What tools do you have available?")),
},
MCPServers: []anthropic.BetaRequestMCPServerURLDefinitionParam{
{
URL: "https://example-server.modelcontextprotocol.io/sse",
Name: "example-mcp",
AuthorizationToken: anthropic.String("YOUR_TOKEN"),
},
},
Tools: []anthropic.BetaToolUnionParam{
{OfMCPToolset: &anthropic.BetaMCPToolsetParam{
MCPServerName: "example-mcp",
}},
},
Betas: []anthropic.AnthropicBeta{
anthropic.AnthropicBetaMCPClient2025_11_20,
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
```
```java Java
import com.anthropic.models.beta.messages.BetaMcpToolset;
// ...
import com.anthropic.models.beta.messages.BetaRequestMcpServerUrlDefinition;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1000L)
.addUserMessage("What tools do you have available?")
.addMcpServer(BetaRequestMcpServerUrlDefinition.builder()
.url("https://example-server.modelcontextprotocol.io/sse")
.name("example-mcp")
.authorizationToken("YOUR_TOKEN")
.build())
.addTool(BetaMcpToolset.builder()
.mcpServerName("example-mcp")
.build())
.addBeta(AnthropicBeta.MCP_CLIENT_2025_11_20)
.build();
BetaMessage response = client.beta().messages().create(params);
IO.println(response);
}
```
```php PHP
$client = new Client();
$message = $client->beta->messages->create(
maxTokens: 1000,
messages: [
['role' => 'user', 'content' => 'What tools do you have available?']
],
model: 'claude-opus-5-5',
mcpServers: [
[
'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'],
);
echo $message;
```
```ruby Ruby
client = Anthropic::Client.new
response = client.beta.messages.create(
model: "claude-opus-5-5",
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"]
)
puts response
```
## MCP 서버 구성
`mcp_servers` 배열의 각 MCP 서버는 연결 세부 정보를 정의합니다:
```json
{
"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 인증 토큰입니다. 토큰을 얻는 방법은 [인증](https://platform.claude.com/docs/ko/agents-and-tools/mcp-connector#authentication)을, 프로토콜 세부 사항은 [MCP 사양](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization)을 참조하세요. |
## MCP 도구 세트 구성
MCPToolset은 `tools` 배열에 위치하며, MCP 서버의 어떤 도구를 활성화할지와 어떻게 구성할지를 설정합니다.
### 기본 구조
```json
{
"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 | 아니요 | 이 도구 세트에 대한 [프롬프트 캐싱](https://platform.claude.com/docs/ko/build-with-claude/prompt-caching) 캐시 중단점 구성입니다. |
`mcp-client-2026-09-15` 베타 헤더를 사용하면 MCPToolset은 서버의 도구 목록을 고정한 복사본인 `tools`도 허용합니다. [MCP 서버의 도구 목록 고정하기](https://platform.claude.com/docs/ko/agents-and-tools/mcp-connector#pin-mcp-tool-list)를 참조하세요.
### 도구 구성 옵션
각 도구(`default_config`에서 구성하든 `configs`에서 구성하든)는 다음 필드를 지원합니다:
| 속성 | 타입 | 기본값 | 설명 |
| --------------- | ------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled` | boolean | `true` | 이 도구의 활성화 여부입니다. |
| `defer_loading` | boolean | `false` | true인 경우 도구 설명이 처음에 모델로 전송되지 않습니다. [도구 검색 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/tool-search-tool)와 함께 사용됩니다. |
Anthropic이 제공하는 도구의 전체 목록과 `defer_loading` 같은 선택적 속성은 [도구 레퍼런스](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/tool-reference)를 참조하세요. 대규모 도구 세트에서 검색하려면 [도구 검색 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/tool-search-tool)를 참조하세요.
### 구성 병합
구성 값은 다음 우선순위(높은 순에서 낮은 순)로 병합됩니다:
1. `configs`의 도구별 설정
2. 세트 수준의 `default_config`
3. 시스템 기본값
예시:
```json
{
"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에서)
## 일반적인 구성 패턴
### 기본 구성으로 모든 도구 활성화
가장 간단한 패턴으로, 서버의 모든 도구를 활성화합니다:
```json
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp"
}
```
### 허용 목록: 특정 도구만 활성화
기본값으로 `enabled: false`를 설정한 다음, 특정 도구를 명시적으로 활성화합니다:
```json
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp",
"default_config": {
"enabled": false
},
"configs": {
"search_events": {
"enabled": true
},
"create_event": {
"enabled": true
}
}
}
```
### 차단 목록: 특정 도구 비활성화
기본적으로 모든 도구를 활성화한 다음, 원하지 않는 도구를 명시적으로 비활성화합니다. 읽기 전용 어시스턴트를 구축하거나 상태 변경 전에 사람의 확인 단계를 두고 싶은 경우, 쓰기 또는 파괴적인 도구를 차단 목록에 추가하는 것이 권장됩니다:
```json
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp",
"configs": {
"delete_all_events": {
"enabled": false
},
"share_calendar_publicly": {
"enabled": false
}
}
}
```
### 혼합: 도구별 구성이 포함된 허용 목록
허용 목록과 각 도구에 대한 사용자 지정 구성을 결합합니다:
```json
{
"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에서 참조되어야 합니다
* **서버당 고유한 도구 세트:** 각 MCP 서버는 하나의 MCPToolset에서만 참조될 수 있습니다
* **알 수 없는 도구 이름:** `configs`의 도구 이름이 MCP 서버에 존재하지 않는 경우, 백엔드 경고가 기록되지만 오류는 반환되지 않습니다(MCP 서버는 동적으로 도구 가용성이 달라질 수 있습니다)
## 응답 콘텐츠 타입
Claude가 MCP 도구를 사용하면 응답에 두 가지 새로운 콘텐츠 블록 타입이 포함됩니다:
### MCP 도구 사용 블록
```json
{
"type": "mcp_tool_use",
"id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
"name": "echo",
"server_name": "example-mcp",
"input": { "param1": "value1", "param2": "value2" }
}
```
### MCP 도구 결과 블록
```json
{
"type": "mcp_tool_result",
"tool_use_id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
"is_error": false,
"content": [
{
"type": "text",
"text": "Hello"
}
]
}
```
## MCP 서버의 도구 목록 고정하기 (베타)
MCP 서버는 언제든지 도구를 변경할 수 있습니다. `mcp-client-2026-09-15` 베타 헤더는 각 서버가 반환하는 도구 목록을 기록하고 이를 고정할 수 있게 하여, 도구를 변경하는 서버가 대화 중간에 Claude가 보는 내용을 변경하지 않도록 합니다. 이 헤더는 `mcp-client-2025-11-20`이 하는 모든 것을 포함하므로 해당 헤더 대신 전송하세요. Claude API에서 사용할 수 있습니다.
API가 응답을 생성하는 동안 MCP 서버에 도구를 요청하면, 응답은 해당 서버에 대한 `mcp_tool_listing` 블록으로 시작하며, 요청한 각 서버마다 하나의 블록이 있습니다:
```json
{
"type": "mcp_tool_listing",
"mcp_server_name": "example-mcp",
"tools": [
{
"name": "echo",
"description": "Returns the text it receives.",
"input_schema": {
"type": "object",
"properties": { "text": { "type": "string" } },
"required": ["text"]
}
}
]
}
```
코드가 `content[0]`을 읽는 경우 이러한 블록을 건너뛰세요. `mcp_tool_listing` 블록을 포함하여 어시스턴트 메시지를 변경하지 않고 다시 보내고, 이를 포함하는 모든 요청에서 계속 `mcp-client-2026-09-15`를 전송하세요. 그러면 이후 요청은 해당 서버에 다시 요청하는 대신 기록된 목록을 사용합니다.
목록을 직접 고정하려면 블록의 `tools`를 해당 서버의 MCPToolset의 `tools` 필드로 복사하세요. 그러면 API는 서버에 도구를 요청하지 않으며, 도구 세트의 도구는 `default_config`와 `configs`가 적용된 정확히 해당 항목들이 됩니다:
```json
{
"type": "mcp_toolset",
"mcp_server_name": "example-mcp",
"tools": [
{
"name": "echo",
"description": "Returns the text it receives.",
"input_schema": {
"type": "object",
"properties": { "text": { "type": "string" } },
"required": ["text"]
}
}
]
}
```
`tools`의 각 항목은 서버가 나열하는 대로의 도구 `name`(서버 이름 제외), `description`, `input_schema`를 포함합니다.
다음 예시는 고정되지 않은 도구 세트로 하나의 요청을 보내고, 반환된 목록을 도구 세트의 `tools` 필드로 복사한 다음 요청을 다시 보냅니다. API가 서버에 요청하지 않기 때문에 두 번째 응답에는 `mcp_tool_listing` 블록이 없습니다:
```bash cURL
BODY='{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"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"
}
],
"messages": [
{
"role": "user",
"content": "What tools do you have available?"
}
]
}'
# 첫 번째 요청: 툴셋이 고정되지 않았으므로 API가 서버에
# 도구를 요청하고, 응답은 mcp_tool_listing 블록으로 시작합니다.
# tee는 응답을 stderr에 표시하고 변수는 이를 캡처합니다.
FIRST=$(curl -sS https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: mcp-client-2026-09-15" \
-d "$BODY" | tee /dev/stderr)
# 목록 고정: 블록의 도구를 툴셋에 복사합니다. API는
# 정확히 이 항목들을 사용하며 서버에 다시 요청하지 않습니다.
TOOLS=$(jq '.content[] | select(.type == "mcp_tool_listing") | .tools' \
<<<"$FIRST")
PINNED=$(jq --argjson tools "$TOOLS" '.tools[0].tools = $tools' <<<"$BODY")
# 고정된 툴셋에서는 응답에 mcp_tool_listing 블록이 없습니다.
curl https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: mcp-client-2026-09-15" \
-d "$PINNED"
```
```bash CLI
request=$(cat <<'YAML'
model: claude-opus-5-5
max_tokens: 1024
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
messages:
- role: user
content: What tools do you have available?
YAML
)
# 첫 번째 요청: 도구 세트가 고정되지 않았으므로 API가 서버에
# 도구를 요청하고, 응답은 mcp_tool_listing 블록으로 시작합니다.
# tee는 응답을 stderr에 표시하는 동시에 변수에 캡처합니다.
first=$(ant beta:messages create --beta mcp-client-2026-09-15 --format json \
<<<"$request" | tee /dev/stderr)
tools=$(jq -c '.content[] | select(.type == "mcp_tool_listing") | .tools' \
<<<"$first")
# 목록 고정: 블록의 도구를 도구 세트로 복사합니다. --tool 플래그는
# 본문의 tools 배열을 대체합니다. API는 정확히 이 항목들을 사용하며
# 서버에 다시 요청하지 않으므로, 응답에 mcp_tool_listing 블록이 없습니다.
ant beta:messages create --beta mcp-client-2026-09-15 \
--tool "{type: mcp_toolset, mcp_server_name: example-mcp, tools: $tools}" \
<<<"$request"
```
```python Python
from anthropic.types.beta import (
BetaMessageParam,
BetaRequestMCPServerURLDefinitionParam,
)
client = anthropic.Anthropic()
mcp_servers: list[BetaRequestMCPServerURLDefinitionParam] = [
{
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse",
"name": "example-mcp",
"authorization_token": "YOUR_TOKEN",
},
]
messages: list[BetaMessageParam] = [
{"role": "user", "content": "What tools do you have available?"},
]
# 첫 번째 요청: 도구 세트가 고정되지 않았으므로 API가 서버에
# 도구를 요청하고, 응답은 mcp_tool_listing 블록으로 시작합니다.
first = client.beta.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
betas=["mcp-client-2026-09-15"],
mcp_servers=mcp_servers,
tools=[{"type": "mcp_toolset", "mcp_server_name": "example-mcp"}],
messages=messages,
)
listing = next(block for block in first.content if block.type == "mcp_tool_listing")
print([tool.name for tool in listing.tools])
# 목록 고정: 블록의 도구를 도구 세트로 복사합니다. API는
# 정확히 이 항목들을 사용하며 서버에 다시 요청하지 않습니다.
second = client.beta.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
betas=["mcp-client-2026-09-15"],
mcp_servers=mcp_servers,
tools=[
{
"type": "mcp_toolset",
"mcp_server_name": "example-mcp",
"tools": [
{
"name": tool.name,
"description": tool.description,
"input_schema": tool.input_schema,
}
for tool in listing.tools
],
},
],
messages=messages,
)
# 고정된 도구 세트를 사용하면 응답에 mcp_tool_listing 블록이 없습니다.
print([block.type for block in second.content])
```
```typescript TypeScript
const client = new Anthropic();
const mcpServers: Anthropic.Beta.BetaRequestMCPServerURLDefinition[] = [
{
type: "url",
url: "https://example-server.modelcontextprotocol.io/sse",
name: "example-mcp",
authorization_token: "YOUR_TOKEN"
}
];
const messages: Anthropic.Beta.BetaMessageParam[] = [
{ role: "user", content: "What tools do you have available?" }
];
// 첫 번째 요청: 도구 세트가 고정되지 않았으므로 API가 서버에
// 도구를 요청하고, 응답은 mcp_tool_listing 블록으로 시작합니다.
const first = await client.beta.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
betas: ["mcp-client-2026-09-15"],
mcp_servers: mcpServers,
tools: [{ type: "mcp_toolset", mcp_server_name: "example-mcp" }],
messages
});
const listing = first.content.find((block) => block.type === "mcp_tool_listing");
if (!listing) {
throw new Error("The response has no mcp_tool_listing block.");
}
console.log(listing.tools.map((tool) => tool.name));
// 목록 고정: 블록의 도구를 도구 세트로 복사합니다. API는
// 정확히 이 항목들을 사용하며 서버에 다시 요청하지 않습니다.
const second = await client.beta.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
betas: ["mcp-client-2026-09-15"],
mcp_servers: mcpServers,
tools: [
{
type: "mcp_toolset",
mcp_server_name: "example-mcp",
tools: listing.tools
}
],
messages
});
// 고정된 도구 세트를 사용하면 응답에 mcp_tool_listing 블록이 없습니다.
console.log(second.content.map((block) => block.type));
```
```csharp C#
using Anthropic.Models.Beta;
using Anthropic.Models.Beta.Messages;
using Messages = Anthropic.Models.Messages;
AnthropicClient client = new();
List mcpServers =
[
new()
{
Url = "https://example-server.modelcontextprotocol.io/sse",
Name = "example-mcp",
AuthorizationToken = "YOUR_TOKEN",
},
];
List messages =
[
new() { Role = Role.User, Content = "What tools do you have available?" },
];
// 첫 번째 요청: 도구 세트가 고정되지 않았으므로 API가 서버에
// 도구를 요청하고, 응답은 mcp_tool_listing 블록으로 시작합니다.
var first = await client.Beta.Messages.Create(new MessageCreateParams
{
Model = Messages::Model.ClaudeOpus5_5,
MaxTokens = 1024,
Betas = [AnthropicBeta.McpClient2026_09_15],
McpServers = mcpServers,
Tools = [new BetaMcpToolset("example-mcp")],
Messages = messages,
});
var listing = first.Content
.Select(block => block.Value)
.OfType()
.First();
Console.WriteLine(string.Join(", ", listing.Tools.Select(tool => tool.Name)));
// 목록 고정: 블록의 도구를 도구 세트로 복사합니다. API는
// 정확히 이 항목들을 사용하며 서버에 다시 요청하지 않습니다.
var second = await client.Beta.Messages.Create(new MessageCreateParams
{
Model = Messages::Model.ClaudeOpus5_5,
MaxTokens = 1024,
Betas = [AnthropicBeta.McpClient2026_09_15],
McpServers = mcpServers,
Tools =
[
new BetaMcpToolset("example-mcp")
{
Tools =
[
.. listing.Tools.Select(tool => new BetaMcpToolParam
{
Name = tool.Name,
Description = tool.Description,
InputSchema = tool.InputSchema,
}),
],
},
],
Messages = messages,
});
// 고정된 도구 세트를 사용하면 응답에 mcp_tool_listing 블록이 없습니다.
Console.WriteLine(string.Join(", ", second.Content.Select(block => block.Type)));
```
```go Go
client := anthropic.NewClient()
mcpServers := []anthropic.BetaRequestMCPServerURLDefinitionParam{
{
URL: "https://example-server.modelcontextprotocol.io/sse",
Name: "example-mcp",
AuthorizationToken: anthropic.String("YOUR_TOKEN"),
},
}
messages := []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("What tools do you have available?")),
}
// 첫 번째 요청: 도구 세트가 고정되지 않았으므로 API가 서버에
// 도구를 요청하고, 응답은 mcp_tool_listing 블록으로 시작합니다.
first, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaMCPClient2026_09_15},
MCPServers: mcpServers,
Tools: []anthropic.BetaToolUnionParam{
{OfMCPToolset: &anthropic.BetaMCPToolsetParam{MCPServerName: "example-mcp"}},
},
Messages: messages,
})
if err != nil {
log.Fatal(err)
}
var listing anthropic.BetaMCPToolListingBlock
for _, block := range first.Content {
if listingBlock, ok := block.AsAny().(anthropic.BetaMCPToolListingBlock); ok {
listing = listingBlock
break
}
}
// 목록 고정: 블록의 도구를 도구 세트로 복사합니다. API는
// 정확히 이 항목들을 사용하며 서버에 다시 요청하지 않습니다.
var toolNames []string
var pinnedTools []anthropic.BetaMCPToolParam
for _, tool := range listing.Tools {
toolNames = append(toolNames, tool.Name)
pinnedTools = append(pinnedTools, anthropic.BetaMCPToolParam{
Name: tool.Name,
Description: anthropic.String(tool.Description),
InputSchema: tool.InputSchema,
})
}
fmt.Println(toolNames)
second, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaMCPClient2026_09_15},
MCPServers: mcpServers,
Tools: []anthropic.BetaToolUnionParam{
{OfMCPToolset: &anthropic.BetaMCPToolsetParam{
MCPServerName: "example-mcp",
Tools: pinnedTools,
}},
},
Messages: messages,
})
if err != nil {
log.Fatal(err)
}
// 고정된 도구 세트에서는 응답에 mcp_tool_listing 블록이 없습니다.
var blockTypes []string
for _, block := range second.Content {
blockTypes = append(blockTypes, block.Type)
}
fmt.Println(blockTypes)
```
```java Java
import com.anthropic.models.beta.AnthropicBeta;
import com.anthropic.models.beta.messages.BetaMcpTool;
import com.anthropic.models.beta.messages.BetaMcpToolListingBlock;
import com.anthropic.models.beta.messages.BetaMcpToolset;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.beta.messages.BetaRequestMcpServerUrlDefinition;
import com.anthropic.models.beta.messages.MessageCreateParams;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
BetaRequestMcpServerUrlDefinition mcpServer = BetaRequestMcpServerUrlDefinition.builder()
.url("https://example-server.modelcontextprotocol.io/sse")
.name("example-mcp")
.authorizationToken("YOUR_TOKEN")
.build();
// 첫 번째 요청: 도구 세트가 고정되지 않았으므로 API가 서버에
// 도구를 요청하고, 응답은 mcp_tool_listing 블록으로 시작합니다.
BetaMessage first = client.beta().messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.addBeta(AnthropicBeta.MCP_CLIENT_2026_09_15)
.addMcpServer(mcpServer)
.addTool(BetaMcpToolset.builder()
.mcpServerName("example-mcp")
.build())
.addUserMessage("What tools do you have available?")
.build());
BetaMcpToolListingBlock listing = first.content().stream()
.flatMap(block -> block.mcpToolListing().stream())
.findFirst()
.orElseThrow();
IO.println(listing.tools().stream().map(BetaMcpTool::name).toList());
// 목록 고정: 블록의 도구를 도구 세트로 복사합니다. API는
// 정확히 이 항목들을 사용하며 서버에 다시 요청하지 않습니다.
BetaMessage second = client.beta().messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.addBeta(AnthropicBeta.MCP_CLIENT_2026_09_15)
.addMcpServer(mcpServer)
.addTool(BetaMcpToolset.builder()
.mcpServerName("example-mcp")
.tools(listing.tools().stream().map(BetaMcpTool::toParam).toList())
.build())
.addUserMessage("What tools do you have available?")
.build());
// 고정된 도구 세트를 사용하면 응답에 mcp_tool_listing 블록이 없습니다.
IO.println(second.content().stream()
.map(block -> block.type().asString())
.toList());
}
```
```php PHP
use Anthropic\Beta\AnthropicBeta;
use Anthropic\Beta\Messages\BetaMCPTool;
use Anthropic\Beta\Messages\BetaMCPToolListingBlock;
// ...
$client = new Client();
$mcpServers = [
[
'type' => 'url',
'url' => 'https://example-server.modelcontextprotocol.io/sse',
'name' => 'example-mcp',
'authorization_token' => 'YOUR_TOKEN',
],
];
$messages = [['role' => 'user', 'content' => 'What tools do you have available?']];
// 첫 번째 요청: 도구 세트가 고정되지 않았으므로 API가 서버에
// 도구를 요청하고, 응답은 mcp_tool_listing 블록으로 시작합니다.
$first = $client->beta->messages->create(
model: Model::CLAUDE_OPUS_5_5,
maxTokens: 1024,
betas: [AnthropicBeta::MCP_CLIENT_2026_09_15],
mcpServers: $mcpServers,
tools: [['type' => 'mcp_toolset', 'mcp_server_name' => 'example-mcp']],
messages: $messages,
);
$listing = array_find($first->content, fn ($block) => $block instanceof BetaMCPToolListingBlock);
echo json_encode(array_map(fn (BetaMCPTool $tool) => $tool->name, $listing->tools)), PHP_EOL;
// 목록 고정: 블록의 도구를 도구 세트로 복사합니다. API는
// 정확히 이 항목들을 사용하며 서버에 다시 요청하지 않습니다.
$second = $client->beta->messages->create(
model: Model::CLAUDE_OPUS_5_5,
maxTokens: 1024,
betas: [AnthropicBeta::MCP_CLIENT_2026_09_15],
mcpServers: $mcpServers,
tools: [
[
'type' => 'mcp_toolset',
'mcp_server_name' => 'example-mcp',
'tools' => array_map(
fn (BetaMCPTool $tool) => [
'name' => $tool->name,
'description' => $tool->description,
'input_schema' => $tool->inputSchema,
],
$listing->tools,
),
],
],
messages: $messages,
);
// 고정된 도구 세트에서는 응답에 mcp_tool_listing 블록이 없습니다.
echo json_encode(array_map(fn ($block) => $block->type, $second->content)), PHP_EOL;
```
```ruby Ruby
client = Anthropic::Client.new
mcp_servers = [
{
type: "url",
url: "https://example-server.modelcontextprotocol.io/sse",
name: "example-mcp",
authorization_token: "YOUR_TOKEN"
}
]
messages = [{ role: "user", content: "What tools do you have available?" }]
# 첫 번째 요청: 도구 세트가 고정되지 않았으므로 API가 서버에
# 도구를 요청하고, 응답은 mcp_tool_listing 블록으로 시작합니다.
first = client.beta.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 1024,
betas: [Anthropic::AnthropicBeta::MCP_CLIENT_2026_09_15],
mcp_servers:,
tools: [{ type: "mcp_toolset", mcp_server_name: "example-mcp" }],
messages:
)
listing = first.content.find { it.is_a?(Anthropic::Beta::BetaMCPToolListingBlock) }
puts listing.tools.map(&:name).inspect
# 목록 고정: 블록의 도구를 도구 세트로 복사합니다. API는
# 정확히 이 항목들을 사용하며 서버에 다시 요청하지 않습니다.
second = client.beta.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 1024,
betas: [Anthropic::AnthropicBeta::MCP_CLIENT_2026_09_15],
mcp_servers:,
tools: [
{
type: "mcp_toolset",
mcp_server_name: "example-mcp",
tools: listing.tools.map(&:to_h)
}
],
messages:
)
# 고정된 도구 세트를 사용하면 응답에 mcp_tool_listing 블록이 없습니다.
puts second.content.map(&:type).inspect
```
`inline-tools-2026-09-15` 베타 헤더도 함께 사용하면 대화 중간에 MCP 서버를 추가할 수 있습니다. [대화 중간에 MCP 서버 추가하기](https://platform.claude.com/docs/ko/build-with-claude/mid-conversation-system-messages#add-an-mcp-server-mid-conversation-beta)를 참조하세요.
## 다중 MCP 서버
`mcp_servers`에 여러 서버 정의를 포함하고 `tools` 배열에 각각에 해당하는 MCPToolset을 포함하여 여러 MCP 서버에 연결할 수 있습니다:
```json
{
"model": "claude-opus-5-5",
"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는 도구 이름과 설명을 기반으로 선택합니다. 명확하고 구체적인 도구 설명은 선택 정확도를 높입니다. 대규모 도구 세트(여러 서버에 걸친 수십 개의 도구)의 경우, 쿼리마다 관련 도구만 표시되도록 [도구 검색 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/tool-search-tool)와 함께 [`defer_loading`](https://platform.claude.com/docs/ko/agents-and-tools/mcp-connector#tool-configuration-options)을 활성화하는 것을 고려하세요.
## 인증
OAuth 인증이 필요한 MCP 서버의 경우 액세스 토큰을 얻어야 합니다. MCP 커넥터 베타는 MCP 서버 정의에 `authorization_token` 매개변수를 전달하는 것을 지원합니다. API 사용자는 API 호출 전에 OAuth 흐름을 처리하여 액세스 토큰을 얻고, 필요에 따라 토큰을 갱신해야 합니다.
### 테스트용 액세스 토큰 얻기
MCP inspector는 테스트 목적으로 액세스 토큰을 얻는 과정을 안내해 줍니다.
1. 다음 명령으로 inspector를 실행하세요. 컴퓨터에 Node.js가 설치되어 있어야 합니다.
```bash
npx @modelcontextprotocol/inspector
```
2. 왼쪽 사이드바의 **Transport type**에서 **SSE** 또는 **Streamable HTTP**를 선택하세요.
3. MCP 서버의 URL을 입력하세요.
4. 오른쪽 영역에서 **Need to configure authentication?** 뒤에 있는 **Open Auth Settings**를 클릭하세요.
5. **Quick OAuth Flow**를 클릭하고 OAuth 화면에서 인증하세요.
6. inspector의 **OAuth Flow Progress** 섹션의 단계를 따라 **Authentication complete**에 도달할 때까지 **Continue**를 클릭하세요.
7. `access_token` 값을 복사하세요.
8. MCP 서버 구성의 `authorization_token` 필드에 붙여넣으세요.
### 액세스 토큰 사용하기
앞서 설명한 OAuth 흐름 중 하나를 사용하여 액세스 토큰을 얻었다면, MCP 서버 구성에서 사용할 수 있습니다:
```json
{
"mcp_servers": [
{
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse",
"name": "authenticated-server",
"authorization_token": "YOUR_ACCESS_TOKEN_HERE"
}
]
}
```
OAuth 흐름에 대한 자세한 설명은 MCP 사양의 [Authorization 섹션](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization)을 참조하세요.
## 클라이언트 측 MCP 헬퍼
자체 MCP 클라이언트 연결을 관리하는 경우(예: 로컬 stdio 서버, MCP 프롬프트 또는 MCP 리소스 사용 시), SDK는 MCP 타입과 Claude API 타입 간 변환을 위한 헬퍼 함수를 제공합니다. 이를 통해 Anthropic SDK와 함께 사용 언어의 MCP SDK(예: [TypeScript MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk))를 사용할 때 수동 변환 코드가 필요 없어집니다.
URL로 접근 가능한 원격 서버가 있고 도구 지원만 필요한 경우에는 [`mcp_servers` API 매개변수](https://platform.claude.com/docs/ko/agents-and-tools/mcp-connector#using-the-mcp-connector-in-the-messages-api)를 사용하세요. 로컬 서버, 프롬프트, 리소스가 필요하거나 기본 SDK로 연결을 더 세밀하게 제어해야 하는 경우에는 클라이언트 측 헬퍼를 사용하세요.
### 설치
Anthropic SDK와 MCP SDK를 모두 설치하세요:
MCP 헬퍼는 `mcp` extra에 포함되어 있으며, Python 3.10 이상이 필요합니다:
```bash
pip install "anthropic[mcp]"
```
```bash
npm install @anthropic-ai/sdk @modelcontextprotocol/sdk
```
헬퍼는 별도의 `Anthropic.Mcp` 패키지에 있으며, MCP 클라이언트 자체는 공식 [ModelContextProtocol 패키지](https://www.nuget.org/packages/ModelContextProtocol)에서 제공됩니다:
```bash
dotnet add package Anthropic.Mcp
dotnet add package ModelContextProtocol
```
헬퍼는 Go SDK의 `mcp` 하위 패키지에 있으며, [MCP Go SDK](https://github.com/modelcontextprotocol/go-sdk)를 기반으로 합니다:
```bash
go get github.com/anthropics/anthropic-sdk-go/mcp
```
헬퍼는 별도의 `anthropic-java-mcp` 아티팩트에 있으며, Java 17 이상이 필요합니다(기본 SDK는 Java 8을 지원합니다). 기본 `anthropic-java` 의존성과 함께 추가하세요:
```kotlin
implementation("com.anthropic:anthropic-java:2.73.0")
implementation("com.anthropic:anthropic-java-mcp:2.73.0")
```
```xml
com.anthropic
anthropic-java
2.73.0
com.anthropic
anthropic-java-mcp
2.73.0
```
헬퍼는 공식 [MCP PHP SDK](https://packagist.org/packages/mcp/sdk)를 사용합니다:
```bash
composer require "anthropic-ai/sdk" "guzzlehttp/guzzle:^7" "mcp/sdk"
```
헬퍼는 공식 [`mcp` gem](https://rubygems.org/gems/mcp)을 사용합니다:
```bash
bundle add anthropic mcp
```
### 사용 가능한 헬퍼
사용 언어에 맞는 헬퍼를 가져오세요:
```python Python
from anthropic.lib.tools.mcp import (
async_mcp_tool,
mcp_message,
mcp_resource_to_content,
mcp_resource_to_file,
)
```
```typescript TypeScript
import {
mcpTools,
mcpMessages,
mcpResourceToContent,
mcpResourceToFile
} from "@anthropic-ai/sdk/helpers/beta/mcp";
```
```csharp C#
using Anthropic.Helpers.Beta;
using Anthropic.Helpers.Beta.Mcp;
```
```go Go
import (
"github.com/anthropics/anthropic-sdk-go/mcp"
)
```
```java Java
import com.anthropic.helpers.McpBetaTool;
import com.anthropic.mcp.BetaMcp;
```
```php PHP
use Anthropic\Lib\Tools\BetaMcp;
```
```ruby Ruby
require "anthropic"
# 헬퍼는 Anthropic::Mcp 모듈에 노출됩니다
```
| 헬퍼 | 설명 |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `async_mcp_tool(tool, mcp_client)` (typescript: `mcpTools(tools, mcpClient)`; csharp: `BetaMcp.ListToolsAsync(mcpClient)`; go: `mcp.NewBetaTools(tools, session)`; java: `BetaMcp.mcpTools(tools, mcpClient)`; php: `BetaMcp::tools($tools, $mcp)`; ruby: `Anthropic::Mcp.tools(tools, mcp_client)`) | MCP 도구를 `client.beta.messages.tool_runner()` (typescript: `client.beta.messages.toolRunner()`; java: `client.beta().messages().toolRunner()`; php: `$client->beta->messages->toolRunner()`; csharp: `client.Beta.Messages.ToolRunner()`; go: `client.Beta.Messages.NewToolRunner()`)와 함께 사용할 수 있는 Claude API 도구로 변환합니다 |
| `mcp_message(message)` (typescript: `mcpMessages(messages)`; csharp: `BetaMcp.Messages(messages)`; go: `mcp.ToMessage(message)`; java: `BetaMcp.mcpMessages(messages)`; php: `BetaMcp::message($message)`; ruby: `Anthropic::Mcp.message(message)`) | MCP 프롬프트 메시지를 Claude API 메시지 형식으로 변환합니다 |
| `mcp_resource_to_content(resource)` (typescript: `mcpResourceToContent(resource)`; csharp: `BetaMcp.ResourceToContent(resource)`; go: `mcp.ResourceToBlock(resource)`; java: `BetaMcp.mcpResourceContents(resource)`; php: `BetaMcp::resourceToContent($resource)`; ruby: `Anthropic::Mcp.resource_to_contents(resource)`) | MCP 리소스를 Claude API 콘텐츠 블록으로 변환합니다 |
| `mcp_resource_to_file(resource)` (typescript: `mcpResourceToFile(resource)`; csharp: `BetaMcp.ResourceToFile(resource)`; go: `mcp.ResourceToFile(resource)`; java: `BetaMcp.mcpResourceFiles(resource)`; php: `BetaMcp::resourceToFile($resource)`; ruby: `Anthropic::Mcp.resource_to_files(resource)`) | MCP 리소스를 업로드용 파일 객체로 변환합니다 |
### MCP 도구 사용하기
도구 실행을 자동으로 처리하는 SDK의 [도구 러너](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/tool-runner)와 함께 사용할 수 있도록 MCP 도구를 변환합니다:
```python Python
from anthropic.lib.tools.mcp import async_mcp_tool
from mcp import ClientSession
from mcp.client.stdio import StdioServerParameters, stdio_client
client = AsyncAnthropic()
async def main() -> None:
# MCP 서버에 연결
server_params = StdioServerParameters(command="mcp-server")
async with stdio_client(server_params) as (read, write):
async with ClientSession(read, write) as mcp_client:
await mcp_client.initialize()
# 도구 목록을 가져와 Claude API 용으로 변환
tools_result = await mcp_client.list_tools()
runner = client.beta.messages.tool_runner(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{"role": "user", "content": "What tools do you have available?"},
],
tools=[async_mcp_tool(tool, mcp_client) for tool in tools_result.tools],
)
final_message = await runner.until_done()
print(final_message)
asyncio.run(main())
```
```typescript TypeScript
import {
mcpTools,
type MCPCallToolResultLike,
type MCPClientLike
} 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();
// MCP SDK의 callTool 반환 타입에는 mcpTools가 허용하지 않는 레거시 결과 형태가
// 아직 포함되어 있으므로 타입을 좁힙니다. MCPClientLike가 확장되면 제거하세요.
const mcpClientForTools: MCPClientLike = {
callTool: (params) => mcpClient.callTool(params) as Promise
};
const finalMessage = await anthropic.beta.messages.toolRunner({
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "What tools do you have available?" }],
tools: mcpTools(tools, mcpClientForTools)
});
console.log(finalMessage);
```
```csharp C#
using Anthropic.Helpers.Beta;
using Anthropic.Helpers.Beta.Mcp;
using Anthropic.Models.Beta.Messages;
using ModelContextProtocol.Client;
using Messages = Anthropic.Models.Messages;
var anthropic = new AnthropicClient();
// MCP 서버에 연결
await using var mcpClient = await McpClient.CreateAsync(
new StdioClientTransport(new StdioClientTransportOptions { Command = "mcp-server" })
);
// 도구 목록을 가져와 Claude API 용으로 변환
var tools = await BetaMcp.ListToolsAsync(mcpClient);
var runner = anthropic.Beta.Messages.ToolRunner(
new MessageCreateParams
{
Model = Messages::Model.ClaudeOpus5_5,
MaxTokens = 1024,
Messages =
[
new BetaMessageParam
{
Role = Role.User,
Content = "What tools do you have available?",
},
],
},
tools
);
var finalMessage = await runner.RunUntilDoneAsync();
Console.WriteLine(finalMessage);
```
```go Go
import (
// ...
// ...
"github.com/anthropics/anthropic-sdk-go/mcp"
mcpsdk "github.com/modelcontextprotocol/go-sdk/mcp"
)
func main() {
client := anthropic.NewClient()
ctx := context.Background()
// MCP 서버에 연결
mcpClient := mcpsdk.NewClient(&mcpsdk.Implementation{Name: "my-client", Version: "1.0.0"}, nil)
session, err := mcpClient.Connect(ctx, &mcpsdk.CommandTransport{Command: exec.Command("mcp-server")}, nil)
if err != nil {
log.Fatal(err)
}
defer session.Close()
// 도구 목록을 가져와 Claude API 용으로 변환
toolsResult, err := session.ListTools(ctx, nil)
if err != nil {
log.Fatal(err)
}
betaTools, err := mcp.NewBetaTools(toolsResult.Tools, session)
if err != nil {
log.Fatal(err)
}
runner := client.Beta.Messages.NewToolRunner(betaTools, anthropic.BetaToolRunnerParams{
BetaMessageNewParams: anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("What tools do you have available?")),
},
},
})
finalMessage, err := runner.RunToCompletion(ctx)
if err != nil {
log.Fatal(err)
}
fmt.Println(finalMessage.RawJSON())
}
```
```java Java
import com.anthropic.helpers.BetaToolRunner;
import com.anthropic.helpers.McpBetaTool;
import com.anthropic.mcp.BetaMcp;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.beta.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
import io.modelcontextprotocol.client.McpClient;
import io.modelcontextprotocol.client.McpSyncClient;
import io.modelcontextprotocol.client.transport.ServerParameters;
import io.modelcontextprotocol.client.transport.StdioClientTransport;
import io.modelcontextprotocol.json.McpJsonDefaults;
import io.modelcontextprotocol.spec.McpSchema;
// ...
void main() throws Exception {
AnthropicClient anthropic = AnthropicOkHttpClient.fromEnv();
// MCP 서버에 연결
StdioClientTransport transport = new StdioClientTransport(
ServerParameters.builder("mcp-server").build(), McpJsonDefaults.getMapper());
try (McpSyncClient mcpClient = McpClient.sync(transport)
.clientInfo(new McpSchema.Implementation("my-client", "1.0.0"))
.build()) {
mcpClient.initialize();
// 도구 목록을 가져와 Claude API 용으로 변환
List betaTools = BetaMcp.mcpTools(mcpClient.listTools().tools(), mcpClient);
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.addUserMessage("What tools do you have available?")
.addTools(betaTools)
.build();
// 러너는 어시스턴트 턴마다 하나의 메시지를 생성하며, 마지막이 최종 응답입니다
BetaToolRunner runner = anthropic.beta().messages().toolRunner(params);
BetaMessage finalMessage = null;
for (BetaMessage message : runner) {
finalMessage = message;
}
IO.println(finalMessage);
}
}
```
```php PHP
use Anthropic\Lib\Tools\BetaMcp;
use Mcp\Client;
use Mcp\Client\Transport\HttpTransport;
$anthropic = new Anthropic();
// MCP 서버에 연결합니다. PHP MCP 클라이언트는 HTTP로 연결하므로, 이를
// 사용 중인 서버의 엔드포인트로 지정하세요.
$mcp = Client::builder()->build();
$mcp->connect(new HttpTransport('http://localhost:8000/mcp'));
// 도구를 나열하고 Claude API용으로 변환합니다
$runner = $anthropic->beta->messages->toolRunner(
maxTokens: 1024,
messages: [['role' => 'user', 'content' => 'What tools do you have available?']],
model: 'claude-opus-5-5',
tools: BetaMcp::tools($mcp->listTools()->tools, $mcp),
);
echo $runner->runUntilDone(), "\n";
```
```ruby Ruby
require "mcp"
anthropic = Anthropic::Client.new
# MCP 서버에 연결
transport = MCP::Client::Stdio.new(command: "mcp-server")
mcp_client = MCP::Client.new(transport: transport)
mcp_client.connect
# 도구를 나열하고 Claude API 용으로 변환
runner = anthropic.beta.messages.tool_runner(
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "What tools do you have available?" }],
tools: Anthropic::Mcp.tools(mcp_client.tools, mcp_client)
)
final_message = runner.run_until_finished.last
puts final_message
```
### MCP 프롬프트 사용하기
MCP 프롬프트 메시지를 Claude API 메시지 형식으로 변환합니다:
```python Python
from anthropic.lib.tools.mcp import mcp_message
prompt = await mcp_client.get_prompt(name="my-prompt")
response = await client.beta.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[mcp_message(message) for message in prompt.messages],
)
print(response)
```
```typescript TypeScript
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-5-5",
max_tokens: 1024,
messages: mcpMessages(messages)
});
console.log(response);
```
```csharp C#
var prompt = await mcpClient.GetPromptAsync("my-prompt");
var response = await anthropic.Beta.Messages.Create(
new MessageCreateParams
{
Model = Messages::Model.ClaudeOpus5_5,
MaxTokens = 1024,
Messages = BetaMcp.Messages(prompt.Messages),
}
);
Console.WriteLine(response);
```
```go Go
prompt, err := session.GetPrompt(ctx, &mcpsdk.GetPromptParams{Name: "my-prompt"})
if err != nil {
log.Fatal(err)
}
messages := make([]anthropic.BetaMessageParam, 0, len(prompt.Messages))
for _, promptMessage := range prompt.Messages {
message, err := mcp.ToMessage(promptMessage)
if err != nil {
log.Fatal(err)
}
messages = append(messages, message)
}
response, err := client.Beta.Messages.New(ctx, anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Messages: messages,
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.RawJSON())
```
```java Java
McpSchema.GetPromptResult prompt = mcpClient.getPrompt(
new McpSchema.GetPromptRequest("my-prompt", Map.of()));
BetaMessage response = anthropic.beta().messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.messages(BetaMcp.mcpMessages(prompt.messages()))
.build());
IO.println(response);
```
```php PHP
$prompt = $mcp->getPrompt('my-prompt');
$response = $anthropic->beta->messages->create(
maxTokens: 1024,
messages: array_map(BetaMcp::message(...), $prompt->messages),
model: 'claude-opus-5-5',
);
echo $response, "\n";
```
```ruby Ruby
prompt = mcp_client.get_prompt(name: "my-prompt")
response = anthropic.beta.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
messages: prompt["messages"].map { |message| Anthropic::Mcp.message(message) }
)
puts response
```
### MCP 리소스 사용하기
MCP 리소스를 메시지에 포함할 콘텐츠 블록으로 변환하거나, 업로드용 파일 객체로 변환합니다:
```python Python
from anthropic.lib.tools.mcp import (
mcp_resource_to_content,
mcp_resource_to_file,
)
# 메시지 내 콘텐츠 블록으로 사용
resource = await mcp_client.read_resource(uri="file:///path/to/doc.txt")
response = await client.beta.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
mcp_resource_to_content(resource),
{"type": "text", "text": "Summarize this document"},
],
}
],
)
print(response)
# 파일 업로드로 사용
file_resource = await mcp_client.read_resource(
uri="file:///path/to/data.json",
)
uploaded = await client.files.upload(
file=mcp_resource_to_file(file_resource),
)
print(uploaded.id)
```
```typescript TypeScript
import { mcpResourceToContent, mcpResourceToFile } from "@anthropic-ai/sdk/helpers/beta/mcp";
// 메시지 내 콘텐츠 블록으로 사용
const resource = await mcpClient.readResource({ uri: "file:///path/to/doc.txt" });
const response = await anthropic.beta.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [
{
role: "user",
content: [
mcpResourceToContent(resource),
{ type: "text", text: "Summarize this document" }
]
}
]
});
console.log(response);
// 파일 업로드로 사용
const fileResource = await mcpClient.readResource({ uri: "file:///path/to/data.json" });
const uploaded = await anthropic.files.upload({ file: mcpResourceToFile(fileResource) });
console.log(uploaded.id);
```
```csharp C#
// 메시지 내 콘텐츠 블록으로 사용
var resource = await mcpClient.ReadResourceAsync("file:///path/to/doc.txt");
var response = await anthropic.Beta.Messages.Create(
new MessageCreateParams
{
Model = Messages::Model.ClaudeOpus5_5,
MaxTokens = 1024,
Messages =
[
new BetaMessageParam
{
Role = Role.User,
Content = new BetaMessageParamContent(
[
BetaMcp.ResourceToContent(resource),
new BetaTextBlockParam { Text = "Summarize this document" },
]
),
},
],
}
);
Console.WriteLine(response);
// 파일 업로드로 사용
var fileResource = await mcpClient.ReadResourceAsync("file:///path/to/data.json");
var (filename, data, mediaType) = BetaMcp.ResourceToFile(fileResource);
// 리소스의 파일 이름과 MIME 타입이 업로드까지 전달되도록
// 파일 파트를 명시적으로 구성합니다.
var file = new BinaryContent { Stream = new MemoryStream(data), FileName = filename };
if (mediaType is not null)
{
file.ContentType = new(mediaType);
}
var uploaded = await anthropic.Files.Upload(new FileUploadParams { File = file });
Console.WriteLine(uploaded.ID);
```
```go Go
// 메시지 내 콘텐츠 블록으로 사용
resource, err := session.ReadResource(ctx, &mcpsdk.ReadResourceParams{URI: "file:///path/to/doc.txt"})
if err != nil {
log.Fatal(err)
}
block, err := mcp.ResourceToBlock(resource)
if err != nil {
log.Fatal(err)
}
response, err := client.Beta.Messages.New(ctx, anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(
// ResourceToBlock은 tool-result 콘텐츠 유니온을 반환합니다. 메시지
// 콘텐츠는 별도의 유니온 타입이므로 공유 변형을 다시 래핑합니다
// (mcp.ToMessage도 내부적으로 동일하게 처리합니다).
anthropic.BetaContentBlockParamUnion{
OfText: block.OfText,
OfImage: block.OfImage,
OfDocument: block.OfDocument,
},
anthropic.NewBetaTextBlock("Summarize this document"),
),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.RawJSON())
// 파일 업로드로 사용
fileResult, err := session.ReadResource(ctx, &mcpsdk.ReadResourceParams{URI: "file:///path/to/data.json"})
if err != nil {
log.Fatal(err)
}
fileReader, err := mcp.ResourceToFile(fileResult)
if err != nil {
log.Fatal(err)
}
uploaded, err := client.Files.Upload(ctx, anthropic.FileUploadParams{File: fileReader})
if err != nil {
log.Fatal(err)
}
fmt.Println(uploaded.ID)
```
```java Java
// 메시지 내 콘텐츠 블록으로 사용
McpSchema.ReadResourceResult resource = mcpClient.readResource(
new McpSchema.ReadResourceRequest("file:///path/to/doc.txt"));
List content =
new ArrayList<>(BetaMcp.mcpResourceContents(resource));
content.add(BetaContentBlockParam.ofText(
BetaTextBlockParam.builder().text("Summarize this document").build()));
BetaMessage response = anthropic.beta().messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.addUserMessageOfBetaContentBlockParams(content)
.build());
IO.println(response);
// 파일 업로드로 사용
McpSchema.ReadResourceResult fileResource = mcpClient.readResource(
new McpSchema.ReadResourceRequest("file:///path/to/data.json"));
McpResourceFile resourceFile = BetaMcp.mcpResourceFiles(fileResource).getFirst();
// 리소스의 파일명과 MIME 타입이 업로드에 전달되도록
// 파일 파트를 명시적으로 구성합니다.
MultipartField.Builder fileField = MultipartField.builder()
.value(new ByteArrayInputStream(resourceFile.content()))
.filename(resourceFile.filename());
if (resourceFile.mimeType() != null) {
fileField.contentType(resourceFile.mimeType());
}
var uploaded = anthropic.files().upload(FileUploadParams.builder()
.file(fileField.build())
.build());
IO.println(uploaded.id());
```
```php PHP
// 메시지 내 콘텐츠 블록으로 사용
$resource = $mcp->readResource('file:///path/to/doc.txt');
$response = $anthropic->beta->messages->create(
maxTokens: 1024,
messages: [
[
'role' => 'user',
'content' => [
BetaMcp::resourceToContent($resource),
['type' => 'text', 'text' => 'Summarize this document'],
],
],
],
model: 'claude-opus-5-5',
);
echo $response, "\n";
// 파일 업로드로 사용
$fileResource = $mcp->readResource('file:///path/to/data.json');
$file = $anthropic->files->upload(file: BetaMcp::resourceToFile($fileResource));
echo $file->id, "\n";
```
```ruby Ruby
# 메시지 내 콘텐츠 블록으로 사용
resource = mcp_client.read_resource(uri: "file:///path/to/doc.txt")
response = anthropic.beta.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [
{
role: "user",
content: [
*Anthropic::Mcp.resource_to_contents(resource),
{ type: "text", text: "Summarize this document" }
]
}
]
)
puts response
# 파일 업로드로 사용
file_resource = mcp_client.read_resource(uri: "file:///path/to/data.json")
file = Anthropic::Mcp.resource_to_files(file_resource).first
uploaded_file = anthropic.files.upload(file: file)
puts uploaded_file.id
```
### 오류 처리
MCP 값이 Claude API에서 지원되지 않는 경우 변환 함수는 `UnsupportedMCPValueError` (go: `UnsupportedValueError`; java, csharp: `AnthropicInvalidDataException`) 오류와 함께 실패합니다(예외가 발생하거나, Go에서는 오류로 반환됨). 이는 지원되지 않는 콘텐츠 타입, MIME 타입 또는 리소스 링크에서 발생할 수 있습니다(변환하기 전에 MCP 클라이언트로 리소스 링크를 해석하세요).
## 배치 요청
[Message Batches API](https://platform.claude.com/docs/ko/build-with-claude/batch-processing) 요청에 `mcp_servers`를 포함할 수 있습니다. Batches API를 통한 MCP 도구 호출은 일반 Messages API 요청과 동일하게 가격이 책정됩니다.
## 데이터 보존
MCP 커넥터는 ZDR 계약의 적용 대상이 아닙니다. 도구 정의 및 실행 결과를 포함하여 MCP 서버와 교환되는 데이터는 Anthropic의 표준 데이터 보존 정책에 따라 보존됩니다.
모든 기능의 ZDR 적격 여부는 [API 및 데이터 보존](https://platform.claude.com/docs/ko/manage-claude/api-and-data-retention)을 참조하세요.
## 마이그레이션 가이드
지원 중단된 `mcp-client-2025-04-04` 베타 헤더를 사용하고 있다면, 이 가이드를 따라 새 버전으로 마이그레이션하세요.
### 주요 변경 사항
1. **새 베타 헤더:** `mcp-client-2025-04-04`에서 `mcp-client-2025-11-20`으로 변경
2. **도구 구성 위치 이동:** 도구 구성은 이제 MCP 서버 정의가 아닌 `tools` 배열의 MCPToolset 객체에 위치합니다
3. **더 유연한 구성:** 새 패턴은 허용 목록, 차단 목록 및 도구별 구성을 지원합니다
### 마이그레이션 단계
**이전 (지원 중단):**
```json
{
"model": "claude-opus-5-5",
"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"]
}
}
]
}
```
**이후 (현재):**
```json
{
"model": "claude-opus-5-5",
"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
이 버전은 지원 중단되었습니다. 앞의 [마이그레이션 가이드](https://platform.claude.com/docs/ko/agents-and-tools/mcp-connector#migration-guide)를 사용하여 `mcp-client-2025-11-20`으로 마이그레이션하세요.
MCP 커넥터의 이전 버전은 MCP 서버 정의에 도구 구성을 직접 포함했습니다:
```json
{
"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`를 사용한 허용 목록 패턴을 사용하세요 |