Agent SDK에서 MCP로 외부 도구 연결
기준일: 2026-07-26 · CLI 기준 2.1.220
개요
MCP(Model Context Protocol)로 에이전트에 외부 도구·데이터 소스를 연결합니다. SDK는 코드의 mcpServers/mcp_servers, 설정 파일, 여러 transport(stdio, HTTP/SSE, in-process SDK server)를 지원합니다.
핵심 개념
- 서버 맵: 이름 → 연결 설정
- 도구 이름:
mcp__<server>__<tool> - allowedTools: 화이트리스트·자동 승인 (와일드카드 가능)
- Transport: stdio 프로세스, HTTP/SSE 원격,
createSdkMcpServer인프로세스 - 연결 시점: 세션 초기화 시; 상태는 init/status로 확인
상세
코드에서 추가
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "List open issues assigned to me",
options: {
mcpServers: {
github: {
command: "npx",
args: ["-y", "@modelcontextprotocol/server-github"],
env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN! }
}
},
allowedTools: ["mcp__github__*"]
}
})) {
// handle stream
}
from claude_agent_sdk import query, ClaudeAgentOptions
import asyncio, os
async def main():
async for message in query(
prompt="List open issues assigned to me",
options=ClaudeAgentOptions(
mcp_servers={
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {"GITHUB_TOKEN": os.environ["GITHUB_TOKEN"]},
}
},
allowed_tools=["mcp__github__*"],
),
):
pass
asyncio.run(main())
설정 파일
.mcp.json 또는 settings MCP 정의는 settingSources에 project/user가 있을 때 CLI와 같이 로드됩니다. 멀티테넌트·재현 가능한 배포에서는 strictMcpConfig와 명시적 mcpServers를 권장합니다. claude.ai connectors는 로그인 방식에 따라 별도로 로드될 수 있습니다.
도구 허용·발견
- 정확한 이름 또는
mcp__server__*패턴 - 미허용 시 permission mode에 따라 프롬프트 또는 deny
- 사용 가능 도구는 init 메시지·MCP status·프롬프트 질문으로 확인
- MCP tool search로 도구가 많을 때 스키마 지연 로드
Transport
| 유형 | 설정 요지 |
|---|---|
| stdio | command, args, env, cwd |
| HTTP/SSE | URL, headers |
| SDK server | createSdkMcpServer / create_sdk_mcp_server + tool() 정의 |
인증
- stdio: 환경변수 토큰
- HTTP: 헤더 맵
- OAuth2: 원격 서버 플로우 (공식 OAuth 절)
시크릿을 저장소에 커밋하지 마세요.
예시 패턴
- 저장소 이슈 목록 (GitHub MCP)
- 데이터베이스 질의 (SQL MCP)
- 인프로세스 커스텀 도구 서버로 앱 내부 API 노출
오류·문제 해결
| 증상 | 조치 |
|---|---|
| status failed | binary path, env, 서버 stderr |
| 도구 미호출 | 이름·allowedTools·설명 |
| connection timeout | 네트워크·방화벽·콜드 스타트 |
| output exceeds max tokens | 페이징·요약·서버 측 limit |
| auth 실패 | 토큰 만료·스코프 |
체크리스트
- transport·인증 경로 확정
-
allowedTools에mcp__...패턴 - 시크릿은 env/secret manager
- 실패 status 관측
- 멀티테넌트면 strictMcpConfig 검토