MCP 커넥터
Claude의 Model Context Protocol (MCP) 커넥터 기능을 사용하여 별도의 MCP 클라이언트 없이 Messages API에서 직접 원격 MCP 서버에 연결하는 방법을 알아보세요.
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
매개변수를 포함하세요:
MCP 서버 구성
mcp_servers
배열의 각 MCP 서버는 다음 구성을 지원합니다:
필드 설명
속성 | 타입 | 필수 | 설명 |
---|---|---|---|
type | string | 예 | 현재 “url”만 지원됩니다 |
url | string | 예 | MCP 서버의 URL. https://로 시작해야 합니다 |
name | string | 예 | 이 MCP 서버의 고유 식별자. mcp_tool_call 블록에서 서버를 식별하고 모델에 도구를 구분하는 데 사용됩니다. |
tool_configuration | object | 아니오 | 도구 사용 구성 |
tool_configuration.enabled | boolean | 아니오 | 이 서버의 도구를 활성화할지 여부 (기본값: true) |
tool_configuration.allowed_tools | array | 아니오 | 허용할 도구를 제한하는 목록 (기본적으로 모든 도구가 허용됩니다) |
authorization_token | string | 아니오 | MCP 서버에서 필요한 경우 OAuth 인증 토큰. MCP 사양을 참조하세요. |
응답 콘텐츠 타입
Claude가 MCP 도구를 사용할 때 응답에는 두 가지 새로운 콘텐츠 블록 타입이 포함됩니다:
MCP 도구 사용 블록
MCP 도구 결과 블록
다중 MCP 서버
mcp_servers
배열에 여러 객체를 포함하여 여러 MCP 서버에 연결할 수 있습니다:
인증
OAuth 인증이 필요한 MCP 서버의 경우 액세스 토큰을 얻어야 합니다. MCP 커넥터 베타는 MCP 서버 정의에서 authorization_token
매개변수 전달을 지원합니다.
API 소비자는 API 호출을 하기 전에 OAuth 플로우를 처리하고 액세스 토큰을 얻을 뿐만 아니라 필요에 따라 토큰을 새로 고칠 것으로 예상됩니다.
테스트용 액세스 토큰 얻기
MCP 인스펙터는 테스트 목적으로 액세스 토큰을 얻는 과정을 안내할 수 있습니다.
-
다음 명령으로 인스펙터를 실행합니다. 컴퓨터에 Node.js가 설치되어 있어야 합니다.
-
왼쪽 사이드바에서 “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 서버 구성에서 사용할 수 있습니다:
OAuth 플로우에 대한 자세한 설명은 MCP 사양의 인증 섹션을 참조하세요.