MCP 服务器集成

Model Context Protocol (MCP) 是连接 AI Agent 与外部工具和数据源的开放标准。通过 MCP，Agent 可以查询数据库、集成 GitHub/Slack 等 API，无需编写自定义工具实现。

核心机制

三种传输类型：

• stdio：本地子进程，通过 stdin/stdout 通信，适合本机运行的 MCP 服务器
• HTTP/SSE：远程服务器，适合云托管的 MCP 服务器
• SDK MCP 服务器：进程内自定义工具，参考 custom-tools

工具命名规则：mcp__<server_name>__<tool_name>，例如 GitHub 服务器的 list_issues 工具变为 mcp__github__list_issues。

MCP 工具必须显式授权：Claude 能看到工具但无法调用，直到在 allowed_tools 中列出。通配符 mcp__github__* 可授权服务器的所有工具。

Tool Search 默认开启：工具数量多时，MCP 工具定义默认按需加载而非全部预加载，节省上下文空间。

关键细节

stdio 服务器（本地进程）：

options = ClaudeAgentOptions(
    mcp_servers={
        "github": {
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-github"],
            "env": {"GITHUB_TOKEN": os.environ["GITHUB_TOKEN"]},
        }
    },
    allowed_tools=["mcp__github__list_issues"],
)

HTTP 服务器（远程）：

mcp_servers={
    "remote-api": {
        "type": "sse",  # 或 "http"
        "url": "https://api.example.com/mcp/sse",
        "headers": {"Authorization": f"Bearer {token}"},
    }
}

配置文件方式：在项目根目录创建 .mcp.json，通过 settingSources: ["project"] 自动加载。

检测连接状态：

if isinstance(message, SystemMessage) and message.subtype == "init":
    failed = [s for s in message.data.get("mcp_servers", []) if s.get("status") != "connected"]

OAuth2：SDK 不自动处理 OAuth 流程，需在应用层完成 OAuth 后将 access token 通过 headers 传入。

与其他概念的关联

• custom-tools - 进程内自定义工具（vs 外部 MCP 服务器）
• tool-search - 大量 MCP 工具时的按需加载
• permissions - MCP 工具权限控制（acceptEdits 不自动批准 MCP 工具）

实践要点

• 优先用 allowedTools 通配符授权 MCP 工具，而非 bypassPermissions（后者影响范围太广）
• MCP 连接超时默认 60 秒，启动慢的服务器需要预热或检查初始化原因
• Vertex AI 上 Tool Search 默认关闭，需显式设置 ENABLE_TOOL_SEARCH=true
• 非 Anthropic 代理（ANTHROPIC_BASE_URL 指向第三方）也默认关闭 Tool Search
• 连接失败常见原因：环境变量未设置、npm 包未安装、数据库连接字符串格式错误