핵심 요약
MCP Connector는 Claude Messages API에서 원격 MCP 서버의 도구를 직접 연결해 쓰게 해주는 기능입니다.
현재 버전은 mcp-client-2025-11-20 베타 헤더가 필요하며, 이전 버전 mcp-client-2025-04-04는 폐기 예정입니다.
이 기능은 ZDR 대상이 아니며, MCP 서버와 주고받은 도구 정의와 실행 결과는 표준 데이터 보존 정책을 따릅니다.
MCP Connector란 무엇인가
MCP Connector는 Claude가 외부 MCP 서버의 도구를 직접 사용할 수 있게 해주는 연결 장치입니다.
원래 MCP 서버를 쓰려면 별도의 MCP 클라이언트를 구현해야 했지만, 이 기능을 사용하면 Messages API 요청 안에서 서버 URL과 도구 설정을 함께 전달할 수 있습니다.
비유하면 Claude에게 "이 주소에 있는 도구 상자를 열어도 된다"고 알려주는 방식입니다.
현재 지원 범위와 제한
현재 MCP Connector는 MCP 사양 전체가 아니라 "도구 호출"만 지원합니다.
MCP 서버는 인터넷에서 접근 가능한 HTTPS URL이어야 합니다. Streamable HTTP와 SSE 방식은 지원하지만, 로컬 STDIO 서버는 직접 연결할 수 없습니다.
Amazon Bedrock과 Google Vertex에서는 현재 사용할 수 없습니다.
요청 구조는 두 부분으로 나뉜다
MCP Connector 설정은 크게 mcp_servers와 tools로 나뉩니다.
mcp_servers는 "어떤 MCP 서버에 연결할 것인가"를 정의합니다.
tools 안의 mcp_toolset은 "그 서버의 어떤 도구를 Claude에게 허용할 것인가"를 정합니다.
즉, 서버 등록과 도구 권한 설정을 분리한 구조입니다.
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"],
)MCP 서버 정의의 핵심 필드
MCP 서버는 mcp_servers 배열 안에 정의합니다.
type은 현재 "url"만 지원합니다.
url은 MCP 서버 주소이며 반드시 https://로 시작해야 합니다.
name은 서버를 구분하는 고유 이름입니다. 이 이름은 tools 배열의 MCPToolset에서 정확히 한 번 참조되어야 합니다.
authorization_token은 인증이 필요한 MCP 서버에 전달하는 OAuth Bearer 토큰입니다.
MCPToolset은 도구 사용 규칙을 정한다
mcp_toolset은 특정 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
}
}
}default_config는 전체 도구에 적용되는 기본값입니다.
configs는 특정 도구에만 적용되는 예외 규칙입니다.
enabled는 도구 사용 가능 여부를 정하고, defer_loading은 도구 설명을 처음부터 모델에 보내지 않을지 정합니다.
설정 우선순위는 가까운 규칙이 이긴다
도구 설정은 세 단계로 합쳐집니다.
가장 우선하는 것은 configs에 적힌 개별 도구 설정입니다.
그다음은 default_config, 마지막은 시스템 기본값입니다.
예를 들어 전체 도구에 defer_loading: true를 주고, 특정 도구만 enabled: false로 설정하면 해당 도구는 비활성화되지만 지연 로딩 설정은 기본값에서 물려받습니다.
이 구조 덕분에 "대부분은 같은 규칙, 일부만 예외"라는 운영 방식이 쉬워집니다.
자주 쓰는 도구 허용 패턴
모든 도구를 허용하려면 MCPToolset만 단순히 선언하면 됩니다.
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp"
}특정 도구만 허용하려면 기본값을 비활성화하고 필요한 도구만 켭니다.
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp",
"default_config": {
"enabled": false
},
"configs": {
"search_events": {
"enabled": true
},
"create_event": {
"enabled": true
}
}
}반대로 대부분 허용하되 위험한 도구만 막는 denylist 방식도 가능합니다.
예를 들어 일정 조회는 허용하되 전체 삭제나 공개 공유 같은 도구만 꺼둘 수 있습니다.
검증 규칙과 응답 블록
API는 MCP 서버와 도구셋의 연결 관계를 엄격하게 확인합니다.
mcp_server_name은 반드시 mcp_servers에 정의된 이름과 일치해야 합니다.
정의된 모든 MCP 서버는 정확히 하나의 MCPToolset에서 참조되어야 합니다.
하나의 MCP 서버를 여러 MCPToolset이 중복 참조할 수 없습니다.
Claude가 MCP 도구를 사용하면 응답에는 mcp_tool_use와 mcp_tool_result라는 블록이 포함됩니다.
mcp_tool_use는 어떤 도구를 어떤 입력으로 호출했는지 나타내고, mcp_tool_result는 그 실행 결과를 담습니다.
여러 MCP 서버와 인증 처리
한 요청에서 여러 MCP 서버를 동시에 연결할 수 있습니다.
각 서버는 mcp_servers에 따로 정의하고, tools에는 각 서버에 대응하는 MCPToolset을 하나씩 둡니다.
인증이 필요한 MCP 서버는 API 호출 전에 OAuth 액세스 토큰을 직접 확보해야 합니다.
테스트용 토큰은 MCP Inspector를 통해 얻을 수 있으며, 얻은 토큰은 authorization_token 필드에 넣습니다.
토큰 갱신 역시 API 사용자가 직접 처리해야 합니다.
TypeScript SDK의 클라이언트 측 MCP 헬퍼
원격 URL 서버의 도구만 필요하면 mcp_servers API 파라미터를 쓰면 됩니다.
하지만 로컬 STDIO 서버, MCP 프롬프트, MCP 리소스, 더 세밀한 연결 제어가 필요하면 TypeScript SDK의 MCP 헬퍼를 사용할 수 있습니다.
제공되는 주요 헬퍼는 다음과 같습니다.
mcpTools는 MCP 도구를 Claude API 도구 형식으로 바꿉니다.
mcpMessages는 MCP 프롬프트 메시지를 Claude 메시지 형식으로 바꿉니다.
mcpResourceToContent는 MCP 리소스를 메시지 콘텐츠 블록으로 바꿉니다.
mcpResourceToFile은 MCP 리소스를 업로드 가능한 파일 객체로 바꿉니다.
지원하지 않는 MCP 값이 들어오면 UnsupportedMCPValueError가 발생할 수 있습니다.
이전 베타 버전에서 마이그레이션하기
이전 버전 mcp-client-2025-04-04에서는 도구 설정이 MCP 서버 정의 안에 들어 있었습니다.
새 버전 mcp-client-2025-11-20에서는 도구 설정이 tools 배열의 MCPToolset으로 이동했습니다.
예전의 tool_configuration.allowed_tools는 이제 default_config.enabled: false와 configs의 개별 도구 활성화로 표현합니다.
즉, 새 구조의 핵심은 "서버 연결 정보는 mcp_servers, 도구 정책은 tools"입니다.
인사이트
MCP Connector의 핵심은 Claude에게 외부 도구를 연결하되, 도구 접근 권한을 API 요청 단위에서 세밀하게 통제할 수 있다는 점입니다.
실무에서는 처음부터 모든 도구를 열기보다 allowlist 방식으로 필요한 도구만 허용하는 편이 안전합니다.
특히 삭제, 공유, 결제, 권한 변경처럼 영향이 큰 도구는 기본적으로 비활성화하고 명시적으로 검토한 뒤 허용하는 것이 좋습니다.
출처 및 참고 : MCP connector - Claude API Docs
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.