精读：Claude Code MCP 深度集成

MCP 对于 Claude Code 不是”可选扩展”——它是核心扩展协议。Plugin = MCP Server，Skill 发现 = MCP 工具发现，跨 Agent 协作 = MCP 互操作。理解 Claude Code 的 MCP 实现就是理解它的生态策略。

MCP 在 Claude Code 中的定位

┌──────────────────────────────────────────────┐
│              Claude Code 能力层               │
│                                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  │
│  │ 内置工具  │  │ MCP 工具  │  │ Hook 拦截 │  │
│  │(Read/Bash)│  │(Plugin)   │  │(审计/增强) │  │
│  └─────┬────┘  └─────┬────┘  └─────┬────┘  │
│        │              │              │       │
│        └──────────────┼──────────────┘       │
│                       │                      │
│              ┌────────▼────────┐             │
│              │   MCP 协议层     │             │
│              │  (统一工具接口)   │             │
│              └────────┬────────┘             │
│                       │                      │
│         ┌─────────────┼─────────────┐        │
│         ▼             ▼             ▼        │
│  ┌────────────┐┌────────────┐┌──────────┐   │
│  │ Local MCP  ││ Remote MCP ││ Agent MCP│   │
│  │ (stdio)    ││ (HTTP/SSE) ││ (互操作) │   │
│  └────────────┘└────────────┘└──────────┘   │
└──────────────────────────────────────────────┘

源码结构

基于泄露源码分析（services/mcp/ 目录，23 个文件）：

文件/模块	职责
`transport/`	7 种传输实现
`client.ts`	MCP Client 核心（连接管理、工具发现）
`server.ts`	MCP Server 暴露（`claude mcp serve`）
`auth/`	OAuth 浏览器流 + Bearer Token
`elicitation.ts`	用户交互表单处理
`tool-search.ts`	延迟加载 + 按需搜索
`config.ts`	三层配置合并逻辑
`reconnect.ts`	自动重连 + 重试
`push.ts`	Channel 推送消息

7 种传输实现

1. stdio（默认本地传输）

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
    }
  }
}

Claude Code 作为父进程启动 MCP Server 子进程
通过 stdin/stdout 交换 JSON-RPC 2.0 消息
零网络开销，最低延迟
适用场景：本地工具（文件系统、数据库、Git）

2. Streamable HTTP（推荐远程传输）

{
  "mcpServers": {
    "remote-api": {
      "url": "https://mcp.example.com/v1",
      "headers": { "Authorization": "Bearer ${API_KEY}" }
    }
  }
}

HTTP POST 发送请求
服务器可选用 SSE 流式返回多条消息
支持断线恢复（Connection ID + 重连）
适用场景：远程 API、云端服务

3. SSE（兼容旧版）

旧版 MCP 规范的远程传输
单向推送（Server → Client）
已被 Streamable HTTP 取代，但 Claude Code 仍兼容

4. WebSocket（全双工）

非 MCP 规范标准，Claude Code 自行支持
用于需要双向实时通信的场景
Neovim 集成通过 WebSocket 连接

5. 自动重连

不是独立传输，而是包装层
检测连接断开 → 指数退避重试
重连后自动重新发现工具
保证长时间运行的 session 不因网络波动中断

6. Channel（Push Messages）

MCP 服务器主动向 Claude Code 推送事件
不依赖 Claude Code 轮询
用于：实时日志、构建状态、外部事件通知
2025-11-25 规范正式化

7. Auth Stub（Headless/SDK 模式）

在无浏览器环境（CI/CD、Docker、远程服务器）中处理认证
将认证流隔离到独立进程
支持预配置 token 注入

三层配置系统

优先级

Local（最高） > Project（中） > User（最低）

Local 配置

位置：~/.claude.json（当前项目路径下解析）

适用：仅个人、不共享。用于个人 API key、本地开发工具。

Project 配置

位置：.mcp.json（仓库根目录）

{
  "mcpServers": {
    "team-db": {
      "command": "npx",
      "args": ["@company/mcp-db-server"],
      "env": {
        "DB_HOST": "${DB_HOST:-localhost}",
        "DB_PORT": "${DB_PORT:-5432}"
      }
    }
  }
}

适用：团队共享（git 提交），CI/CD 环境变量展开。

环境变量语法：

${VAR}：必须存在
${VAR:-default}：不存在时使用默认值

User 配置

位置：~/.claude.json（全局区域）

适用：个人所有项目通用的 MCP 服务器（如日历、邮件、笔记）。

OAuth 认证流

完整浏览器流程

┌─────────────┐     ┌──────────────┐     ┌────────────────┐
│ Claude Code │     │ Local HTTP   │     │ OAuth Provider │
│ (Client)    │     │ Server       │     │ (GitHub/etc)   │
└──────┬──────┘     └──────┬───────┘     └───────┬────────┘
       │                   │                      │
       │ 1. 启动本地 Server │                      │
       │──────────────────▶│                      │
       │                   │                      │
       │ 2. 打开浏览器      │                      │
       │──────────────────────────────────────────▶│
       │                   │                      │
       │                   │    3. 用户授权         │
       │                   │◀─────────────────────│
       │                   │                      │
       │ 4. 回调 + code    │                      │
       │◀──────────────────│                      │
       │                   │                      │
       │ 5. 交换 token     │                      │
       │──────────────────────────────────────────▶│
       │                   │                      │
       │ 6. 存储 token     │  7. 注入后续请求      │
       │───────────────────┘──────────────────────┘

配置选项

选项	说明
`--oauth-port`	固定回调端口（避免防火墙问题）
预配置凭据	跳过浏览器流（CI/CD 场景）
metadata discovery 覆盖	自定义 well-known URL
scope 限制	只申请必要权限
动态 headers	自定义认证头（非 OAuth 场景）

Elicitation 机制

什么是 Elicitation

MCP 服务器在工具执行过程中，可能需要用户提供额外信息（如确认操作、选择参数、输入凭据）。Elicitation 提供了标准化的交互方式。

两种模式

内联表单：

// MCP Server → Claude Code
{
  "method": "elicitation/request",
  "params": {
    "schema": {
      "type": "object",
      "properties": {
        "environment": {
          "type": "string",
          "enum": ["dev", "staging", "production"],
          "description": "选择部署目标环境"
        },
        "confirm": {
          "type": "boolean",
          "description": "确认执行部署？"
        }
      }
    }
  }
}

Claude Code 在终端中渲染表单，用户填写后返回结果。

URL mode（2025-11-25 规范新增）：

{
  "method": "elicitation/request",
  "params": {
    "url": "https://auth.example.com/consent?scope=deploy",
    "description": "请在浏览器中完成授权"
  }
}

适用于需要浏览器完成的复杂交互（如 OAuth 同意页）。

Tool Search（延迟加载）

问题

当连接多个 MCP 服务器，每个暴露 20+ 工具时，总工具数可能超过 100。把所有工具描述塞进 system prompt 会：

占用大量 context window
降低 LLM 选择准确性
增加 token 成本

解决方案

所有 MCP 工具 → 元数据索引（名称 + 简短描述）
                    │
                    ▼
LLM 描述需要的能力 → 匹配算法 → 选出 Top-K 工具
                                    │
                                    ▼
                              注入当前上下文

具体实现：

连接时获取所有工具的 name + description（不含完整参数 schema）
维护轻量级索引
当 LLM 表达”我需要搜索文件”时，匹配 grep/find/search_docs 等工具
按需加载完整 schema 到当前 turn 的 system prompt

与 Codex 对比

Codex 的方案：手动配置 enabled_tools / disabled_tools（人工过滤）。

Claude Code 的方案：AI 驱动的按需发现（自动过滤）。

权衡：Claude Code 更智能但可能遗漏；Codex 更确定但需要人工维护。

MCP Server 暴露

启动方式

claude mcp serve

暴露的能力

Claude Code 作为 MCP Server 时，暴露其完整的内置工具集：

文件读写
代码搜索
Bash 执行
Web 搜索
Agent 推理

使用场景

被 Codex 调用：Codex 通过 MCP 连接 Claude Code，获取深度推理能力
多 Agent 编排：作为 Agents SDK 网络中的一个节点
IDE 深度集成：Neovim 通过 WebSocket MCP 连接
自动化流水线：CI/CD 中调用 Claude Code 做代码审查

Plugin Marketplace 与 MCP

Plugin = MCP Server

Claude Code 的 Plugin Marketplace 本质上是一个 MCP Server 注册中心：

开发者发布 MCP Server → Marketplace 审核 → 用户一键安装
                                              │
                                              ▼
                                      自动添加到 .mcp.json

安装流程

claude plugin install @company/mcp-jira
# 等同于在 .mcp.json 中添加对应配置

生态飞轮

更多 MCP Server → 更多 Plugin → 更多用户 → 更多开发者 → ...

安全模型

MCP 工具权限

层级	机制
发现	连接后自动发现（`tools/list`）
首次使用	用户确认（”允许使用 XXX 工具？”）
后续使用	Auto Mode 自动批准（或 allowedTools 白名单）
拒绝	Hook PreToolUse 可拦截

allowedTools 配置

{
  "mcpServers": {
    "database": {
      "command": "...",
      "allowedTools": ["query", "explain"],
      "blockedTools": ["drop", "truncate"]
    }
  }
}

输出大小限制

默认限制 MCP 工具输出大小（防止大量数据淹没上下文）：

全局默认：10KB
可按工具提升："outputLimit": "100KB"

实际应用模式

模式 1：团队标准化工具集

// .mcp.json（git 提交，团队共享）
{
  "mcpServers": {
    "jira": { "command": "mcp-jira", "env": {"TOKEN": "${JIRA_TOKEN}"} },
    "grafana": { "command": "mcp-grafana" },
    "sentry": { "command": "mcp-sentry" },
    "postgres": { "command": "mcp-postgres", "env": {"DSN": "${DB_DSN}"} }
  }
}

新成员 clone 仓库即可获得完整工具集。

模式 2：个人效率工具

// ~/.claude.json（全局，不共享）
{
  "mcpServers": {
    "calendar": { "command": "mcp-google-calendar" },
    "notes": { "command": "mcp-obsidian" },
    "todoist": { "command": "mcp-todoist" }
  }
}

模式 3：跨 Agent 协作

// .mcp.json
{
  "mcpServers": {
    "codex": {
      "command": "codex",
      "args": ["--mcp-server"],
      "env": {"CODEX_SANDBOX": "workspace-write"}
    }
  }
}

Claude Code 将子任务委派给 Codex 在沙箱中执行。

演进路线

时间	MCP 相关里程碑
2024-11	MCP 规范发布
2025-09	Claude Code 集成 MCP Client
2025-11	MCP 规范升级（Streamable HTTP）
2025-12	MCP 捐赠 Linux Foundation
2026-01	Plugin 系统上线（基于 MCP）
2026-03	Elicitation + Tool Search
2026-04	Plugin Marketplace
2026-05	`claude mcp serve`（Server 模式）
2025-11-25	最新规范：Async Tasks + Extensions

交叉引用

MCP 集成对比 — 与 Codex MCP 实现对比
Claude Code 工具循环 — MCP 工具在 7 阶段管线中的位置
Claude Code 工具与权限 — MCP 工具的权限检查
Claude Agent SDK — SDK 中 MCP 的编程接口
Codex 多 Agent 编排 — Codex 作为 MCP Server 节点