MCP 커넥터

빌드MCP

MCP 커넥터

Claude의 Model Context Protocol (MCP) 커넥터 기능을 사용하여 Messages API에서 직접 원격 MCP 서버에 연결하는 방법을 알아봅니다.

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

현재 버전: 이 기능은 베타 헤더가 필요합니다: "anthropic-beta": "mcp-client-2025-11-20"

이전 버전(mcp-client-2025-04-04)은 더 이상 지원되지 않습니다. 아래의 더 이상 지원되지 않는 버전 문서를 참조하세요.

This feature is not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.

주요 기능

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

제한 사항

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

Messages API에서 MCP 커넥터 사용

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

MCP 서버 정의 (mcp_servers 배열): 서버 연결 세부 정보(URL, 인증) 정의
MCP 도구 세트 (tools 배열): 활성화할 도구 및 구성 방법 구성

기본 예제

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

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-7",
    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`	문자열	예	현재 "url"만 지원됨
`url`	문자열	예	MCP 서버의 URL. https://로 시작해야 함
`name`	문자열	예	이 MCP 서버의 고유 식별자. `tools` 배열의 정확히 하나의 MCPToolset에서 참조되어야 함
`authorization_token`	문자열	아니오	MCP 서버에서 필요한 경우 OAuth 인증 토큰. MCP 사양 참조

MCP 도구 세트 구성

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`	문자열	예	"mcp_toolset"이어야 함
`mcp_server_name`	문자열	예	`mcp_servers` 배열에 정의된 서버 이름과 일치해야 함
`default_config`	객체	아니오	이 세트의 모든 도구에 적용되는 기본 구성. `configs`의 개별 도구 구성이 이러한 기본값을 재정의합니다.
`configs`	객체	아니오	도구별 구성 재정의. 키는 도구 이름이고 값은 구성 객체입니다.
`cache_control`	객체	아니오	이 도구 세트에 대한 캐시 중단점 구성

도구 구성 옵션

각 도구(default_config 또는 configs에서 구성되든)는 다음 필드를 지원합니다:

속성	유형	기본값	설명
`enabled`	부울	`true`	이 도구가 활성화되어 있는지 여부
`defer_loading`	부울	`false`	true인 경우 도구 설명이 처음에 모델로 전송되지 않습니다. 도구 검색 도구와 함께 사용됩니다.

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

구성 병합

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

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에서 참조되어야 함
서버당 고유한 도구 세트: 각 MCP 서버는 하나의 MCPToolset에서만 참조될 수 있음
알 수 없는 도구 이름: configs의 도구 이름이 MCP 서버에 존재하지 않으면 백엔드 경고가 기록되지만 오류는 반환되지 않음 (MCP 서버는 동적 도구 가용성을 가질 수 있음)

응답 콘텐츠 유형

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

MCP 도구 사용 블록

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

MCP 도구 결과 블록

{
  "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-7",
  "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
      }
    }
  ]
}

인증

OAuth 인증이 필요한 MCP 서버의 경우 액세스 토큰을 얻어야 합니다. MCP 커넥터 베타는 MCP 서버 정의에서 authorization_token 매개변수를 전달하는 것을 지원합니다. API 소비자는 OAuth 흐름을 처리하고 API 호출 전에 액세스 토큰을 얻으며 필요에 따라 토큰을 새로 고칠 책임이 있습니다.

테스트를 위한 액세스 토큰 얻기

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

다음 명령으로 검사기를 실행합니다. 컴퓨터에 Node.js가 설치되어 있어야 합니다.
```
npx @modelcontextprotocol/inspector
```
왼쪽 사이드바에서 "Transport type"에 대해 "SSE" 또는 "Streamable HTTP"를 선택합니다.
MCP 서버의 URL을 입력합니다.
오른쪽 영역에서 "Need to configure authentication?" 다음의 "Open Auth Settings" 버튼을 클릭합니다.
"Quick OAuth Flow"를 클릭하고 OAuth 화면에서 인증합니다.
검사기의 "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 사양의 인증 섹션을 참조하세요.

클라이언트 측 MCP 도우미 (TypeScript)

자신의 MCP 클라이언트 연결을 관리하는 경우(예: 로컬 stdio 서버, MCP 프롬프트 또는 MCP 리소스 사용), TypeScript SDK는 MCP 유형과 Claude API 유형 간의 변환을 수행하는 도우미 함수를 제공합니다. 이는 Anthropic SDK와 함께 MCP SDK를 사용할 때 수동 변환 코드를 제거합니다.

이러한 도우미는 현재 TypeScript SDK에서만 사용 가능합니다.

원격 서버에 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)`	MCP 도구를 `client.beta.messages.toolRunner()`와 함께 사용하기 위해 Claude API 도구로 변환
`mcpMessages(messages)`	MCP 프롬프트 메시지를 Claude API 메시지 형식으로 변환
`mcpResourceToContent(resource)`	MCP 리소스를 Claude API 콘텐츠 블록으로 변환
`mcpResourceToFile(resource)`	MCP 리소스를 업로드용 파일 객체로 변환

MCP 도구 사용

SDK의 도구 실행기와 함께 사용하기 위해 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();

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

// List tools and convert them for the Claude API
const { tools } = await mcpClient.listTools();
const runner = await anthropic.beta.messages.toolRunner({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [{ role: "user", content: "What tools do you have available?" }],
  tools: mcpTools(tools, mcpClient)
});

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-sonnet-4-6",
  max_tokens: 1024,
  messages: mcpMessages(messages)
});

MCP 리소스 사용

MCP 리소스를 콘텐츠 블록으로 변환하여 메시지에 포함하거나 파일 객체로 변환하여 업로드합니다:

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

// As a content block in a message
const resource = await mcpClient.readResource({ uri: "file:///path/to/doc.txt" });
await anthropic.beta.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content: [
        mcpResourceToContent(resource),
        { type: "text", text: "Summarize this document" }
      ]
    }
  ]
});

// As a file upload
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 리소스 링크로 발생할 수 있습니다.

데이터 보존

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-7",
  "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-7",
  "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`	객체	더 이상 지원되지 않음: 대신 `tools` 배열의 MCPToolset을 사용하세요
`tool_configuration.enabled`	부울	더 이상 지원되지 않음: MCPToolset의 `default_config.enabled`를 사용하세요
`tool_configuration.allowed_tools`	배열	더 이상 지원되지 않음: MCPToolset의 `configs`와 함께 허용 목록 패턴을 사용하세요

Was this page helpful?

빌드MCP

MCP 커넥터

Claude의 Model Context Protocol (MCP) 커넥터 기능을 사용하여 Messages API에서 직접 원격 MCP 서버에 연결하는 방법을 알아봅니다.

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

현재 버전: 이 기능은 베타 헤더가 필요합니다: "anthropic-beta": "mcp-client-2025-11-20"

이전 버전(mcp-client-2025-04-04)은 더 이상 지원되지 않습니다. 아래의 더 이상 지원되지 않는 버전 문서를 참조하세요.

This feature is not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.

주요 기능

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

제한 사항

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

Messages API에서 MCP 커넥터 사용

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

MCP 서버 정의 (mcp_servers 배열): 서버 연결 세부 정보(URL, 인증) 정의
MCP 도구 세트 (tools 배열): 활성화할 도구 및 구성 방법 구성

기본 예제

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

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-7",
    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`	문자열	예	현재 "url"만 지원됨
`url`	문자열	예	MCP 서버의 URL. https://로 시작해야 함
`name`	문자열	예	이 MCP 서버의 고유 식별자. `tools` 배열의 정확히 하나의 MCPToolset에서 참조되어야 함
`authorization_token`	문자열	아니오	MCP 서버에서 필요한 경우 OAuth 인증 토큰. MCP 사양 참조

MCP 도구 세트 구성

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`	문자열	예	"mcp_toolset"이어야 함
`mcp_server_name`	문자열	예	`mcp_servers` 배열에 정의된 서버 이름과 일치해야 함
`default_config`	객체	아니오	이 세트의 모든 도구에 적용되는 기본 구성. `configs`의 개별 도구 구성이 이러한 기본값을 재정의합니다.
`configs`	객체	아니오	도구별 구성 재정의. 키는 도구 이름이고 값은 구성 객체입니다.
`cache_control`	객체	아니오	이 도구 세트에 대한 캐시 중단점 구성

도구 구성 옵션

각 도구(default_config 또는 configs에서 구성되든)는 다음 필드를 지원합니다:

속성	유형	기본값	설명
`enabled`	부울	`true`	이 도구가 활성화되어 있는지 여부
`defer_loading`	부울	`false`	true인 경우 도구 설명이 처음에 모델로 전송되지 않습니다. 도구 검색 도구와 함께 사용됩니다.

구성 병합

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

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에서 참조되어야 함
서버당 고유한 도구 세트: 각 MCP 서버는 하나의 MCPToolset에서만 참조될 수 있음
알 수 없는 도구 이름: configs의 도구 이름이 MCP 서버에 존재하지 않으면 백엔드 경고가 기록되지만 오류는 반환되지 않음 (MCP 서버는 동적 도구 가용성을 가질 수 있음)

응답 콘텐츠 유형

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

MCP 도구 사용 블록

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

MCP 도구 결과 블록

{
  "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-7",
  "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 검사기는 테스트 목적으로 액세스 토큰을 얻는 과정을 안내할 수 있습니다.

다음 명령으로 검사기를 실행합니다. 컴퓨터에 Node.js가 설치되어 있어야 합니다.
```
npx @modelcontextprotocol/inspector
```
왼쪽 사이드바에서 "Transport type"에 대해 "SSE" 또는 "Streamable HTTP"를 선택합니다.
MCP 서버의 URL을 입력합니다.
오른쪽 영역에서 "Need to configure authentication?" 다음의 "Open Auth Settings" 버튼을 클릭합니다.
"Quick OAuth Flow"를 클릭하고 OAuth 화면에서 인증합니다.
검사기의 "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 사양의 인증 섹션을 참조하세요.

클라이언트 측 MCP 도우미 (TypeScript)

이러한 도우미는 현재 TypeScript 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)`	MCP 도구를 `client.beta.messages.toolRunner()`와 함께 사용하기 위해 Claude API 도구로 변환
`mcpMessages(messages)`	MCP 프롬프트 메시지를 Claude API 메시지 형식으로 변환
`mcpResourceToContent(resource)`	MCP 리소스를 Claude API 콘텐츠 블록으로 변환
`mcpResourceToFile(resource)`	MCP 리소스를 업로드용 파일 객체로 변환

MCP 도구 사용

SDK의 도구 실행기와 함께 사용하기 위해 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();

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

// List tools and convert them for the Claude API
const { tools } = await mcpClient.listTools();
const runner = await anthropic.beta.messages.toolRunner({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [{ role: "user", content: "What tools do you have available?" }],
  tools: mcpTools(tools, mcpClient)
});

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-sonnet-4-6",
  max_tokens: 1024,
  messages: mcpMessages(messages)
});

MCP 리소스 사용

MCP 리소스를 콘텐츠 블록으로 변환하여 메시지에 포함하거나 파일 객체로 변환하여 업로드합니다:

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

// As a content block in a message
const resource = await mcpClient.readResource({ uri: "file:///path/to/doc.txt" });
await anthropic.beta.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content: [
        mcpResourceToContent(resource),
        { type: "text", text: "Summarize this document" }
      ]
    }
  ]
});

// As a file upload
const fileResource = await mcpClient.readResource({ uri: "file:///path/to/data.json" });
await anthropic.beta.files.upload({ file: mcpResourceToFile(fileResource) });

오류 처리

데이터 보존

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

마이그레이션 가이드

더 이상 지원되지 않는 mcp-client-2025-04-04 베타 헤더를 사용 중인 경우 이 가이드를 따라 새 버전으로 마이그레이션하세요.

주요 변경 사항

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

마이그레이션 단계

이전 (더 이상 지원되지 않음):

{
  "model": "claude-opus-4-7",
  "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-7",
  "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`	객체	더 이상 지원되지 않음: 대신 `tools` 배열의 MCPToolset을 사용하세요
`tool_configuration.enabled`	부울	더 이상 지원되지 않음: MCPToolset의 `default_config.enabled`를 사용하세요
`tool_configuration.allowed_tools`	배열	더 이상 지원되지 않음: MCPToolset의 `configs`와 함께 허용 목록 패턴을 사용하세요

Was this page helpful?