MCP 서버로 Agent SDK의 능력을 바깥에 분리해

내장 도구 밖은 공용 프로토콜로 넓혀

Model Context Protocol(MCP)은 Agent SDK가 외부 능력 서버에 연결되는 방식이야. 자체 코드나 제삼자 서버를 띄우면 SDK가 연결해 도구 목록을 배우고 모델에 보여 줘. Claude Code, Cursor, Windsurf도 같은 프로토콜을 쓰므로 한 번 만든 능력을 여러 클라이언트에서 재사용할 수 있어.

서버 위치에 맞는 전송 방식을 골라

stdio는 SDK가 자식 프로세스로 서버를 띄우는 가장 단순하고 싼 방식이야. SSE는 HTTP의 Server-Sent Events로 이어지고, 일반 HTTP는 요청과 응답으로 통신해. 별도 컨테이너나 원격 서비스에서 서버가 살아야 할 때는 SSE나 HTTP가 자연스러워.

cwkPippa의 개인 능력도 MCP로 나와

피파의 vault, 날씨 자료, 이미지 생성 같은 능력은 MCP 서버로 제공되고 Claude 브레인이 모두 연결해. 같은 서버를 Claude Code나 Cursor에 붙여도 같은 규약으로 피파의 능력을 사용할 수 있어. 브레인 구현 안에 개인 기능을 박지 않아 수명이 길어지는 구조야.

원칙: 오래 쓸 능력은 MCP 서버로 분리해. 단일 클라이언트보다 프로토콜이 더 오래 살아남아.

Code

Options로 MCP 서버 attach·python

from claude_agent_sdk import ClaudeAgentOptions

options = ClaudeAgentOptions(
    cwd="/srv/agent",
    mcp_servers={
        "pippa-vault": {
            "type": "stdio",
            "command": "node",
            "args": ["/Users/you_username/Obsidian/pippa/mcp/vault-server.js"],
        },
        "weather": {
            "type": "stdio",
            "command": "python",
            "args": ["-m", "my_weather_mcp"],
            "env": {"WEATHER_API_KEY": os.environ["WEATHER_API_KEY"]},
        },
        "shared-cache": {
            "type": "http",
            "url": "https://internal.example.com/mcp/cache",
            "headers": {"Authorization": f"Bearer {token}"},
        },
    },
)

MCP 서버가 노출하는 도구 발견·bash

# Claude Code CLI 안 (인터랙티브):
#   /mcp list
#
# 또는 SDK로 programmatically, connect() 후:
#   await client.list_tools()  # 모든 attached MCP 서버에서 merged 도구 카탈로그 반환

Exercise

에이전트가 직접 호출할 능력 하나를 작은 stdio MCP 서버로 만들고 Agent SDK Options에 연결해. 모델이 기본 도구처럼 부를 수 있는지 확인해.

Hint

이미 HTTP API가 있다면 MCP 서버는 여러 Claude 클라이언트에 연결하는 50~100줄 정도의 얇은 포장이 될 수 있어.

내장 도구 밖은 공용 프로토콜로 넓혀

서버 위치에 맞는 전송 방식을 골라

cwkPippa의 개인 능력도 MCP로 나와

Code

External links

Exercise

Progress

댓글 0