MCP 从入门到进阶

1. MCP 是什么

Model Context Protocol（模型上下文协议，简称 MCP） 是一个开放标准（协议），用于把 AI 应用（如 Claude、ChatGPT、VS Code 等）连接到外部系统——数据源、工具、工作流。

官方有一个很形象的比喻：MCP 就像 AI 应用的「USB-C 接口」。

就像 USB-C 让你用一个统一的接口连接各种外设（充电器、显示器、硬盘），MCP 让你用一个统一的标准接口连接各种外部系统（数据库、API、文件系统、Git 仓库……），而不用为每一个数据源或工具写一套单独的集成。

关键事实

一句话理解

• 没有 MCP 之前：每个 AI 应用要连 N 个工具，每个工具要适配 M 个 AI 应用，结果是 M × N 套重复的定制集成。
• 有了 MCP 之后：工具方只需要实现一次 MCP 服务器，任何支持 MCP 的 AI 应用都能直接连接，变成 M + N。

2. 为什么需要 MCP

以「让 AI 助手读取本地文件」为例：

传统做法：为每个 AI 应用单独写插件/连接器，Claude 一套、ChatGPT 一套、某个 IDE 又一套，逻辑重复、维护成本高。

MCP 做法：写一个「文件系统 MCP 服务器」，通过标准协议暴露 read_file、list_directory 等工具。所有支持 MCP 的客户端都能复用同一个服务器。

MCP 解决的核心问题是：

1. 统一接口——一套协议连接所有外部能力。
2. 可复用——一个服务器服务多个客户端。
3. 可组合——一个 AI 应用可以同时连接多个 MCP 服务器。
4. 标准化安全——内置了认证、授权、作用域等机制。

3. 核心架构：Host / Client / Server

MCP 有三个核心参与者：

关系可以理解为：

Host（AI 应用）
  ├── Client A ──── 1:1 ──── Server A（例如文件系统）
  ├── Client B ──── 1:1 ──── Server B（例如数据库）
  └── Client C ──── 1:1 ──── Server C（例如远程 API）
 

• 本地服务器：通过 stdio 作为子进程运行。
• 远程服务器：作为独立进程在网络上运行，通过 HTTP(S) 暴露（Streamable HTTP）。

4. 三大服务器原语：Resources / Tools / Prompts

服务器向模型提供三种核心「能力」。

4.1 Resources（资源）

只读的、可用 URI 寻址的上下文/数据，例如文件内容、数据库记录、API 响应。

• 带有 MIME 类型。
• 支持模板 URI（例如 file:///logs/{date}）。
• 对应方法：resources/list、resources/read。

类比：Resources 是「可以读的东西」，AI 用来获取信息，但不会改变它。

4.2 Tools（工具）

模型可以调用的可执行函数，用来执行动作。

• 由模型控制（模型决定何时调用）。
• 输入输出有类型（JSON Schema）。
• 对应方法：tools/list、tools/call。

类比：Tools 是「可以做的事情」，比如查询天气、发邮件、写入数据库。

4.3 Prompts（提示词）

可复用的、由用户调用的指令/模板工作流。

• 由用户控制（用户选择使用）。
• 对应方法：prompts/list、prompts/get。

类比：Prompts 是「预设好的指令模板」，比如「帮我写一份周报」「按此格式总结这份代码」。

快速对比

5. 客户端原语与已废弃的能力

5.1 Elicitation（信息征求）——当前推荐

服务器请求用户提供额外输入或确认的机制，是「服务器发起请求」的现代替代方案。

• 表单模式（form）：用结构化 schema 让客户端渲染表单收集输入。
• URL 模式：跳转到外部链接（例如 OAuth 授权、填写凭证）。

它是 Sampling / Roots 等旧机制的替代者——新的服务器若需要「反过来问用户」，应该用 Elicitation。

5.2 已废弃的能力（2026-07-28 起）

⚠️ 如果你在旧教程里看到 Sampling / Roots / Logging，请注意：新的开发不应该再基于它们构建功能。

5.3 其他概念

• Structured output（结构化输出）：工具可以声明 outputSchema，除纯文本 content 外还能返回 structuredContent。
• Pagination（分页）：*/list 方法支持基于游标（cursor）的分页，用于工具/资源/提示词很多时。
• Parameter completion（参数补全）：给资源/提示词参数提供候选值（原 completion/complete 被重构为「参数补全」）。

6. 传输方式：stdio 与 Streamable HTTP

传输方式决定客户端和服务器之间如何「对话」。

6.1 stdio（本地子进程）

• 客户端把服务器作为子进程启动。
• 消息是 换行分隔的 JSON-RPC，走 stdin/stdout。
• stderr 用于日志。
• 特点：本地、简单、无网络开销、一个进程一个客户端。

绝大多数本地 MCP 服务器都用 stdio。

6.2 Streamable HTTP（远程，当前推荐）

• 服务器暴露一个 HTTP 端点，接受 POST。
• 每条客户端消息是一次独立的 POST。
• 服务器回复：单个 JSON 对象，或一个请求作用域的 SSE 流。
• 长期变更通知通过 subscriptions/listen 流。
• 支持标准 HTTP 认证（Bearer token、API key、自定义头；推荐 OAuth）。
• 要求校验 Origin，并镜像 MCP-Protocol-Version、Mcp-Method、Mcp-Name 头。

这是远程/部署服务器的推荐传输方式。

6.3 HTTP+SSE（已废弃）

• 2024-11-05 起的旧传输方式（单独 SSE 端点 + endpoint 事件）。
• 已废弃，仅保留向后兼容。

对比

传输场景特点stdio本地子进程、简单、无网络Streamable HTTP远程单端点、多客户端、可联网HTTP+SSE旧版已废弃，仅兼容

7. 快速上手：写第一个 MCP 服务器

下面分别用 Python（SDK v2） 和 TypeScript（SDK v2） 写一个最小服务器。

7.1 Python 版

先安装（需要 Python 3.10+）：

pip install "mcp[cli]"
# 或使用 uv
uv add "mcp[cli]"
 

一个「加法工具 + 问候资源」的最小服务器：

from mcp.server import MCPServer
 
mcp = MCPServer("Demo")
 
@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers."""
    return a + b
 
@mcp.resource("greeting://{name}")
def greeting(name: str) -> str:
    """Greet someone by name."""
    return f"Hello, {name}!"
 

本地开发/运行：

# 开发模式
uv run mcp dev server.py
 
# 以 Streamable HTTP 方式运行
uv run mcp run server.py --transport streamable-http
 

7.2 TypeScript 版

安装（SDK v2 拆分为 server / client 包）：

npm install @modelcontextprotocol/server @modelcontextprotocol/client
# 以及 schema 校验库（示例用 zod v4）
npm install zod
 

一个「greet 工具」的最小服务器（stdio）：

import { McpServer } from '@modelcontextprotocol/server';
import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
import * as z from 'zod/v4';
 
const server = new McpServer({ name: 'greeting-server', version: '1.0.0' });
 
server.registerTool(
  'greet',
  {
    description: 'Greet someone by name',
    inputSchema: z.object({ name: z.string() }),
  },
  async ({ name }) => ({
    content: [{ type: 'text', text: `Hello, ${name}!` }],
  })
);
 
async function main() {
  await server.connect(new StdioServerTransport());
}
main();
 

说明：上面的 API 是 SDK v2 的写法（MCPServer、registerTool、StdioServerTransport）。旧教程里常见的 Server / setRequestHandler / StdioServerTransport 来自 v1（@modelcontextprotocol/sdk）。

8. 在客户端注册服务器

写好了服务器，需要在客户端（Host）里「注册」它，客户端才会启动并连接。

8.1 Claude Desktop

配置文件 claude_desktop_config.json：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": ["--directory", "/ABSOLUTE/PATH/TO/weather", "run", "weather.py"]
    }
  }
}
 

• Node 服务器："command": "node"，"args": ["/abs/path/build/index.js"]。
• HTTP 服务器：用 "url": "https://..." 替代 command（可配 bearerTokenEnvVar 引用环境变量）。

8.2 通用 mcp.json

很多工具（Claude Code、VS Code 等）用同一个 mcpServers 结构，写在项目级 .mcp.json 里。Python SDK 的 mcp install 命令也能自动写入。

一个 HTTP 服务器（使用环境变量里的静态 Bearer Token）：

{
  "mcpServers": {
    "my-remote": {
      "url": "https://mcp.example.com/mcp",
      "bearerTokenEnvVar": "MY_MCP_TOKEN"
    }
  }
}
 

注意：stdio 条目会在会话启动时启动子进程，因此项目级配置应只放在可信的仓库里。

9. 认证与授权（OAuth 2.1 / Bearer Token）

重要：授权是可选的。只有服务器真正需要鉴权时才实现。

9.1 基本规则

• HTTP 传输：按 MCP 授权规范走 OAuth 2.1。
• stdio 传输：不要套用 OAuth 规范，改为从环境变量读取凭证。

9.2 角色对应

MCP 角色OAuth 角色MCP 服务器资源服务器（Resource Server）MCP 客户端客户端（Client）（独立的）授权服务授权服务器（Authorization Server）

9.3 基于的标准

MCP 授权基于 OAuth 2.1 的一个子集，并引用多个 RFC：

• OAuth 2.1（draft-ietf-oauth-v2-1）——核心框架
• RFC 6750——Bearer Token
• RFC 8414——授权服务器元数据
• RFC 8707——资源指示符（resource 参数）
• RFC 9728——受保护资源元数据
• RFC 9207——签发者标识
• RFC 7591——动态客户端注册（已被 Client ID Metadata Documents 取代）
• OIDC——发现与注册

9.4 双方要实现什么

服务器（资源服务器）必须：

• 提供受保护资源元数据（RFC 9728）
• 校验 token 的受众（audience，按 RFC 8707）
• 正确处理 401 / 403 / 400
• 在 WWW-Authenticate 挑战中给出 scope 指引

客户端必须：

• 发现资源/授权服务器元数据
• 使用 PKCE
• 在授权与 token 请求中带 resource 参数
• 校验签发者（RFC 9207）
• 每次请求用 Authorization: Bearer ... 头（绝不能放在 URL 查询串里）
• 处理 insufficient_scope 时的 step-up / scope 合并

9.5 安全要点

• PKCE 对公共客户端是必须的。
• Refresh token 可选，不要默认假设存在。
• 永远不要把 token 写在 URL 里。
• 不要把密钥明文写进 mcp.json——HTTP 服务器用 bearerTokenEnvVar 引用环境变量；stdio 若必须在 env 里内联密钥，务必先评估风险。

10. 进阶主题

10.1 当前版本（2026-07-28）的重大变化

这一版是一次大型重构，如果你读过旧资料，重点注意这些变化：

• 无状态/无会话（stateless/sessionless）协议。
• 按请求元数据（_meta + HTTP 头）取代 initialize 握手。
• server/discover 取代 initialize。
• Multi Round-Trip Requests（MRTR）：服务器→客户端的多轮交互。
• 弃用 Sampling、Roots、Logging（见第 5 节）。
• 新可选扩展：Tasks、MCP Apps、Skills over MCP。
• 默认 JSON Schema 方言升级为 2020-12。

10.2 结构化输出（Structured Output）

工具除了返回文本，还可以返回结构化结果，方便程序处理：

from pydantic import BaseModel
 
class WeatherResult(BaseModel):
    temperature: float
    condition: str
 
@mcp.tool()
def get_weather(city: str) -> WeatherResult:
    """Get current weather for a city."""
    return WeatherResult(temperature=22.5, condition="sunny")
 

客户端可以通过 result.structured_content 拿到结构化对象。

10.3 分页

当工具/资源/提示词很多时，*/list 支持游标分页：

• 请求带 cursor 参数。
• 响应返回 nextCursor。

10.4 远程 MCP 与托管服务器

• 本地服务器：stdio 子进程。
• 远程/托管服务器：独立进程，通过网络用 Streamable HTTP 暴露（常由公司/平台托管，如 Sentry）。

10.5 MCP Registry（官方注册中心）

存在官方集中式元数据仓库：https://registry.modelcontextprotocol.io。

• 由 Anthropic、GitHub、PulseMCP、Microsoft 支持。
• 提供 REST API + OpenAPI 规范，供宿主应用/聚合器/市场使用。
• 命名用反向 DNS（如 io.github.user/server）。
• 支持开源与闭源服务器；不支持私有服务器（私有可自建 registry）。

11. 官方 SDK 与生态

11.1 官方 SDK 分级

• Tier 1：TypeScript、Python、C#、Go、Rust
• Tier 2：Java、Ruby
• Tier 3：Kotlin、Swift、PHP

11.2 版本速查（截至 2026-08 检索）

11.3 生态亮点

• 主要客户端/宿主：Claude（Desktop、Code、Claude.ai）、ChatGPT/OpenAI、VS Code、Cursor 等。
• 官方参考服务器：Filesystem、Git、Memory、Fetch、Sequential Thinking、Time、Everything。
• 官方集成：GitHub、Slack、Google Drive、Postgres、Sentry 等（位于 modelcontextprotocol/servers 仓库）。

12. 安全要点与常见坑

12.1 写给初学者的「别踩的坑」

1. stdio 服务器里不要用 print() / console.log() 输出到 stdout。 —— 这会污染 JSON-RPC 流。日志请写到 stderr（或文件）。
2. 工具 = 任意代码执行。 —— 不要把工具描述/注解当作可信输入；宿主在调用工具前应取得用户明确同意。
3. Streamable HTTP 必须校验 Origin 头，防止 DNS rebinding。 —— 本地服务器请绑定 127.0.0.1，不要绑 0.0.0.0。
4. Token 永远不放 URL 查询串，用 Authorization: Bearer 头；校验 token 的 audience；公共客户端用 PKCE。
5. Roots 只是建议，不是安全边界。 —— 真正的限制要靠操作系统权限/沙箱。
6. Sampling / Roots / Logging 已废弃，不要在新的功能上依赖它们。
7. stdio 服务器不要套 OAuth 规范，凭证从环境变量读。
8. 版本协商现在是按请求的（_meta.protocolVersion / MCP-Protocol-Version 头），initialize 已是旧机制；新服务器请基于 server/discover 构建。
9. 服务器描述、资源内容、提示词内容都应视为不可信输入。

13. 版本历史与治理

13.1 版本号怎么读

MCP 用日期字符串作为版本号（YYYY-MM-DD），表示「最后一次向后不兼容变更」的日期。

13.2 主要版本里程碑

13.3 治理

• 归属 Linux Foundation（LF Projects, LLC）。
• 开放治理：Contributors → Maintainers → Core Maintainers → Lead Maintainers/BDFL。
• 通过 SEP（Specification Enhancement Proposal） 流程演进。
• 当前 Lead Maintainers：David Soria Parra、Den Delimarsky；荣誉退休：Justin Spahr-Summers。

14. 学习资源

• 官网：https://modelcontextprotocol.io/
• 规范仓库（原 modelcontextprotocol/specification 已重定向）：https://github.com/modelcontextprotocol/modelcontextprotocol
• TypeScript SDK：https://github.com/modelcontextprotocol/typescript-sdk
• Python SDK：https://github.com/modelcontextprotocol/python-sdk
• 官方示例服务器：https://modelcontextprotocol.io/examples
• 官方集成仓库：https://github.com/modelcontextprotocol/servers
• 注册中心：https://registry.modelcontextprotocol.io/
• 创始介绍（Anthropic）：https://www.anthropic.com/news/model-context-protocol

本文基于 2026-08 检索到的官方文档与规范整理，关键版本与 API 请以官方最新页面为准。版本演进较快，动手实践前建议再次核对官网对应版本的 SDK 文档。