MCP开发-01.协议标准与心智模型

发表于 | 分类于
以 MCP 2025-11-25 为实践主干，梳理协议层、原语层与业务层心智模型，并介绍 Tasks、Progress 等通用能力与 2026 演进路线。

本系列：00 什么是 MCP · 01 协议与心智模型（本文） · 02 Python 框架选型 · 03 部署与调用 · 04 重任务与优化 · 05 从 0 开发 · 06 进阶示例 · 07 阿里云案例

1. 为什么要单独建立「心智模型」

开发 MCP Server 时，常见两类问题混在一处排查：协议没握手 vs 业务逻辑报错。把问题拆成三层，排错路径会清晰很多：

层次 你关心什么 典型故障
协议层 传输、握手、JSON-RPC 消息 Host 未连接、404 session、Origin 403
原语层 Tools / Resources / Prompts 如何暴露与调用 工具列表为空、模型选错原语
业务层 Python 函数、数据库、外部 API 参数错误、超时、权限不足

段末注释：Model Context Protocol（模型上下文协议，MCP）是 AI 应用与外部工具/数据之间的开放连接标准；JSON-RPC（JavaScript Object Notation Remote Procedure Call）为 MCP 消息编码格式。

2. 三层心智模型

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
flowchart TB
  subgraph layer1 [协议层]
    JSONRPC["JSON-RPC 2.0 消息"]
    Transport["传输: stdio / Streamable HTTP"]
    Lifecycle["initialize → 能力协商 → 调用"]
  end
  subgraph layer2 [原语层]
    Tools["Tools: 可执行动作"]
    Resources["Resources: 可读上下文 URI"]
    Prompts["Prompts: 可复用模板"]
  end
  subgraph layer3 [业务层]
    Logic["Python 函数与外部系统"]
  end
  layer1 --> layer2 --> layer3

记忆口诀：传输管「怎么连」，原语管「暴露什么」，业务管「具体干什么」。下文默认协议版本为 2025-11-25（当前稳定实践主干）。

3. 协议层：版本、生命周期与传输

3.1 协议版本

MCP 使用日期字符串标识版本（如 2025-11-25）。客户端与服务器在 initialize 阶段协商版本与能力；Streamable HTTP 下，后续请求应携带 MCP-Protocol-Version 头。

版本 地位 要点
2024-11-05 历史 含已弃用的 HTTP+SSE 传输
2025-03-26 过渡 引入 Streamable HTTP
2025-11-25 当前实践主干 Tasks、结构化输出、传输安全强化等
2026-07-28 RC / 演进中 无会话、无 initialize 握手等（见 §7）

3.2 典型生命周期（2025-11-25）

1
2
3
4
5
6
7
8
9
10
11
12
13
sequenceDiagram
    participant Host as MCP_Host
    participant Client as MCP_Client
    participant Server as MCP_Server

    Host->>Client: 配置 Server 连接
    Client->>Server: initialize（协商版本与能力）
    Server->>Client: InitializeResult
    Client->>Server: initialized 通知
    Client->>Server: tools/list 等发现请求
    Server->>Client: 工具/资源/提示列表
    Client->>Server: tools/call 等执行请求
    Server->>Client: 结果或 Task 句柄
  1. 连接建立：stdio 由 Host 拉起子进程；HTTP 由 Client POST 到 MCP 端点。
  2. 初始化：交换协议版本、各自 capabilities（支持 Tools / Tasks / Sampling 等）。
  3. 发现：tools/list、resources/list、prompts/list 等。
  4. 执行：tools/call、resources/read、prompts/get 等。
  5. 结束：stdio 关闭管道；HTTP 可 DELETE 会话（若使用有会话模式）。

3.3 标准传输（仅两种）

传输 连接方式 适用
stdio Host 启动子进程，经 stdin/stdout 交换 JSON-RPC（换行分隔） 本地 IDE、桌面端、开发调试
Streamable HTTP 独立 HTTP 进程，POST/GET 到单一 MCP 端点，可 SSE 流式 远程部署、多客户端、生产环境

重要：协议版本 2025-03-26 起，远程部署应使用 Streamable HTTP；旧版 HTTP+SSE（2024-11-05）已弃用，仅作向后兼容。日志应写 stderr（stdio）或结构化 logging（HTTP），禁止向 stdout 输出非 MCP 消息。

部署与 Host 配置细节见：MCP开发-03.部署方式与调用配置。

段末注释：Server-Sent Events（服务器发送事件，SSE）是一种 HTTP 单向推送机制；Streamable HTTP 可在需要时用 SSE 承载多条服务器消息。

4. 原语层：Server 暴露什么

MCP Server 通过三类原语向模型提供能力，语义不同，选型也不同：

原语 类比 典型用途 客户端操作
Tools POST / 函数调用 执行动作、改状态、跑计算 tools/call
Resources GET / 只读文档 提供上下文、配置、结果摘要 resources/read
Prompts 模板 / 宏 可复用、参数化的交互模板 prompts/get 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
flowchart LR
  subgraph discover [发现阶段]
    TL[tools/list]
    RL[resources/list]
    PL[prompts/list]
  end
  subgraph invoke [调用阶段]
    TC[tools/call]
    RR[resources/read]
    PG[prompts/get]
  end
  TL --> TC
  RL --> RR
  PL --> PG

实践建议：

  • 会改变外部状态或有副作用 → Tool，并在描述中写清。
  • 大段只读上下文（文档、schema、上次结果摘要）→ Resource，避免塞进 Tool 返回文本。
  • 固定工作流模板（如「按此格式审查代码」）→ Prompt。

进阶代码示例见：MCP开发-06.进阶示例-Resources与Tasks。

5. 能力协商：Server 与 Client 各能做什么

5.1 服务端常见能力

能力 说明
tools 暴露可调用工具
resources 暴露 URI 可读资源
prompts 暴露提示模板
logging 向 Client 发送日志消息
completions 资源/提示的补全建议

5.2 客户端常见能力（Server 可反向请求）

能力 说明
sampling Server 请求 Host 内的 LLM 生成（如子 Agent）
roots 告知 Server 可访问的文件/目录根
elicitation Server 向用户请求补充参数（表单式交互）

开发 Server 时，应假设 Client 能力因 Host 而异：Desktop IDE 可能支持 elicitation，纯 HTTP 网关可能不支持 sampling。

6. 通用工具：Progress、Cancellation、Tasks

除三类原语外，规范还提供跨请求工具，对长任务与可观测性尤其重要。

6.1 Progress（进度通知）

Tool 执行过程中，Server 可通过 notifications/progress 上报进度（百分比、状态文案）。Client 在请求中提供 progressToken 时，Token 在任务全生命周期有效。

Python SDK 中常见写法（概念示例）：

1
2
3
4
5
6
7
8
9
from mcp.server.fastmcp import Context, FastMCP

mcp = FastMCP("demo")

@mcp.tool()
async def long_step(n: int, ctx: Context) -> str:
    for i in range(n):
        await ctx.report_progress(i + 1, n, f"step {i + 1}/{n}")
    return "done"

6.2 Cancellation（取消）

Client 可发送 notifications/cancelled，Server 应协作式停止工作（杀子进程、撤销队列任务等）。取消语义是尽力而为，不保证立即中断。

6.3 Tasks（SEP-1686：call-now, fetch-later）

Tasks 解决同步 tools/call 阻塞导致的超时问题：Server 立即返回 taskId 与 working 状态，Client 通过 tasks/get 轮询、tasks/result 取结果、tasks/cancel 请求取消。

1
2
3
4
5
6
7
8
9
10
stateDiagram-v2
    [*] --> working
    working --> input_required: 需要用户输入
    input_required --> working: 收到输入
    working --> completed: 成功
    working --> failed: 错误
    working --> cancelled: 取消
    completed --> [*]
    failed --> [*]
    cancelled --> [*]
方法 用途
tasks/get 查询状态；完成时可能内联 result
tasks/result 阻塞直到终态并返回结果
tasks/list 列出任务（可按状态过滤）
tasks/cancel 请求取消（终态任务会拒绝）

重任务架构与实现模式见：MCP开发-04.重服务与长任务开发。

段末注释：SEP（Specification Enhancement Proposal，规范增强提案）是 MCP 协议变更的正式提案流程；SEP-1686 定义了 Tasks 原语。

7. 安全基线（Streamable HTTP）

远程 Server 至少应满足：

  1. Origin 校验：非法 Origin 返回 403，防 DNS rebinding。
  2. 本地绑定：开发环境优先 127.0.0.1，避免 0.0.0.0 无意暴露。
  3. TLS：生产环境 HTTPS。
  4. 认证：OAuth 2.1 等扩展（视场景）；勿在 Tool 参数中硬编码密钥。
  5. 最小权限：Tools 只暴露必要操作；敏感读走 Resource + 授权。

8. 2026 演进路线（预览，非默认实践）

以下基于 2026-07-28 规范 RC 与 SEP-2567，正式版预计 2026-07-28 发布，实施时以最终 spec 为准。

变更 影响
移除协议级 Session 不再依赖 MCP-Session-Id；请求可独立路由，利于负载均衡
移除 initialize 握手 版本与能力随请求携带；Client 可缓存 tools/list（带 ttlMs）
Mcp-Method / Mcp-Name 头 网关可按操作路由，无需解析 body
显式 state handles 有状态 Tool 由 Server 签发 handle，模型在后续调用中传参

迁移提示（现在可做）：

  • 新部署优先 stateless_http=True（Python SDK），与未来无会话模型对齐。
  • 若使用多实例 + 粘性 Session，应规划升级窗口；2026 版将简化网关与扩缩容。
  • 教程代码仍以 2025-11-25 + initialize 为准，升级时对照官方 changelog。

9. 与后续篇章的衔接

你想… 阅读
选 Python 框架 02 Python 框架选型
决定 stdio 还是 HTTP、怎么配 Host 03 部署与调用
跑大计算、长任务 04 重服务与长任务
写第一个 Tool 05 从 0 开发
Tools + Resources + Tasks 完整示例 06 进阶示例
生产案例（阿里云 Argo + OSS/NAS） 07 阿里云案例

官方规范：modelcontextprotocol.io · Python SDK

-------------本文结束感谢您的阅读-------------