Claude의 Model Context Protocol (MCP) 커넥터 기능을 사용하면 별도의 MCP 클라이언트 없이 Messages API에서 직접 원격 MCP 서버에 연결할 수 있습니다.
이 기능을 사용하려면 베타 헤더가 필요합니다: "anthropic-beta": "mcp-client-2025-04-04"

​
주요 기능

  • 직접 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 서버에 연결하려면 Messages API 요청에 mcp_servers 매개변수를 포함하세요: 
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-04-04" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "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"
      }
    ]
  }'

​
MCP 서버 구성

mcp_servers 배열의 각 MCP 서버는 다음 구성을 지원합니다: 
{
  "type": "url",
  "url": "https://example-server.modelcontextprotocol.io/sse",
  "name": "example-mcp",
  "tool_configuration": {
    "enabled": true,
    "allowed_tools": ["example_tool_1", "example_tool_2"]
  },
  "authorization_token": "YOUR_TOKEN"
}

​
필드 설명

속성타입필수설명
typestring예현재 “url”만 지원됩니다
urlstring예MCP 서버의 URL. https://로 시작해야 합니다
namestring예이 MCP 서버의 고유 식별자. mcp_tool_call 블록에서 서버를 식별하고 모델에 도구를 구분하는 데 사용됩니다.
tool_configurationobject아니오도구 사용 구성
tool_configuration.enabledboolean아니오이 서버의 도구를 활성화할지 여부 (기본값: true)
tool_configuration.allowed_toolsarray아니오허용할 도구를 제한하는 목록 (기본적으로 모든 도구가 허용됩니다)
authorization_tokenstring아니오MCP 서버에서 필요한 경우 OAuth 인증 토큰. 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 배열에 여러 객체를 포함하여 여러 MCP 서버에 연결할 수 있습니다: 
{
  "model": "claude-sonnet-4-20250514",
  "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"
    }
  ]
}

​
인증

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

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

MCP 인스펙터는 테스트 목적으로 액세스 토큰을 얻는 과정을 안내할 수 있습니다.
  1. 다음 명령으로 인스펙터를 실행합니다. 컴퓨터에 Node.js가 설치되어 있어야 합니다. 
    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. 인스펙터의 “OAuth Flow Progress” 섹션의 단계를 따르고 “Authentication complete”에 도달할 때까지 “Continue”를 클릭합니다.
  7. access_token 값을 복사합니다.
  8. 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 사양의 인증 섹션을 참조하세요.