> For the complete documentation index, see [llms.txt](https://yeasy.gitbook.io/claude_guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://yeasy.gitbook.io/claude_guide/di-er-bu-fen-gong-ju-pian/04_mcp/4.2_architecture.md).

# 4.2 MCP 架构与核心概念

MCP 并不仅仅是一个简单的 API 定义，它是一套面向工具、资源与提示模板的应用层协议。要熟练使用 MCP，需要理解其架构组件、能力边界与通信机制。

## 4.2.1 系统架构图谱

MCP 采用经典的 **Client-Server (C/S)** 架构，但在 AI 场景里，角色定义略有特殊。

```mermaid
graph LR
    classDef core fill:#E65100,stroke:#333,stroke-width:3px,color:white,font-weight:bold;
    classDef branch fill:#FFECB3,stroke:#FF6F00,stroke-width:2px,color:#333;
    classDef node fill:#FFF8E1,stroke:#FFB300,stroke-width:1px,color:#333;

    subgraph HostApp["宿主应用 (Host)"]
        AI(("Claude")):::core <--> ClientLogic["MCP Client"]:::branch
    end

    subgraph LocalEnv["本地环境"]
        ClientLogic <-->|"stdio"| S1["Filesystem"]:::node
        ClientLogic <-->|"stdio"| S2["SQLite"]:::node
    end

    subgraph RemoteEnv["远程环境"]
        ClientLogic <-->|"Streamable HTTP"| S3["Slack Gateway"]:::node
    end
```

### MCP Host 与 MCP Client

**Host 是宿主应用**，即 Claude Desktop、IDE、终端代理等 AI 应用本身；它为每个 Server 实例化一个 **MCP Client**。Client 是协议层的发起方，与 Server 保持一对一连接。

* **职责**：Host 协调多个 Client、把用户意图转成 MCP 请求、并将 Server 的结果呈现给用户或喂给模型；每个 Client 负责管理与对应 Server 的连接。
* *注意：LLM 本身既不是 Host 也不是 Client；包裹 LLM 的宿主应用是 Host，Client 是 Host 内部与 Server 通信的组件。*

### MCP Server

**Server 是能力提供方**。它通常是一个独立进程或独立服务。

* **职责**：暴露资源（数据）、工具（功能）和提示词（模板）。
* **特性**：一般专注于单一领域，如 Git、PostgreSQL、文件系统或企业内部系统。

## 4.2.2 三大核心原语

MCP 协议定义了三种主要能力。

### 资源 —— “读取 Context”

资源是被动的数据源，模型通过 `read` 操作获取其内容。

* **类比**：`GET` 请求或文件读取。
* **URI 寻址**：每个资源都有唯一 URI，例如 `file:///home/user/notes.txt` 或 `postgres://db/users/schema`。
* **用途**：让 Claude 读取大文件、数据库 schema 或运行日志，而不必把全部内容塞进 prompt。
* **注意**：资源内容获取后直接进入上下文窗口，应注意资源大小的管理以避免 Token 溢出。

### 工具 —— “执行 Action”

工具是可执行的函数。

* **类比**：`POST` 请求或函数调用。
* **结构**：通常包含 `name`、`description`、`inputSchema` 等元数据。
* **用途**：创建文件、执行查询、发送消息、触发工作流。
* **流程**：Client 发起 `tools/call`，Server 执行逻辑并返回结果内容。

### 提示词 —— “预设模板”

这是 MCP 相对有特色的一类能力，允许 Server 暴露可复用的提示模板。

* **类比**：Slash Command（斜杠命令）或参数化 Prompt 模板。
* **用途**：把某个领域里的标准分析过程沉淀为可复用入口。
* **例子**：Git Server 可以提供一个 “分析当前 diff” 的提示模板，宿主应用把上下文采集和模板拼装标准化后，再交给模型执行。

### 大规模工具库的按需加载

面对大规模工具库时，要区分 **MCP 协议标准能力** 和 **宿主/编排层优化**。MCP 标准层定义的是 `tools/list`、`tools/call` 和 `Tool[]` 等基本交互；部分宿主或 agent harness 可能会在其上增加工具搜索、延迟加载或压缩提示的机制。

一种常见优化是：

1. 先让模型看到精简的工具索引或工具分类。
2. 当任务需要某类工具时，再加载完整 schema、描述和使用示例。
3. 通过宿主提供的 Tool Search、RAG 或工具目录服务找到候选工具。

这种设计可以减少初始 prompt 的 token 占用。如果一个 MCP Server 暴露了 50 个工具，但当前任务只需要其中 2 个，预加载全部 Schema 会浪费大量上下文空间。写 MCP 文档或实现时，应把这类优化描述为宿主层能力，不要把 `deferred_tools_delta`、`ToolSearch` 等特定实现名写成 MCP 核心协议的一部分。Anthropic API 层面的工具搜索与按需加载实现，详见 [3.6 工具搜索](/claude_guide/di-er-bu-fen-gong-ju-pian/03_tools/3.6_tool_search.md)。

## 4.2.3 通信与传输层

MCP 在消息层统一使用 **JSON-RPC 2.0**（规范强制要求，所有 Client-Server 消息都必须遵循该格式）。在传输层，MCP 规范定义了 `stdio` 和 `Streamable HTTP` 两种标准传输方式，同时不同的客户端实现可能支持额外的传输选项。

### `stdio`：本地进程通信

* **最常用**：Client 作为父进程启动 Server 子进程。
* **通信**：通过 `stdin` / `stdout` 交换 JSON-RPC 消息。
* **优点**：部署简单、不暴露网络端口、适合本地工具。
* **场景**：文件系统、本地数据库、本机开发工具。

### `Streamable HTTP`：远程服务主流方案

* **当前远程连接的推荐方案**。
* **通信**：基于 HTTP 传输 JSON-RPC 消息，支持流式返回、会话恢复 token 和重试逻辑。
* **优点**：适合容器部署、内网服务、云端网关，支持断线重连。
* **场景**：团队共享服务、企业内部系统、需要远程认证的工具网关。

### `SSE`：历史双向实现

* **早期远程方案**：下行使用 Server-Sent Events，上行使用独立的 HTTP POST。
* **定位**：在当前生态中属于历史兼容实现，新项目应优先使用 Streamable HTTP。
* **仍可用**：部分已有 Server 仍采用此方案，Client 通常向后兼容。

### `WebSocket`：低延迟选项

* **注意**：Claude Code 可以通过 `.mcp.json` / `claude mcp add-json` 配置 WebSocket MCP Server；但普通请求/响应和需要 OAuth 的远程工具应优先使用 Streamable HTTP。
* **直连模式**：直接 JSON 消息传递，延迟最低。
* **场景**：实时协作、需要双向高频通信的工具。
* **兼容性**：使用前需确认 Server 端是否支持此协议。

> **提示**：选择传输方式时，优先使用 MCP 标准定义的 `stdio`（本地）或 `Streamable HTTP`（远程），以确保最大兼容性。需要兼容旧远程 Server 时可保留 SSE；WebSocket 只能作为双方显式支持的自定义传输处理。

下面是 Claude Code / Claude Desktop 风格的宿主配置示例；不同宿主的字段名可能不同。

```json
{
  "mcpServers": {
    "company-tools": {
      "type": "streamable-http",
      "url": "https://mcp-server.company.com/mcp"
    }
  }
}
```

## 4.2.4 MCP 认证与交互

随着 MCP 被用于企业系统和远程服务，认证与用户确认变得至关重要。

### OAuth 2.1

对于远程 MCP Server，常见做法是由宿主应用或网关接入 **OAuth 2.1** 流程。

**工程上要把握两个原则：**

* 认证配置的具体字段由所用宿主、SDK 或 Server 实现决定，并不意味着 MCP 核心协议强制规定了某一套环境变量名。
* 写文档时应重点解释“为什么需要 OAuth、典型会话长什么样”，避免把某个私有实现的配置项写成协议标准。

### Elicitation / 用户确认

在需要额外输入或确认的场景中，远程端与宿主端可能发生交互式确认，例如：

* 请求额外权限；
* 询问是否继续敏感操作；
* 补充缺失参数。

这类能力说明 MCP 并不总是单向“调用工具 -> 返回结果”，而是可以承载更复杂的人机协作流程。

## 4.2.5 初始化握手

> **版本说明**：本节描述的是握手式修订版（MCP `2025-11-25` 及更早）的流程，也是当前多数客户端与 Server 实际运行的方式。官方 `2026-07-28` 修订版移除了 `initialize` / `notifications/initialized` 握手与协议级会话，改为每个请求在 `_meta` 中携带协议版本与客户端能力，并新增 `server/discover` 供客户端一次性获取版本与能力。实现方通常会同时支持多个修订版，接入前请按目标 Server 支持的版本核对。

当支持 MCP 的宿主应用启动并连接某个 Server 时，通常会发生以下过程：

1. **启动或连接**：启动本地 `mcp-server` 进程，或连接远程服务。
2. **Initialize**：Client 发送 `initialize` 请求，声明自己的协议版本与能力。
3. **Negotiate**：Server 返回自身信息和支持的能力。
4. **Initialized**：Client 发送 `notifications/initialized`，表示初始化阶段完成。
5. **List**：Client 视需要请求 `tools/list`、`resources/list`、`prompts/list` 构建能力目录。
6. **Auth / Consent**：若远程服务需要认证或用户确认，会在此阶段或首次调用时完成。

这一过程对用户通常是透明的。用户看到的只是 Claude “学会”了访问数据库、文件系统或企业服务。

## 4.2.6 配置层级与企业管控

> **来源说明**：本节的作用域优先级与企业管控行为以 [官方 MCP 文档](https://code.claude.com/docs/en/mcp#scope-hierarchy-and-precedence) 和 [官方 Managed MCP 文档](https://code.claude.com/docs/en/managed-mcp) 为准；个别官方未载的实现细节（如每轮重新获取 MCP 指令、Resource 内容直接进入上下文）仍来自社区逆向分析（HitCC 项目）。其他 MCP 客户端的配置机制可能不同。

MCP 在 Claude Code 中的配置解析遵循官方文档定义的作用域优先级——同名 Server 取最高优先级来源，从高到低依次为：

| 优先级 | 配置来源              | 说明                                       |
| --- | ----------------- | ---------------------------------------- |
| 1   | 本地作用域（local）      | 当前用户在当前项目内私有的配置（含 `claude mcp add` 默认写入） |
| 2   | 项目作用域 `.mcp.json` | 随仓库共享的项目配置                               |
| 3   | 用户作用域             | `~/.claude/` 下跨项目的个人配置                   |

上述合并**按名称**匹配重复项；按**端点**（URL 或启动命令）匹配的去重只适用于插件与连接器——当插件/连接器指向的 URL 或命令与上层某个 Server 相同时，会被视为重复。

企业 `managed-mcp.json` 不参与上述合并——它具有**排他控制权**：一旦部署，Claude Code 只加载该文件定义的 Server，用户无法添加、修改或使用任何其他 MCP Server。

### 企业管控约束

在企业环境中，MCP 配置不是简单的合并——**企业级配置会施加策略约束**：

* 企业 `managed-mcp.json` 存在时，仅其定义的 Server 可用（排他）
* 用户**无法**通过命令行动态添加新的 MCP Server
* 企业管理员可以锁定允许使用的 Server 列表

这意味着 MCP 在企业部署中是一个**策略管控系统**，而非简单的配置文件合并。管理员可以确保所有用户只连接到经过审批的工具服务。

### MCP 指令的动态性

MCP Server 可能在运行中动态更新其工具、资源或提示列表。客户端可根据 `list_changed` 通知或重连刷新能力目录；是否每轮对话都刷新取决于宿主实现，不是 MCP 核心协议的硬性要求。

### Resource 的使用方式

MCP Resource 的内容在被获取后，会直接出现在对话上下文中（而非保持为引用）。这意味着大型资源会直接占用上下文窗口空间，使用时需要注意资源大小的管理。

***

理论知识已经具备，现在动手实战。我们将配置 Claude Desktop 来连接一个本地的 SQLite 数据库。

➡️ [配置与实战指南](/claude_guide/di-er-bu-fen-gong-ju-pian/04_mcp/4.3_config.md)