핵심 표면

MCP server 연결
  -> mcpServers 옵션 또는 .mcp.json
  -> 도구 이름은 mcp__<server>__<tool>
  -> allowedTools로 명시 허용
  -> agent가 외부 데이터와 도구 사용

연결 방식

SDK에서는 MCP 서버를 코드나 설정 파일로 연결한다

Agent SDK에서 MCP 서버는 query() 호출의 mcpServers 옵션으로 직접 넘기거나, 프로젝트 루트의 .mcp.json에서 불러올 수 있습니다. 코드 안에 넣으면 agent별 구성이 명확하고, .mcp.json을 쓰면 프로젝트 공통 연결을 재사용하기 쉽습니다.

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "List files in the allowed project directory",
  options: {
    mcpServers: {
      filesystem: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-filesystem", "/workspace/project"]
      }
    },
    allowedTools: ["mcp__filesystem__*"]
  }
})) {
  console.log(message);
}

외부 도구 연결은 편의 기능이 아니라 agent의 권한 표면을 넓히는 설정입니다. 어떤 서버가 어떤 데이터와 side effect를 제공하는지 먼저 정리해야 합니다.

MCP tool 이름은 서버 이름과 도구 이름으로 만들어진다

MCP tool은 mcp__<server-name>__<tool-name> 패턴으로 노출됩니다. 예를 들어 github 서버의 list_issues 도구는 mcp__github__list_issues처럼 볼 수 있습니다. 이 이름을 알아야 allowedTools에서 정확히 허용하거나 차단할 수 있습니다.

mcp__github__list_issues
mcp__github__create_issue
mcp__db__query
mcp__slack__send_message

와일드카드로 mcp__github__*를 허용하면 해당 서버의 모든 도구를 열 수 있습니다. 읽기 도구만 필요한 agent라면 전체 허용보다 특정 tool만 지정하는 편이 안전합니다.

allowedTools 없이는 연결만으로 충분하지 않다

공식 문서 기준으로 MCP tool은 명시적 permission이 필요합니다. 서버를 연결해도 allowedTools에 들어 있지 않으면 Claude가 도구를 볼 수는 있어도 바로 사용할 수 없습니다. 이 구조는 "연결"과 "실행 허용"을 분리해 권한을 좁히기 위한 장치입니다.

const options = {
  mcpServers: {
    db: {
      command: "node",
      args: ["./mcp-db-server.js"]
    }
  },
  allowedTools: ["mcp__db__query"]
};

DB, issue tracker, Slack, 배포 시스템처럼 쓰기 side effect가 있는 서버는 읽기 도구와 쓰기 도구를 분리해서 허용해야 합니다.

project 설정을 불러올 때는 setting source를 확인한다

.mcp.json은 project 설정 source가 활성화되어 있을 때 읽힙니다. SDK 옵션에서 setting source를 명시적으로 조정하면 .mcp.json이 로드되지 않을 수 있으므로, agent가 어떤 설정 source를 읽는지 확인해야 합니다.

project .mcp.json
  -> project setting source 필요
  -> agent options에서 명시적으로 제외하면 로드 안 됨

여러 agent가 같은 프로젝트에서 다른 MCP 권한을 가져야 한다면, 공통 .mcp.json과 agent별 allowedTools를 분리하는 방식이 관리하기 쉽습니다.

체크포인트

주의할 점

민감 데이터가 있는 MCP 서버는 agent prompt만으로 보호하지 말고 서버 자체 권한, 네트워크 접근, API token scope, audit log를 함께 제한해야 합니다. Agent SDK는 사용 표면을 만들 뿐, 외부 시스템의 권한 설계를 대신하지 않습니다.