Agent SDK로 MCP 서버 연결하기

Agent SDK로 MCP 서버 연결하기

Anthropic Agent SDK에서 Model Context Protocol(MCP) 서버를 찾고 연결하는 방법을 다루는 가이드예요. Agent.connectServer()로 표준 MCP 서버를 에이전트에 연결해 외부 도구를 노출시키고, 구체적인 ClientSession(stdlib 또는 HTTP)을 붙여 전송을 직접 다룰 수도 있어요. MCP의 도구·프롬프트·리소스를 SDK의 앱과 통합하는 핵심 지점이에요.

출처: 공식문서

본문

MCP 서버 연결

가장 흔한 방법은 Agent.connectServer()로 호스트 프로세스에 MCP 서버를 연결하는 거예요. 서버의 도구가 에이전트의 도구 목록에 병합되고, 연결 후 에이전트가 즉시 사용할 수 있어요.

TypeScript

import { Agent } from "@anthropic-ai/sdk";
import { StdioClientTransport } from "@anthropic-ai/sdk/client";
import {
  StdioMCPClient,
  type StdioMCPClientTransport,
} from "@anthropic-ai/sdk/client";

async function main() {
  const agent = new Agent({
    type: "generic",
    id: "main-agent",
    systemPrompt: `MCP 도구를 사용해 작업을 완료하세요.`,
  });

  await agent.connectServer("sqlite-db", {
    type: "stdio",
    command: "uvx",
    args: ["mcp-server-sqlite", "--db-path", "./test.db"],
    cwd: __dirname,
  });

  const result = await agent.run("test.db의 모든 테이블을 나열하세요.");
  console.log(result);
}

main().catch(console.error);

agent.connectServer 시그니처는:

connectServer(
  serverId: string,
  transport: string | StdioClientTransport | { type: "stdio"; command: string; args?: string[]; cwd?: string } | { type: "http"; url: string; headers?: Record<string, string> },
  options?: { subscriptionGuids?: string[] }
): Promise<void>

클라이언트 세션 만들기

Agent.connectServer가 자동으로 서버와의 세션을 관리한다면, ClientSession은 전송을 직접 다루는 더 낮은 수준의 제어를 줘요. 표준 stdio 서버든 원격 HTTP 서버든 ClientSession이 프로토콜 메시지를 주고받아요.

TypeScript — stdio ClientSession

import { ClientSession, StdioMCPClientTransport } from "@anthropic-ai/sdk/client";

const transport = new StdioMCPClientTransport({
  command: "npx",
  args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
});

const session = await ClientSession.connect(transport);

const tools = await session.listTools();
console.log(tools);

await session.close();

Python — stdio ClientSession

from anthropic import ClientSession, StdioClientTransport

transport = StdioClientTransport(command="npx", args=["-y", "@modelcontextprotocol/server-filesystem", "/tmp"])
async with ClientSession(transport) as session:
    tools = await session.list_tools()
    print(tools)

ClientSession에 수동으로 에이전트 연결

ClientSession을 직접 만들었다면 agent.connectSession()으로 에이전트에 붙일 수 있어요. 이렇게 하면 여러 에이전트가 같은 세션을 공유하거나, 에이전트를 돌리기 전에 세션을 준비하는 흐름을 제어할 수 있어요.

TypeScript

import { Agent } from "@anthropic-ai/sdk";
import { ClientSession } from "@anthropic-ai/sdk/client";

const agent = new Agent({
  type: "generic",
  id: "main-agent",
  systemPrompt: "쿼리에 답하세요.",
});

const session = await ClientSession.connect(transport);
await agent.connectSession("filesystem", session);

const result = await agent.run("루트 디렉터리의 파일을 나열하세요.");
console.log(result);

MCP 프롬프트 코드(라이브러리 팩토리 위임)

MCP 서버는 프롬프트를 노출할 수 있어요. SDK는 서버에서 prompts를 얻고, 그 프롬프트 정의를 사용해 promptReader를 구성할 수 있어요. 예를 들어 sourceFilesFromPrompt(n) 같은 함수형 코드로 프롬프트를 호출할 수 있게 합니다.

원격 HTTP MCP 지원

SDK는 원격 HTTP(S) MCP 서버 연결을 지원해요. /mcp 엔드포인트에 ClientSession을 연결하거나 agent.connectServer에 { type: "http", url } 전송을 넘기면 돼요. 인증이 필요하면 headers에 베어러 토큰을 넣어요.

TypeScript — HTTP 서버 연결

const session = await ClientSession.connect({
  type: "http",
  url: "https://your-mcp-server.example.com/mcp",
  headers: { Authorization: "Bearer <your-token>" },
});

MCP 구독

일부 MCP 서버는 리소스·도구 변경 알림(구독)을 제공해요. ClientSession은 서버가 구독을 지원하면 변경 알림을 받을 수 있고, connectServer의 subscriptionGuids 옵션으로 특정 구독에만 연결할 수 있어요. 서버가 구독 요청을 지원하지 않으면 그 GUID는 무시돼요.

TypeScript — 구독 항목으로 서버 연결

await agent.connectServer(
  "notificationsServer",
  { type: "stdio", command: "node", args: ["./server.js"] },
  { subscriptionGuids: ["mcp.resource.requests", "mcp.tool.changes"] }
);

다중 전송

원격 HTTP와 로컬 stdio 두 전송을 하나의 세션에 결합하거나, 같은 서버 자격 증명으로 여러 세션을 재연결해 자동 재연결 동작을 얻을 수 있어요. 멀티플렉싱(멀티 전송 연결)은 라이브러리 팩토리에서 관리됩니다.

더 알아보기