第 6 章 · 01 MCP 架构与传输方式

第 6 章 · 01 MCP 架构与传输方式

本节摘要:MCP 是"让 Claude Code 接上外部世界"的标准化插座。先分清它与记忆的分工(实时数据 vs 静态偏好),再看清三层架构(Claude → MCP Server → 外部服务),最后选对传输方式:远程服务用 HTTP,本地进程用 stdio,SSE 已被 HTTP 取代。本节还覆盖 CLAUDE_PROJECT_DIR 注入与 Windows 上的启动特例。

学习目标

阅读完本节,你应当能够:

1. 用"MCP vs 记忆"决策矩阵判断一个数据需求该走哪条路。
2. 画出 MCP 架构三部分并解释每层的职责。
3. 说出三种传输方式各自适用场景,并写出 HTTP/stdio 的添加命令。
4. 解释 CLAUDE_PROJECT_DIR 对 stdio 服务器的意义,以及 Windows 上 npx 命令要加 cmd /c 的原因。

一、MCP 是什么:实时数据通道

MCP(Model Context Protocol)是 Claude Code 访问外部工具、API 与实时数据源的标准化方式。它的关键特性一句话:实时访问——与第 3 章的记忆不同,记忆存放的是"不太变化的数据"(偏好、上下文、历史),而 MCP 连接的是"一直在变的数据"(GitHub 的 issue、数据库的行、Slack 的消息)。

这两者的分工可以用一个决策矩阵记忆:

需要外部数据吗?
├─ 不需要 → 用记忆(存偏好/上下文/历史)
└─ 需要 → 数据变化频繁吗?
   ├─ 不变/很少变 → 用记忆
   └─ 频繁变化 → 用 MCP(实时 API/数据库/服务)
​

例子:用户的编码偏好存在记忆里;今天 GitHub 上开了哪些 PR、数据库里订单表的最新行——这些必须走 MCP,因为它们是实时查询,不是存下来的快照。

二、架构三部分

MCP 的架构只有三个角色:

┌─────────┐   请求(list_issues)    ┌─────────────┐   查询    ┌──────────────┐
│ Claude  │ ────────────────────→ │ MCP Server  │ ────────→ │ External     │
│  (宿主)  │ ←──────────────────── │  (中间层)    │ ←──────── │ Service      │
└─────────┘   响应(数据)          └─────────────┘   结果    └──────────────┘
​

1. Claude(宿主):发起请求、消费结果,只与 MCP Server 对话,不直接接触外部服务。
2. MCP Server(中间层):把外部服务包装成标准化工具。它负责接收请求、调用外部 API、把结果回传。一个服务器可以对接一个服务(如 GitHub MCP 提供 list_prs、create_issue 等一整套工具)。
3. 外部服务(数据源):GitHub、数据库、Slack、Google Docs 等真实世界资源。

这个分层的好处:Claude 不需要知道每个服务的私有 API 怎么调,只要对接 MCP 标准;新增一个服务 = 新增一个 MCP Server,宿主端零改动。

三、传输方式:三种接法

MCP Server 与宿主之间通过"传输"连接,Claude Code 支持三种:

HTTP 传输(推荐)

远程服务的首选,一条命令接入:

# 基本 HTTP 连接
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 带认证头
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"
​

stdio 传输(本地)

本机跑的 MCP Server(比如 npx 拉起的 Node 进程):

# 本地 Node.js 服务器
claude mcp add --transport stdio myserver -- npx @myorg/mcp-server

# 带环境变量
claude mcp add --transport stdio myserver --env KEY=value -- npx server
​

CLAUDE_PROJECT_DIR 注入(v2.1.139+):每个 stdio 服务器启动时,环境里已预设 CLAUDE_PROJECT_DIR=<仓库根目录绝对路径>(与 hooks 同一约定)。插件和项目的 .mcp.json 可以在 command/args/env 里引用 ${CLAUDE_PROJECT_DIR},替换发生在进程启动之前:

{
  "mcpServers": {
    "repo-tools": {
      "type": "stdio",
      "command": "node",
      "args": ["${CLAUDE_PROJECT_DIR}/.claude/mcp/repo-tools.js"],
      "env": {
        "REPO_ROOT": "${CLAUDE_PROJECT_DIR}"
      }
    }
  }
}
​

什么时候用?当你的 stdio 服务器需要相对仓库根目录读文件,而 Claude Code 可能从任意目录启动时。

SSE 传输(已弃用)

Server-Sent Events 已弃用,由 http 取代,但兼容保留:

claude mcp add --transport sse legacy-server https://example.com/sse
​

Windows 特例

原生 Windows(非 WSL)上跑 npx 命令,必须用 cmd /c 包裹:

claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package
​

四、会话工作目录与超时

MCP 服务器可以通过 roots/list 请求发现当前会话的工作目录(启动目录 + 所有 --add-dir/additionalDirectories 条目);目录集合变化时,服务器会收到 notifications/roots/list_changed 通知(v2.1.203+)。同一版本起,空闲超时(30 分钟)也适用于 stdio 服务器,每个服务器可用 timeout 字段设置空闲下限——长时间不用的服务器会被回收,而不是无限挂着。

小结

MCP 是 Claude Code 的"实时数据插座":记忆管静态偏好,MCP 管动态数据。架构上,宿主只管与标准 Server 对话,Server 负责包装外部服务;接线上,远程用 HTTP、本地用 stdio、旧配置用 SSE。stdio 服务器自带 CLAUDE_PROJECT_DIR 锚定仓库根,Windows 用户记得 cmd /c。下一步:把服务器接进来之后,怎么用 CLI 和配置文件管理它们。

下一节预告:第 2 节讲 claude mcp 命令族、三种配置作用域与 JSON 语法——把 MCP 真正装进你的项目。