Claude의 모델 컨텍스트 프로토콜(MCP) 커넥터 기능을 사용하면 별도의 MCP 클라이언트 없이 Messages API에서 직접 원격 MCP 서버에 연결할 수 있습니다.

이 기능은 베타 헤더가 필요합니다: "anthropic-beta": "mcp-client-2025-04-04"

​
주요 기능

  • 직접 API 통합: MCP 클라이언트를 구현하지 않고도 MCP 서버에 연결
  • 도구 호출 지원: Messages API를 통해 MCP 도구에 접근
  • OAuth 인증: 인증된 서버를 위한 OAuth Bearer 토큰 지원
  • 다중 서버: 단일 요청에서 여러 MCP 서버에 연결

​
제한 사항

  • MCP 사양의 기능 세트 중에서 현재는 도구 호출만 지원됩니다.
  • 서버는 HTTP를 통해 공개적으로 노출되어야 합니다. 로컬 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": "어떤 도구를 사용할 수 있나요?"}],
    "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": "mcp-server-1과 mcp-server-2의 도구를 모두 사용하여 이 작업을 완료하세요"
    }
  ],
  "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 사양의 인증 섹션을 참조하세요.