AI Agent / 知识点
MCP 开发速查手册
手册条目
快速判断 MCP Host、Client 和 Server 在一次连接中的职责边界。
区分 MCP Host、Client 与 Server
判断职责时先看“谁面向用户、谁维护协议连接、谁提供能力”。Host 负责整体体验与安全控制;Client 是 Host 内部连接某个 Server 的协议组件;Server 只暴露工具、资源、提示词等能力,不负责决定模型如何使用它们。
职责边界
| 角色 | 主要职责 | 不应承担 |
|---|---|---|
| Host | 管理用户会话、模型、权限、同意流程与多个 Client;汇总各 Server 的能力 | 不把未授权数据自动发送给 Server |
| Client | 对接一个 Server,处理传输、JSON-RPC、版本与能力发现、请求路由和错误返回 | 不独立决定业务权限或替用户批准高风险操作 |
| Server | 提供 Tools、Resources、Prompts 等能力,并校验输入、执行业务逻辑、返回结果 | 不假设自己能直接访问 Host 的模型、其他 Server 或全部用户上下文 |

快速判断
遇到“是否允许调用删除工具、是否把文件内容交给模型”时,责任在 Host,因为它掌握用户意图、会话和授权界面。Server 仍需做最小权限、参数校验和服务端鉴权,但不能把自身校验当作用户同意。
遇到“如何连接 stdio 或 Streamable HTTP、如何发送请求、如何处理协议版本不兼容”时,责任在 Client 或所用 SDK。Host 可以配置策略,但不应把协议细节散落到业务页面中。
遇到“查询数据库、读取仓库、调用内部 API、返回结构化结果”时,责任在 Server。Server 应把能力声明和实际权限保持一致,不能在工具描述中承诺自己无法保证的行为。
高频连接形态
本地工具通常是 Host 启动本地 Server,并通过 stdio 创建一个 Client。远程服务通常由多个 Host 的 Client 通过 Streamable HTTP 访问同一个 Server 实例或集群。
一个 Host 连接多个 Server 时,应为每个 Server 建立独立 Client,并分别记录能力、认证信息、超时和健康状态。这样单个 Server 故障不会污染其他连接,也能准确定位工具来自哪个服务。
风险与边界
把 Server 当成 Host 会导致服务端自行决定模型调用、用户授权或上下文传播,后果是越权操作和数据泄露。安全替代方案是由 Host 统一展示来源、参数和确认动作,Server 只执行已授权请求。
让多个不相关 Server 共用同一份可变 Client 状态,会造成能力串线、凭据误用和错误路由。安全替代方案是按 Server 隔离 Client、认证与缓存,并在日志中同时记录 Host 会话 ID、Client 标识和 Server 标识。
速查结论:Host 管全局与授权,Client 管一条协议连接,Server 管能力实现。
根据语言、运行环境和兼容性要求选择 MCP 规范版本与官方 SDK。
选择 MCP 规范版本与 SDK
选择顺序应是“目标 Host 支持什么版本 → 官方 SDK 是否实现该版本 → 当前运行环境是否适配”,而不是直接追最新包。生成本条目时,MCP Current 规范版本为 2026-07-28;生产接入仍应以 Host、Client SDK 与 Server 的共同支持集为准。
版本判断
MCP 规范版本使用 YYYY-MM-DD 标识不兼容变更日期。2026-07-28 采用无状态、请求级版本与能力声明;2025-11-25 及更早版本使用旧的握手兼容路径,迁移时不能只修改版本字符串。
远程 Streamable HTTP 请求会在 _meta 中声明 io.modelcontextprotocol/protocolVersion,同时通过 MCP-Protocol-Version 请求头携带版本。Server 不支持时应返回 UnsupportedProtocolVersionError 及其支持列表,Client 再选择共同版本重试。
主动探测 Server
将 <HOST>、<PATH> 替换为实际 MCP 端点;需要鉴权时额外添加服务端要求的 Authorization 请求头。
curl -sS -X POST "https://<HOST>/<PATH>" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "MCP-Protocol-Version: 2026-07-28" \
--data '{
"jsonrpc": "2.0",
"id": 1,
"method": "server/discover",
"params": {
"_meta": {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientInfo": {
"name": "compat-check",
"version": "1.0.0"
},
"io.modelcontextprotocol/clientCapabilities": {}
}
}
}'预期结果
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"resultType": "complete",
"supportedVersions": ["2026-07-28"],
"capabilities": {},
"_meta": {
"io.modelcontextprotocol/serverInfo": {
"name": "<SERVER_NAME>",
"version": "<VERSION>"
}
}
}
}实际响应可能额外包含能力、缓存或扩展字段。读取时先看 supportedVersions 是否包含目标版本,再根据 capabilities 判断 Tools、Resources、Prompts 或其他特性是否可用;不要只凭 HTTP 200 判断兼容。
SDK 选择
| 运行环境 | 优先选择 | 适用判断 |
|---|---|---|
| Node.js、浏览器侧 Host 或 TypeScript Server | 官方 TypeScript SDK | 已使用 TypeScript,需快速共享类型和 JSON Schema |
| Python 服务、数据与 AI 工具链 | 官方 Python SDK | 现有运行时以 asyncio、FastAPI 或 Python 工具为主 |
| Spring Boot、企业 JVM 服务 | 官方 Java SDK | 需要接入 Java 依赖管理、线程模型和企业鉴权 |
| Kotlin/JVM 或多平台项目 | 官方 Kotlin SDK | 项目主体为 Kotlin,不希望混用 Java 风格 API |
| .NET 服务 | 官方 C# SDK | 依赖 ASP.NET Core、依赖注入与 .NET 运维体系 |
| Go、Rust、Swift、PHP、Ruby | 对应语言的官方 SDK | 以团队现有运行时、部署体积和维护能力为首要条件 |
SDK 包版本与协议版本不是同一套编号。升级 SDK 后必须查看其发布说明和支持矩阵,确认是否支持目标协议、传输和扩展;不能看到包版本更高就假定协议兼容。
推荐决策流程
新项目先列出必须兼容的 Host,记录其支持版本、传输方式和认证要求;再选择对应语言的官方 SDK,并把 SDK 精确版本写入锁文件。旧项目升级时先在测试环境同时支持新旧版本,再逐步淘汰旧握手路径。
上线前至少验证 server/discover、能力列表、一次只读调用、一次受控写操作、超时与版本不兼容错误。多语言实现还应使用相同测试用例核对字段、错误码和权限行为。
风险与边界
直接使用 Draft、预发布 SDK 或未锁定依赖,可能在升级后出现 API、消息结构或扩展行为变化。安全替代方案是固定 SDK 版本,记录协议版本,并通过兼容性测试后再更新。
只按 Server 支持版本选型而忽略 Host,会出现 Server 可运行但目标应用无法连接。安全替代方案是维护 Host、SDK、Server 三方兼容矩阵,以交集版本作为生产基线。
速查结论:先确定目标 Host 的共同协议版本,再选对应语言的官方 SDK,最后锁版本并用发现请求验证真实能力。
创建包含依赖、入口文件和运行脚本的最小 MCP 服务端工程。
初始化 MCP 服务端项目
用于从空目录创建可运行的 TypeScript MCP stdio 服务端,包含依赖、入口文件、类型检查脚本和最小工具。完成后项目能通过 TypeScript 校验,并保持运行等待 MCP 客户端连接。
前置条件
使用 Node.js 20 或更高版本,并确认 node -v、npm -v 可正常执行。下面命令适用于 Bash、zsh 和常见 Linux CI 环境。
一次性创建
在准备存放项目的父目录执行:
mkdir mcp-minimal-server
cd mcp-minimal-server
npm init -y
npm pkg set type=module
npm pkg set 'scripts.dev=tsx src/index.ts'
npm pkg set 'scripts.check=tsc --noEmit'
npm install @modelcontextprotocol/server
npm install -D typescript tsx @types/node
mkdir src
cat > tsconfig.json <<'JSON'
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"strict": true,
"types": ["node"],
"noEmit": true
},
"include": ["src/**/*.ts"]
}
JSON
cat > src/index.ts <<'TS'
import { McpServer } from '@modelcontextprotocol/server';
import { serveStdio } from '@modelcontextprotocol/server/stdio';
function createServer(): McpServer {
const server = new McpServer({
name: 'minimal-mcp-server',
version: '1.0.0'
});
server.registerTool(
'health',
{ description: 'Return the server health state' },
async () => ({
content: [{ type: 'text', text: 'ok' }]
})
);
return server;
}
// stdio 的 stdout 专供 JSON-RPC;运行日志必须写入 stderr。
void serveStdio(createServer).catch((error: unknown) => {
console.error('MCP server failed:', error);
process.exitCode = 1;
});
console.error('minimal MCP server running on stdio');
TS
npm run check预期输出中最后两行如下;依赖安装数量和耗时会随环境变化:
> mcp-minimal-server@1.0.0 check
> tsc --noEmit没有 TypeScript 错误即表示依赖、ESM 配置和入口文件能够正确解析。
运行验证
npm run dev预期输出:
> mcp-minimal-server@1.0.0 dev
> tsx src/index.ts
minimal MCP server running on stdio进程保持运行且不继续输出是正常现象:stdio 服务端正在等待客户端从标准输入发送协议消息,使用 Ctrl+C 停止。
风险与边界
stdio 的 stdout 是协议通道。只要业务代码执行 console.log,客户端就可能把普通文本当作 JSON-RPC 解析,导致连接失败;安全替代方案是统一使用 console.error 或写入日志文件。
不要在已有非空目录直接覆盖 package.json、tsconfig.json 或 src/index.ts,否则可能丢失原配置。先使用新目录验证,再把依赖和脚本合并进现有工程。
排障清单
- 出现
ERR_MODULE_NOT_FOUND:确认在项目根目录执行过npm install,并检查package.json中存在"type": "module"。 - 出现
Cannot find type definition file for 'node':重新安装@types/node,并保留tsconfig.json的"types": ["node"]。 - 客户端启动后立即断开:检查启动命令、工作目录和 Node.js 路径;同时确认服务端没有向 stdout 打印日志。
兼容性
该工程使用拆分后的 @modelcontextprotocol/server 包和 serveStdio 入口,适用于当前 ESM 版 TypeScript SDK。旧版 @modelcontextprotocol/sdk 的导入路径不同,不要在同一文件中混用两套 API。
配置服务端名称、版本和支持的协议能力。
声明服务端信息
用于设置客户端可见的服务端名称、实现版本和能力声明,并通过本地客户端读取结果。version 表示服务端实现版本,不是 MCP 协议版本。
声明方式
在上一条目的项目中新增 src/server-info.ts。服务信息放在第一个参数中;能力放在第二个参数中,并且必须与实际注册的处理器一致。
import { McpServer } from '@modelcontextprotocol/server';
import { serveStdio } from '@modelcontextprotocol/server/stdio';
function createServer(): McpServer {
const server = new McpServer(
{
name: 'inventory-mcp',
version: '1.3.0',
title: '库存查询服务',
description: '提供只读库存健康检查'
},
{
capabilities: {
tools: { listChanged: true }
}
}
);
server.registerTool(
'inventory-health',
{ description: 'Return the inventory backend health state' },
async () => ({
content: [{ type: 'text', text: 'ok' }]
})
);
return server;
}
void serveStdio(createServer);这里声明了 tools 能力,同时实际注册了 inventory-health 工具。使用高层 McpServer 注册工具、资源或提示词时,SDK也会根据注册项补充相应能力;显式配置主要用于 listChanged、资源订阅等能力标志。
字段速查
name:稳定的程序标识,适合配置、日志和客户端匹配;发布后不宜频繁修改。version:服务端实现版本,通常与发布包版本一致,例如1.3.0。title:面向用户的显示名称,可使用中文。description:简要说明服务端提供什么,不应包含密钥、内部地址或动态状态。capabilities:客户端可调用的协议能力。只声明已经实现并注册处理器的tools、resources、prompts等能力。
验证声明结果
新增 src/check-info.ts,由测试客户端启动服务端并读取它公开的信息:
import { Client } from '@modelcontextprotocol/client';
import { StdioClientTransport } from '@modelcontextprotocol/client/stdio';
const client = new Client(
{ name: 'metadata-check', version: '1.0.0' },
{ versionNegotiation: { mode: 'auto' } }
);
const command = process.platform === 'win32' ? 'npx.cmd' : 'npx';
const transport = new StdioClientTransport({
command,
args: ['tsx', 'src/server-info.ts'],
stderr: 'ignore'
});
await client.connect(transport);
console.log(
JSON.stringify(
{
serverInfo: client.getServerVersion(),
capabilities: client.getServerCapabilities(),
era: client.getProtocolEra()
},
null,
2
)
);
await client.close();安装客户端包并执行验证:
npm install --silent @modelcontextprotocol/client
npx tsx src/check-info.ts预期输出:
{
"serverInfo": {
"name": "inventory-mcp",
"version": "1.3.0",
"title": "库存查询服务",
"description": "提供只读库存健康检查"
},
"capabilities": {
"tools": {
"listChanged": true
}
},
"era": "modern"
}字段顺序可能不同,但 name、version 和 tools 能力必须存在。era 为 modern 表示客户端与 serveStdio 协商到 2026-07-28 及之后的协议时代。
风险与边界
声明了能力但没有注册对应处理器时,客户端会展示不可用功能,调用后可能收到方法不存在、超时或连接错误。安全做法是先完成注册和测试,再开放能力;删除功能时同步移除能力声明。
服务信息由服务端自报,适合展示和排障,不应作为身份认证或授权依据。需要安全决策时,应使用受信任的认证凭据、传输层身份和服务端权限校验。
排障清单
serverInfo为undefined:必须等待client.connect()完成后再读取。capabilities缺少tools:确认registerTool在createServer()返回前执行,并检查能力名称拼写。- 输出中出现额外日志或 JSON 解析失败:服务端不得向 stdout 写普通日志;改用 stderr。
- 旧客户端无法连接:保留
serveStdio(createServer)的默认兼容行为,不要在尚未完成迁移时拒绝 legacy 协商。
兼容性
当前拆分包使用 @modelcontextprotocol/server 和 @modelcontextprotocol/client。旧版 v1 项目通常从 @modelcontextprotocol/sdk/... 导入;迁移时应整套替换导入和启动方式,避免高层服务端、传输层和客户端来自不同主版本。
通过标准输入输出启动适合本地 Host 调用的 MCP 服务端。
启动 stdio 服务
当 MCP 服务只供本机 Host 调用时,使用 stdio 传输。Host 会把服务端作为子进程启动,通过 stdin 写入 MCP 消息,通过 stdout 读取响应;手工启动主要用于确认运行时、入口文件和依赖是否正确。
命令定位
先找到编译后的服务入口,而不是 TypeScript 源文件。Node.js 项目常见入口为 build/index.js 或 dist/index.js,生产配置应使用绝对路径,避免 Host 的工作目录与终端不同。
node /absolute/path/to/mcp-server/build/index.js预期输出
(stdout 无普通文本;进程保持运行并等待 Host 发送 MCP 消息)未返回 Shell 提示符通常表示服务正在等待输入,不等于卡死。启动日志应写入 stderr;stdio 协议要求 stdout 只承载 MCP 消息。
基本语法
<runtime-command> <server-entry> [server-arguments...]runtime-command 是 node、python、java 等运行时;server-entry 是可执行文件、脚本或 JAR。服务必须持续读取标准输入,直到 Host 关闭连接或进程退出。
高频用法
正常使用时由 Host 按配置自动启动,不要先在另一个终端常驻同一实例。前台手工启动适合排查入口不存在、依赖缺失、权限不足或启动即退出。
需要检查协议握手、工具列表和调用结果时,可用 MCP Inspector 启动同一条 stdio 命令:
npx -y @modelcontextprotocol/inspector node /absolute/path/to/mcp-server/build/index.js预期结果
浏览器打开 Inspector;连接成功后可查看服务暴露的 tools、resources 或 prompts。首次运行可能下载 Inspector;本地监听端口会因环境而异。
风险与边界
向 stdout 写调试日志会与 JSON-RPC 消息混流,触发解析失败、连接反复断开或工具列表为空。安全替代方案是把日志写到 stderr,Node.js 中使用 console.error(),不要使用 console.log()。
stdio 服务不适合等待终端交互输入。若代码调用密码提示、确认菜单或 REPL,Host 无法完成交互,进程可能永久阻塞;应改为通过受控环境变量、命令参数或配置文件传入。
直接使用相对路径时,GUI Host 常以不同工作目录启动进程,可能出现 MODULE_NOT_FOUND 或文件不存在。生产配置使用运行时和入口文件的绝对路径。
排障清单
先确认运行时和入口文件存在:
node --version
test -f /absolute/path/to/mcp-server/build/index.js && echo "entry ok"预期输出
v<MAJOR>.<MINOR>.<PATCH>
entry ok若进程立即退出,直接执行 Host 配置中的完整命令并查看 stderr。若命令能启动但 Host 连接失败,依次检查是否污染 stdout、入口是否为最新构建产物、依赖是否完整,以及 Host 是否传入了服务必需的环境变量。
兼容性
macOS 与 Linux 可直接使用 POSIX 路径;Windows 配置中的反斜杠需要按 JSON 写成 \\,也可使用正斜杠。不同 SDK 的启动 API 不同,但 stdio 的边界一致:Host 启动子进程,协议走 stdin/stdout,诊断日志走 stderr。
在支持 MCP 的 Host 中配置命令、参数和环境变量以连接本地服务。
配置 Host 连接服务
在支持本地 MCP 服务的 Host 中,配置服务名、启动命令、参数和必要环境变量。保存并重启 Host 后,Host 会按配置创建 stdio 子进程并完成 MCP 初始化。
配置结构
下面是常见的 mcpServers 配置形态。路径必须替换为本机真实绝对路径,环境变量名必须与服务端实际读取的名称一致。
{
"mcpServers": {
"local-tools": {
"command": "/absolute/path/to/node",
"args": [
"/absolute/path/to/mcp-server/build/index.js"
],
"env": {
"MCP_API_TOKEN": "<TOKEN>",
"LOG_LEVEL": "info"
}
}
}
}local-tools 是 Host 内显示的服务标识;command 只放可执行程序;args 按数组顺序传给进程;env 只注入该服务需要的变量。若服务不需要环境变量,可省略 env。
配置步骤
先备份现有配置,并把新服务合并到已有 mcpServers,不要覆盖其他服务。随后将 command 改为运行时绝对路径,将 args 第一项改为已构建入口,保存后完全退出并重新启动 Host。
可用 Node.js 自身确认运行时位置,并解析入口文件的真实路径:
node -p "process.execPath"
node -e "console.log(require('node:fs').realpathSync(process.argv[1]))" /absolute/path/to/mcp-server/build/index.js预期输出
<PATH>/node
/absolute/path/to/mcp-server/build/index.js若第二条命令报文件不存在,应先执行项目构建,并把配置指向实际生成的 build 或 dist 文件。
验证连接
在终端中原样执行 command 与 args,先排除 Host 配置之外的问题:
"/absolute/path/to/node" "/absolute/path/to/mcp-server/build/index.js"预期输出
(stdout 无普通文本;进程持续运行并等待 MCP 输入)终端验证通过后重启 Host,在连接器、工具或开发者页面确认 local-tools 已加载,并检查服务暴露的工具是否出现。若 Host 有日志面板,优先查看子进程退出码和 stderr。
风险与边界
把令牌直接写入配置文件时,配置同步、备份、截图或误提交可能泄露凭据。优先使用 Host 提供的密钥存储或系统凭据注入;无法使用时,限制配置文件权限、使用最小权限令牌,并确保文件不进入版本库。
GUI Host 继承的 PATH 往往少于交互式 Shell。只写 "command": "node" 可能在终端正常、在 Host 中却提示命令不存在;安全做法是配置运行时绝对路径。
第三方 MCP 服务以当前用户权限运行,并能读取传入的环境变量。只有在审查来源和代码后才启用,且不要把无关的云密钥、代理凭据或数据库口令批量传给子进程。
排障清单
配置无法加载时先用 JSON 校验器检查双引号、逗号和反斜杠;标准 JSON 不允许注释或尾随逗号。服务显示离线时,复制完整命令到终端执行,检查入口路径、文件权限、依赖和构建产物。
连接建立后立即断开,通常检查服务是否向 stdout 输出了普通日志。工具为空时确认配置指向最新构建文件,并查看服务初始化是否因缺少环境变量而失败。修改配置后无变化时,完全退出 Host 进程再重启,而不是只关闭窗口。
兼容性
mcpServers、command、args、env 是常见桌面 Host 的配置形态,但并非所有 Host 都使用同一文件名或 JSON 层级;有些 Host 通过设置界面维护相同信息。Windows JSON 路径中的 \ 必须写成 \\,例如 C:\\Program Files\\nodejs\\node.exe。
注册一个可被模型发现和调用的 MCP Tool。
定义 MCP Tool
当模型需要执行查询、计算或受控写操作时,用 Tool 暴露明确的动作入口。注册后,客户端通过 tools/list 发现工具,并通过 tools/call 传入参数;静态说明文档更适合 Resource,不要为了“可见”而滥用 Tool。
基本语法
以下示例基于 TypeScript SDK v1 的稳定包名,注册 check_service,再用本地客户端完成发现和调用。
mkdir mcp-tool-demo && cd mcp-tool-demo
npm init -y
npm pkg set type=module
npm install @modelcontextprotocol/sdk zod预期输出
added <ID> packages, and audited <ID> packages保存为 server.mjs:
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
const server = new McpServer({
name: "ops-tools",
version: "1.0.0"
});
server.registerTool(
"check_service",
{
title: "检查服务状态",
description: "按服务名返回模拟健康状态;只读,不会重启或修改服务。",
inputSchema: {
service: z
.string()
.regex(/^[a-z][a-z0-9-]{1,31}$/)
.describe("服务短名,例如 api 或 order-service")
}
},
async ({ service }) => {
const result = {
service,
status: service === "api" ? "UP" : "UNKNOWN"
};
return {
content: [{ type: "text", text: JSON.stringify(result) }]
};
}
);
await server.connect(new StdioServerTransport());保存为 client.mjs:
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
const client = new Client({ name: "smoke-test", version: "1.0.0" });
const transport = new StdioClientTransport({
command: process.execPath,
args: ["server.mjs"]
});
await client.connect(transport);
const listed = await client.listTools();
console.log(listed.tools.map((tool) => tool.name).join(","));
const called = await client.callTool({
name: "check_service",
arguments: { service: "api" }
});
console.log(called.content[0].text);
await client.close();执行:
node client.mjs预期输出
check_service
{"service":"api","status":"UP"}第一行证明工具可被发现,第二行是处理器返回的文本内容。实际工具列表可能包含同一服务器注册的其他名称。
定义要点
工具名应稳定、唯一并使用可读的动词短语;description 要写清动作、对象、限制和副作用,让模型知道何时调用。inputSchema 负责在处理器运行前拒绝非法参数,处理器只处理已经通过结构校验的业务输入。
返回值至少包含 content。需要机器读取时,可同时定义 outputSchema 并返回 structuredContent;声明了输出 Schema 后,返回结构必须与其一致,否则部分客户端会拒绝或降级结果。
风险与边界
写入、删除、支付、发布和重启类工具若仅靠描述约束,模型仍可能误调用,后果是数据变化或服务中断。安全替代方案是拆分“预览”和“执行”工具,在执行前做身份鉴别、资源级授权、幂等校验和人工确认,并把调用人、参数摘要与结果写入审计日志。
stdio 传输把标准输出用于协议报文。服务端向 stdout 打印调试日志会破坏 JSON-RPC 流,表现为初始化失败或响应解析错误;日志应写到 stderr,例如使用 console.error()。
排障清单
tools/list看不到工具:确认注册代码在connect()前执行,名称未重复,启动的是最新构建产物。- 调用提示参数无效:对照 Schema 检查必填项、类型、枚举和正则,不要在处理器内偷偷接受另一种格式。
- 客户端连接后立即退出:直接运行服务时等待输入是正常现象;用 MCP 客户端或 Inspector 建立连接验证。
- 返回成功但模型读不懂:缩短文本结果,并为稳定字段补充
outputSchema与structuredContent。
兼容性
示例使用 @modelcontextprotocol/sdk 的 v1 导入路径。v2 使用拆分后的包名与 serveStdio 风格,迁移时不要混用两代导入;协议层的工具名、描述、输入 Schema 和调用语义保持一致。
使用清晰且可校验的 JSON Schema 描述工具参数。
设计工具输入 Schema
输入 Schema 用来限制模型可提交的参数,并向客户端说明字段含义。目标不是复刻数据库表,而是把一次工具调用所需的最小输入描述清楚,使错误在业务逻辑执行前被拒绝。
基本语法
MCP Tool 的 inputSchema 根节点应为对象。下面的 Schema 描述“按环境查询日志”:service 和 environment 必填,limit 有范围与默认值,并禁止未声明字段。
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"additionalProperties": false,
"properties": {
"service": {
"type": "string",
"pattern": "^[a-z][a-z0-9-]{1,31}$",
"description": "服务短名,例如 order-service"
},
"environment": {
"type": "string",
"enum": ["test", "staging", "prod"],
"description": "目标环境"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"default": 50,
"description": "最多返回的日志条数"
},
"contains": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "可选的文本过滤条件"
}
},
"required": ["service", "environment"]
}default 是客户端提示,不保证所有客户端都会自动补值;处理器仍应在缺省时使用自己的安全默认值。
验证示例
保存上面的对象为 input-schema.json,再用 Ajv 2020 验证一组合法和非法参数。
npm init -y
npm pkg set type=module
npm install ajv预期输出
added <ID> packages, and audited <ID> packages保存为 validate.mjs:
import fs from "node:fs";
import Ajv2020 from "ajv/dist/2020.js";
const schema = JSON.parse(fs.readFileSync("input-schema.json", "utf8"));
const ajv = new Ajv2020({ allErrors: true });
const validate = ajv.compile(schema);
const samples = [
{ service: "order-service", environment: "prod", limit: 20 },
{ service: "Order Service", environment: "production", limit: 500 }
];
for (const sample of samples) {
const valid = validate(sample);
console.log(valid ? "VALID" : "INVALID");
if (!valid) {
console.log(validate.errors.map((error) => error.instancePath || "/").join(","));
}
}执行:
node validate.mjs预期输出
VALID
INVALID
/service,/environment,/limit第二组同时违反服务名格式、环境枚举和数量上限。allErrors: true 会一次返回全部问题,便于排查;实际错误文本可能随 Ajv 小版本略有差异。
设计规则
字段名使用稳定业务语义,不暴露内部表名或临时缩写。每个字段的 description 应说明单位、格式、可选值和例子;对字符串设置长度,对数字设置上下界,对固定集合使用 enum,对数组设置 minItems、maxItems 和 uniqueItems。
必填项只保留完成动作不可缺少的参数。能由服务端从身份、会话或配置推导出的值不要让模型填写,例如租户 ID、操作者 ID 和内部权限级别,避免伪造或跨租户访问。
复杂输入优先拆成多个职责单一的工具。只有确实需要“二选一”结构时才使用 oneOf 或 anyOf,并确保各分支可以明确区分;过深嵌套和大量条件组合会降低模型选参稳定性,也可能增加验证开销。
风险与边界
只校验类型而不限制范围时,模型可能提交超大 limit、超长文本或巨型数组,导致慢查询、内存上涨或下游限流。安全替代方案是在 Schema 中设置上限,并在业务层再次执行资源配额、超时和分页限制。
additionalProperties: false 能尽早发现拼写错误,但旧客户端或兼容层可能附加扩展字段并因此失败。对外部生态兼容性要求高时,可先记录未知字段并逐步收紧;涉及敏感操作时应保持严格拒绝。
不要把口令、访问令牌或私钥设计成普通工具参数。参数可能进入模型上下文、客户端日志或审计记录;应改用服务器端凭据、授权上下文或密钥管理系统。
排障清单
- 模型频繁漏填:减少必填字段,并把关键约束写进字段描述和工具描述。
- Schema 验证通过但业务失败:补充跨字段校验,例如开始时间不得晚于结束时间。
- 客户端报 Schema 不兼容:确认 SDK 与客户端支持的 JSON Schema 草案;生产环境优先使用双方共同支持的关键字子集。
- 修改 Schema 后仍看到旧参数:重启服务器并让客户端重新执行
tools/list,动态工具列表还需发送列表变更通知。
速查原则:先限制类型和数量,再写清语义与示例,最后把授权、配额和跨字段规则留在业务层做第二道校验。
按照协议返回文本、结构化数据或其他受支持的工具结果内容。
返回工具结果
在 tools/call 已成功执行时,返回 result 对象,并把模型可读内容放入 content。需要稳定字段供程序消费时,同时返回 structuredContent;图片、音频或资源则使用对应的内容块类型。
基本结构
content 是内容块数组,适合给模型或用户直接阅读;structuredContent 是机器可读结果,应与工具声明的 outputSchema 一致。isError 省略或为 false 表示工具执行成功。
以下命令需要系统已安装 jq。
cat > /tmp/mcp-tool-result.json <<'JSON'
{
"jsonrpc": "2.0",
"id": "<ID>",
"result": {
"content": [
{
"type": "text",
"text": "已查询 2 条订单。"
}
],
"structuredContent": {
"count": 2,
"orders": [
{"orderId": "A1001", "status": "PAID"},
{"orderId": "A1002", "status": "PENDING"}
]
},
"isError": false
}
}
JSON
jq '{
message: .result.content[0].text,
count: .result.structuredContent.count,
isError: (.result.isError // false)
}' /tmp/mcp-tool-result.json预期输出
{
"message": "已查询 2 条订单。",
"count": 2,
"isError": false
}读取时先检查顶层是否存在 result,再按内容块的 type 分派处理;程序化调用优先读取 structuredContent,对话场景优先读取精简的 content。
高频用法
- 纯文本结果:返回一个或多个
text内容块,适合状态说明、摘要和下一步建议。 - 结构化结果:返回
structuredContent,并在content中保留语义等价的简短文本,兼容只识别文本的客户端。 - 二进制结果:图片或音频内容块使用 Base64 数据和准确的
mimeType;体积较大时优先返回资源链接。 - 文件或资源:使用
resource_link返回可获取的 URI,或使用resource内嵌小型资源及其 MIME 类型。
输出字段说明
| 字段 | 读取方式 |
|---|---|
content |
必备的非结构化内容块数组;逐项检查 type |
structuredContent |
可选的结构化数据;存在 outputSchema 时必须匹配 |
isError |
可选;省略按 false 处理 |
_meta |
可选扩展元数据;不要依赖未协商的私有字段 |
风险与边界
同时在 content 和 structuredContent 放入完整大数据会重复占用上下文,可能导致响应超限或模型关注点被淹没。安全做法是让 content 只保留摘要、总数和少量预览,完整数据通过分页、资源链接或后续工具调用获取。
图片和音频直接内嵌 Base64 会放大报文。超过客户端或传输限制时可能超时、断连或占用大量内存,应改用受控资源 URI,并校验访问权限、有效期和 MIME 类型。
服务端返回前应校验输出模式并清理敏感字段。若 structuredContent 与 outputSchema 不一致,客户端可能拒绝结果;若把密钥、内部路径或堆栈写入 content,模型和用户都可能看到。
兼容性
协议版本由客户端与服务端协商。为兼容较旧实现,结构化结果优先使用对象作为根节点,并在 content 中附带精简的文本或序列化表示;不要假设所有客户端都支持图片、音频、资源链接或自定义 _meta。
区分协议错误与业务执行错误,并向模型返回可处理的信息。
返回工具执行错误
先判断失败发生在协议分发层还是工具执行层。请求无法被 MCP 正确识别或分发时返回顶层 JSON-RPC error;工具已经被调用,但外部 API、权限、业务校验或运行过程失败时,仍返回 result,并设置 isError: true,让模型能够读取原因并调整下一次调用。
错误分类
协议错误适用于 JSON-RPC 报文无效、方法不存在、工具不存在、服务端未声明工具能力或发生无法形成工具结果的异常。客户端通常在协议层处理这类错误,模型不一定能看到。
工具执行错误适用于调用已进入具体工具,但参数值不满足业务约束、上游接口失败、权限不足、限流或数据不存在。错误信息应面向模型给出可执行的修正方向,而不是只返回“执行失败”。以下命令需要系统已安装 jq。
cat > /tmp/mcp-errors.ndjson <<'JSON'
{"kind":"protocol","response":{"jsonrpc":"2.0","id":"<ID>","error":{"code":-32602,"message":"Unknown tool: invalid_tool_name"}}}
{"kind":"tool","response":{"jsonrpc":"2.0","id":"<ID>","result":{"content":[{"type":"text","text":"订单不存在;请检查 orderId 后重试。错误编号:<ERROR_ID>"}],"isError":true}}}
JSON
jq -c '{
kind,
hasProtocolError: (.response.error != null),
isToolError: (.response.result.isError // false),
message: (.response.error.message // .response.result.content[0].text)
}' /tmp/mcp-errors.ndjson预期输出
{"kind":"protocol","hasProtocolError":true,"isToolError":false,"message":"Unknown tool: invalid_tool_name"}
{"kind":"tool","hasProtocolError":false,"isToolError":true,"message":"订单不存在;请检查 orderId 后重试。错误编号:<ERROR_ID>"}读取时不要只判断 HTTP 状态或是否存在 JSON-RPC 响应。工具执行错误通常仍是正常的 JSON-RPC result 响应,必须继续检查 result.isError。
返回规则
| 失败位置 | 返回形态 | 典型处理 |
|---|---|---|
| 协议解析或分发 | 顶层 error.code、error.message,可带 error.data |
客户端修复协议、方法或工具名 |
| 工具业务执行 | 顶层 result,其中 isError: true 且 content 描述错误 |
模型修改参数、等待后重试或向用户补充信息 |
| 工具成功 | 顶层 result,isError 省略或为 false |
正常消费内容 |
错误文本应包含失败对象、可修正原因、是否可重试和下一步动作。内部异常可关联一个错误编号,详细堆栈只写服务端日志。
风险与边界
把业务失败抛成协议错误会让模型拿不到可恢复信息,可能反复使用相同参数;安全替代是捕获预期的业务异常,返回 isError: true 和明确的修正建议。
把未知工具、非法 JSON-RPC 或能力不支持伪装成工具结果,会掩盖客户端或协议实现缺陷。此类问题应返回标准 JSON-RPC 错误,并保留请求 id;只有无法解析请求标识时才按协议规则处理缺失或空标识。
直接返回异常堆栈、SQL、访问令牌、内部主机名或完整上游响应,可能泄露系统信息。对外只返回经过脱敏的稳定错误码、简短原因和可执行建议,原始异常记录到受控日志。
自动重试非幂等工具可能重复扣款、发消息或修改数据。只有错误明确标记为可重试、操作具备幂等键且未产生副作用时才重试;否则先查询执行状态或要求人工确认。
排障清单
- 客户端报调用失败但模型无错误信息:检查服务端是否误用了顶层
error。 - 模型忽略失败继续执行:检查
result.isError是否为布尔值true,以及content是否包含可操作说明。 - 客户端把错误当成功数据:同时检查顶层
error和result.isError,不要只看传输状态。 - 同一请求重复产生副作用:核对幂等键、超时后的状态查询和重试策略。
兼容性
不同 SDK 可能把工具异常自动转换为 isError: true,也可能直接抛出异常。生产代码应明确测试 SDK 的映射行为,并用抓包或协议日志确认最终线上报文,而不是只依据本地异常类型。
将文件、数据库记录或业务数据作为 MCP Resource 提供给客户端。
暴露 MCP Resource
当客户端需要把文件、数据库记录或业务数据读取为模型上下文时,使用 Resource。固定资源适合 URI 已知、数量有限且只读的数据;客户端通过 resources/list 发现资源,再通过 resources/read 获取内容。
基本语法与高频用法
TypeScript SDK v2 使用 registerResource(name, uri, config, readCallback) 注册固定资源。
name:服务端内部唯一名称,不等同于资源 URI。uri:资源稳定标识,如config://app、orders://1001。config:提供标题、说明和默认 MIME 类型,供客户端展示与筛选。readCallback:实际读取文件、查询数据库或组装业务数据,返回{ contents: [...] }。
固定资源常用于应用配置、最新报表、数据库中的单条公开记录。数据集合需要动态参数时改用 ResourceTemplate,不要为每个 ID 手工注册一条资源。
可运行验证
下面在进程内启动 MCP 处理器,列出并读取一个订单资源,不占用端口。
tmp_dir="$(mktemp -d)"
cd "$tmp_dir"
npm init -y >/dev/null
npm install @modelcontextprotocol/server @modelcontextprotocol/client tsx >/dev/null
cat > demo.ts <<'TS'
import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
import { createMcpHandler, McpServer } from '@modelcontextprotocol/server';
function createServer(): McpServer {
const server = new McpServer({ name: 'order-resource-demo', version: '1.0.0' });
server.registerResource(
'order-1001',
'orders://1001',
{
title: 'Order 1001',
description: 'A read-only order snapshot',
mimeType: 'application/json'
},
async (uri) => ({
contents: [{
uri: uri.href,
mimeType: 'application/json',
text: JSON.stringify({ id: '1001', status: 'PAID', amount: 12800 })
}]
})
);
return server;
}
const handler = createMcpHandler(createServer);
const transport = new StreamableHTTPClientTransport(new URL('http://test.local/mcp'), {
fetch: (url, init) => handler.fetch(new Request(url, init))
});
const client = new Client(
{ name: 'resource-test', version: '1.0.0' },
{ versionNegotiation: { mode: 'auto' } }
);
await client.connect(transport);
const listed = await client.listResources();
console.log(JSON.stringify(listed.resources.map((item) => item.uri)));
const read = await client.readResource({ uri: 'orders://1001' });
console.log(JSON.stringify(read.contents[0]));
await client.close();
await handler.close();
TS
npx tsx demo.ts预期输出
["orders://1001"]
{"uri":"orders://1001","mimeType":"application/json","text":"{\"id\":\"1001\",\"status\":\"PAID\",\"amount\":12800}"}第一行证明资源已进入可发现列表;第二行是 resources/read 返回的首个内容项。实际业务中将内存对象替换为文件读取、参数化 SQL 或受控的内部 API 调用。
输出字段说明
contents 可以包含多个内容项。每项都应返回实际响应的 uri,并使用 text 承载文本,或使用 blob 承载 Base64 二进制;二进制内容必须给出准确 mimeType。注册配置中的 mimeType 描述资源整体,内容项中的 mimeType 描述该项本身。
风险与边界
当读取回调直接返回用户无权查看的数据时,会造成越权泄露。安全替代方案是在每次读取时校验调用身份、租户和数据权限,并只返回必要字段。
当 URI 或参数被直接拼入文件路径、SQL 或内部 URL 时,可能触发目录穿越、SQL 注入或 SSRF。文件路径应解析真实路径后限制在允许根目录内,数据库查询使用参数绑定,远程地址使用主机白名单。
大文件或大结果集会放大延迟、内存和模型上下文消耗。优先返回摘要、分页索引或可继续读取的细粒度资源,不要一次暴露整个目录或全表。
排障清单
resources/list为空:确认registerResource在服务器连接前执行,且资源未被禁用或移除。resources/read找不到 URI:检查客户端 URI 与注册值是否逐字一致,尤其是协议名、斜杠和大小写。- 客户端无法解析内容:确认文本使用
text,二进制使用 Base64blob,并填写匹配的mimeType。 - 回调异常:先检查文件权限、数据库连接和授权逻辑;不要把敏感堆栈或凭据原样返回客户端。
兼容性
示例使用 MCP TypeScript SDK v2 的拆分包 @modelcontextprotocol/server 与 @modelcontextprotocol/client。旧版 v1 使用单体 @modelcontextprotocol/sdk,导入路径和部分注册 API 不同,迁移时不要混用。
通过 URI 模板暴露带动态参数的资源集合。
定义 MCP 资源模板
当资源 URI 中包含用户 ID、订单号、文件名等动态部分时,使用 ResourceTemplate 注册一组可按模式读取的资源。模板负责匹配 URI 并提取变量,读取回调再根据变量加载对应数据。
基本语法与高频用法
使用 new ResourceTemplate(uriTemplate, { list }) 创建模板,再交给 registerResource。
- URI 模板示例:
orders://{orderId}、users://{userId}/profile。 list: undefined:资源集合不可枚举或数量过大;模板仍会出现在resources/templates/list,但不会向resources/list添加具体实例。list回调:返回有限且允许客户端发现的具体 URI;适合小型目录、团队列表或近期记录。- 读取回调第二个参数是模板变量,如
{ orderId };变量来自客户端 URI,必须视为不可信输入。
可运行验证
下面注册订单模板,同时验证模板列表、可发现实例和动态读取结果。
tmp_dir="$(mktemp -d)"
cd "$tmp_dir"
npm init -y >/dev/null
npm install @modelcontextprotocol/server @modelcontextprotocol/client tsx >/dev/null
cat > demo.ts <<'TS'
import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
import { createMcpHandler, McpServer, ResourceTemplate } from '@modelcontextprotocol/server';
const orders = new Map([
['1001', { id: '1001', status: 'PAID' }],
['1002', { id: '1002', status: 'PENDING' }]
]);
function createServer(): McpServer {
const server = new McpServer({ name: 'order-template-demo', version: '1.0.0' });
server.registerResource(
'order-by-id',
new ResourceTemplate('orders://{orderId}', {
list: async () => ({
resources: [...orders.keys()].map((id) => ({
uri: `orders://${id}`,
name: `Order ${id}`
}))
})
}),
{
title: 'Order detail',
description: 'Read one order by ID',
mimeType: 'application/json'
},
async (uri, { orderId }) => {
const id = String(orderId);
const order = orders.get(id);
if (!order) throw new Error(`Order ${id} not found`);
return {
contents: [{
uri: uri.href,
mimeType: 'application/json',
text: JSON.stringify(order)
}]
};
}
);
return server;
}
const handler = createMcpHandler(createServer);
const transport = new StreamableHTTPClientTransport(new URL('http://test.local/mcp'), {
fetch: (url, init) => handler.fetch(new Request(url, init))
});
const client = new Client(
{ name: 'template-test', version: '1.0.0' },
{ versionNegotiation: { mode: 'auto' } }
);
await client.connect(transport);
const templates = await client.listResourceTemplates();
console.log(JSON.stringify(templates.resourceTemplates.map((item) => item.uriTemplate)));
const listed = await client.listResources();
console.log(JSON.stringify(listed.resources.map((item) => item.uri)));
const read = await client.readResource({ uri: 'orders://1002' });
console.log(JSON.stringify(read.contents[0]));
await client.close();
await handler.close();
TS
npx tsx demo.ts预期输出
["orders://{orderId}"]
["orders://1001","orders://1002"]
{"uri":"orders://1002","mimeType":"application/json","text":"{\"id\":\"1002\",\"status\":\"PENDING\"}"}第一行来自 resources/templates/list,表示客户端可构造符合模式的 URI;第二行来自模板的 list 回调;第三行证明 orderId 已绑定为 1002 并传入读取回调。
列表与读取行为
模板是否可读取与是否可枚举是两件事。list: undefined 不会阻止读取匹配 URI,只表示客户端不能通过 resources/list 获得实例清单。提供 list 时,只应列出当前调用者有权限看到的资源;读取回调仍需再次鉴权,不能把“出现在列表中”当作访问许可。
风险与边界
模板变量被直接拼入 SQL、路径或 URL 时,可能造成注入、目录穿越和 SSRF。安全替代方案是限定变量格式与长度,数据库使用参数化查询,文件读取比较真实路径与允许根目录,远程地址执行协议和主机白名单校验。
当 list 扫描全表或返回海量实例时,会造成超时、内存上涨和客户端上下文膨胀。集合无界时使用 list: undefined;集合可枚举时只返回有限、稳定且授权后的条目。
当模板过于宽泛或多个模板可匹配同一 URI 时,排障会变得困难,甚至读取到错误数据。使用清晰的自定义协议和固定层级,例如 orders://{orderId},避免把多个业务实体塞进同一个可选参数模板。
排障清单
- 模板能列出但读取失败:检查具体 URI 是否符合模板,变量解码后是否通过格式和权限校验。
- 模板出现在
resources/templates/list,实例不在resources/list:确认是否使用了list: undefined,或list回调返回了空数组。 - 回调中的变量为空:检查占位符名称与解构名称是否一致,如
{orderId}对应{ orderId }。 - URI 读取到错误记录:检查 URI 规范化、字符串转数字造成的前导零丢失,以及租户条件是否进入查询。
兼容性
示例基于 MCP TypeScript SDK v2。v2 中 ResourceTemplate 从 @modelcontextprotocol/server 导入;旧版 v1 的包名、导入路径和注册方法不同,升级时应按同一版本文档整体迁移。
在资源内容或资源列表更新时向客户端发送变化通知。
通知资源变化
当资源目录或某个资源内容发生变化时,向客户端发送对应通知,使客户端只刷新必要缓存。先区分“资源集合变化”和“单个资源内容变化”,再选择通知方法。
选择通知类型
| 变化类型 | 通知方法 | 客户端收到后 |
|---|---|---|
| 新增、删除、启用、禁用资源,或可枚举 URI 集合变化 | notifications/resources/list_changed |
重新调用 resources/list |
| 已知 URI 的文本、文件或状态内容变化 | notifications/resources/updated,参数包含 uri |
重新调用 resources/read |
不要用 list_changed 表示普通内容更新,否则客户端会重复拉取整个目录;也不要只发 updated 表示资源增删,否则客户端不知道目录已经变化。

可运行示例
下面使用 TypeScript SDK v2 的进程内 HTTP 测试方式,打开 subscriptions/listen 后分别发布目录变化和内容变化,并等待客户端收到两种通知。保存为 resource-notify.ts。
import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
import { createMcpHandler, McpServer } from '@modelcontextprotocol/server';
let resourceText = 'version=1';
function buildServer(): McpServer {
const server = new McpServer(
{ name: 'resource-notifier', version: '1.0.0' },
{ capabilities: { resources: { subscribe: true } } }
);
// 注册资源会让 McpServer 自动声明 resources.listChanged。
server.registerResource(
'app-config',
'config://app',
{ description: 'Application config', mimeType: 'text/plain' },
async (uri) => ({
contents: [{ uri: uri.href, mimeType: 'text/plain', text: resourceText }]
})
);
return server;
}
const handler = createMcpHandler(buildServer);
const transport = new StreamableHTTPClientTransport(
new URL('http://test.local/mcp'),
{ fetch: (url, init) => handler.fetch(new Request(url, init)) }
);
const client = new Client(
{ name: 'notification-test', version: '1.0.0' },
{ versionNegotiation: { mode: 'auto' } }
);
const received = new Set<string>();
let finish!: () => void;
const done = new Promise<void>((resolve) => {
finish = resolve;
});
function mark(method: string): void {
received.add(method);
if (received.size === 2) finish();
}
// 必须先注册处理器,再连接并打开订阅流。
client.setNotificationHandler(
'notifications/resources/list_changed',
async () => mark('notifications/resources/list_changed')
);
client.setNotificationHandler(
'notifications/resources/updated',
async () => mark('notifications/resources/updated')
);
await client.connect(transport);
const subscription = await client.listen({
resourcesListChanged: true,
resourceSubscriptions: ['config://app']
});
resourceText = 'version=2';
// HTTP handler 是按请求创建服务实例的,跨请求通知应通过 handler.notify 发布。
handler.notify.resourcesChanged();
handler.notify.resourceUpdated('config://app');
let timeout!: ReturnType<typeof setTimeout>;
await Promise.race([
done,
new Promise<never>((_, reject) => {
timeout = setTimeout(() => reject(new Error('notification timeout')), 2000);
})
]).finally(() => clearTimeout(timeout));
console.log(JSON.stringify([...received].sort(), null, 2));
await subscription.close();
await client.close();
await handler.close();安装依赖并运行:
npm init -y
npm install @modelcontextprotocol/server @modelcontextprotocol/client
npm install --save-dev tsx typescript @types/node
npx tsx resource-notify.ts预期输出(省略 npm 安装日志):
[
"notifications/resources/list_changed",
"notifications/resources/updated"
]两项都出现表示订阅流已接收目录变化和 config://app 内容变化;实际业务处理器还应在收到 updated 后重新读取该 URI。
高频用法
- 通过
registerResource返回的注册句柄执行update()、enable()、disable()或remove()时,SDK 会自动发送资源列表变化通知,通常无需手动补发。 - 外部数据库或插件目录改变了可枚举资源,但没有经过注册句柄时,HTTP 服务调用
handler.notify.resourcesChanged();长连接或 stdio 场景可调用server.sendResourceListChanged()。 - 已存在资源的内容改变时,HTTP 服务调用
handler.notify.resourceUpdated(uri);长连接场景通过底层server.server.sendResourceUpdated({ uri })发送。 - 短时间大量更新应按 URI 合并或防抖,避免客户端连续重读同一资源。
风险与边界
- 未建立订阅流:在 2026-07-28 协议连接中,客户端未调用
listen()时不会收到变化通知,结果是缓存持续过期。安全做法是检查subscription.honoredFilter,确认服务器接受了所需通知类型。 - 通知类型混用:集合变化只发
updated会漏掉新增或删除项;内容变化频繁发送list_changed会引发全量刷新。按上表映射,并为两类事件分别写测试。 - 多进程丢通知:
createMcpHandler默认事件总线只在当前进程内有效;发布请求与订阅流落到不同实例时,客户端可能收不到通知。多实例部署应实现共享ServerEventBus,底层接 Redis、NATS 或其他可靠发布订阅系统。
兼容性
TypeScript SDK v2 对应 2026-07-28 协议:客户端通过 subscriptions/listen 选择 resourcesListChanged 和 resourceSubscriptions。2025 时代客户端使用 resources/subscribe 与 resources/unsubscribe 订阅单个 URI;在错误协议版本调用 listen() 或 subscribeResource() 会被拒绝。双版本服务必须按协商结果选择订阅路径,不能假设通知会主动推送。
注册可复用的 MCP Prompt,为客户端提供标准化提示消息。
定义提示模板
使用 registerPrompt 注册可复用提示模板,让客户端通过 prompts/list 发现模板,并通过 prompts/get 传入参数获得标准化消息。Prompt 通常由用户在命令、菜单或表单中主动选择,不等同于模型自动调用的 Tool。
基本语法
registerPrompt(name, config, callback) 包含三部分:稳定的模板名称、供客户端展示和校验的配置、返回 messages 的渲染回调。
| 配置项 | 用途 |
|---|---|
title |
客户端展示名称,可省略 |
description |
说明模板解决什么问题 |
argsSchema |
Zod 对象,生成参数清单并在回调前校验 |
messages |
按顺序返回 user 或 assistant 消息及其内容 |
可运行示例
下面注册一个生产故障分诊模板,并用进程内客户端验证列表发现和参数渲染。保存为 prompt-template.ts。
import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
import { createMcpHandler, McpServer } from '@modelcontextprotocol/server';
import * as z from 'zod/v4';
function buildServer(): McpServer {
const server = new McpServer({
name: 'prompt-server',
version: '1.0.0'
});
server.registerPrompt(
'incident-triage',
{
title: 'Incident Triage',
description: 'Generate a concise production troubleshooting request',
argsSchema: z.object({
service: z.string().min(1).describe('Affected service name'),
symptom: z.string().min(1).describe('Observed error or symptom')
})
},
({ service, symptom }) => ({
description: `Troubleshooting request for ${service}`,
messages: [
{
role: 'user' as const,
content: {
type: 'text' as const,
text:
`请排查服务 ${service} 的故障。\n` +
`现象:${symptom}\n` +
'输出:最可能原因、验证命令、回滚建议。'
}
}
]
})
);
return server;
}
const handler = createMcpHandler(buildServer);
const transport = new StreamableHTTPClientTransport(
new URL('http://test.local/mcp'),
{ fetch: (url, init) => handler.fetch(new Request(url, init)) }
);
const client = new Client(
{ name: 'prompt-test', version: '1.0.0' },
{ versionNegotiation: { mode: 'auto' } }
);
await client.connect(transport);
const { prompts } = await client.listPrompts();
console.log(prompts.map((prompt) => prompt.name));
const result = await client.getPrompt({
name: 'incident-triage',
arguments: {
service: 'pay-api',
symptom: 'HTTP 502'
}
});
const content = result.messages[0]?.content;
if (!content || content.type !== 'text') {
throw new Error('expected first prompt message to be text');
}
console.log(content.text);
await client.close();
await handler.close();安装依赖并运行:
npm init -y
npm install @modelcontextprotocol/server @modelcontextprotocol/client zod
npm install --save-dev tsx typescript @types/node
npx tsx prompt-template.ts预期输出(省略 npm 安装日志):
[ 'incident-triage' ]
请排查服务 pay-api 的故障。
现象:HTTP 502
输出:最可能原因、验证命令、回滚建议。第一行证明模板已进入 prompts/list;后续三行是 prompts/get 校验参数并执行回调后的首条文本消息。
输出字段说明
prompts/list 返回模板元数据和参数定义,不会提前渲染消息。prompts/get 接收 name 与 arguments,成功后返回可选 description 和有序 messages。
每条消息包含 role 与一个 content 块。常见内容是 text,也可以返回图片、音频、资源链接或内嵌资源。需要把团队规范一并交给模型时,可嵌入受控 Resource;不要让客户端额外猜测资源 URI。
高频用法
- 故障分诊:固定要求输出原因、验证步骤、风险和回滚方案,只把服务名与现象参数化。
- 代码审查:把代码作为必填参数,并在模板中明确检查范围,避免每个客户端自行拼接提示词。
- 翻译或生成模板:对语言、框架等枚举参数使用
completable()提供补全,正文参数仍由argsSchema校验。 - 模板动态下线或修改时,保留
registerPrompt返回的句柄并调用update()、disable()或remove();SDK 会自动发送提示列表变化通知。
风险与边界
- 参数缺失或类型错误:
argsSchema校验失败会使prompts/get返回协议错误-32602,回调不会执行。安全做法是为必填字段写清.describe(),可选字段显式使用.optional()。 - 敏感信息泄露:放入
messages的密钥、令牌或内部数据会被客户端和后续模型上下文看到。只嵌入调用者有权读取的内容,并在渲染前脱敏。 - 输入与指令混淆:把外部日志、代码或用户文本直接拼进指令区,可能让其中的文字被误当成新指令。使用清晰边界标记,将不可信内容声明为待分析数据,并让高风险操作继续通过 Tool 的权限与确认流程执行。
- 模板承担副作用:Prompt 只返回消息,不应假装已经执行部署、删除或支付等操作。需要真实副作用时注册 Tool,并单独做鉴权、幂等和审计。
兼容性
TypeScript SDK v2 使用 @modelcontextprotocol/server 的 registerPrompt;v1 的 prompt() 已被替代。支持 Prompt 的客户端应实现 prompts/list 与 prompts/get,但是否在界面中展示为斜杠命令或菜单由客户端决定。上线前至少验证模板可发现、必填参数能拒绝空值、返回消息顺序正确。
为提示模板定义必填参数、可选参数和参数说明。
声明提示参数
为 MCP 提示模板声明参数时,要让客户端能够区分必填项、可选项并显示清晰说明。协议层的提示参数是扁平的名称和值集合;必填性和说明来自服务端声明,业务约束仍应在处理函数中校验。
声明规则
参数通常包含 name、可选的 description 和 required。在 Python SDK 2.x 中,无默认值的函数参数会声明为必填;带默认值的参数会声明为可选;Annotated 与 Field(description=...) 用于生成客户端可见说明。
参数名应保持稳定,避免发布后随意改名。说明要写输入含义、格式和边界,例如“源码文本,最大 20 KB”,不要只写“代码”或“字符串”。
可运行示例
下面的脚本注册一个提示,并通过内存客户端读取 prompts/list 结果,不需要启动端口。
import asyncio
from typing import Annotated
from mcp import Client
from mcp.server import MCPServer
from pydantic import Field
mcp = MCPServer("review-service")
@mcp.prompt(title="代码审查")
def review_code(
code: Annotated[str, Field(description="待审查的源码文本,不能为空")],
language: Annotated[
str,
Field(description="源码语言:python、typescript 或 java"),
] = "python",
) -> str:
"""生成带语言上下文的代码审查提示。"""
if not code.strip():
raise ValueError("code must not be blank")
if language not in {"python", "typescript", "java"}:
raise ValueError("unsupported language")
return f"请审查以下 {language} 代码:\n\n{code}"
async def main() -> None:
async with Client(mcp) as client:
result = await client.list_prompts()
print(result.model_dump_json(indent=2, exclude_none=True))
if __name__ == "__main__":
asyncio.run(main())运行命令:
uv run --with "mcp>=2,<3" python server.py预期输出:
{
"resultType": "complete",
"prompts": [
{
"name": "review_code",
"title": "代码审查",
"description": "生成带语言上下文的代码审查提示。",
"arguments": [
{
"name": "code",
"description": "待审查的源码文本,不能为空",
"required": true
},
{
"name": "language",
"description": "源码语言:python、typescript 或 java",
"required": false
}
]
}
]
}读取时重点确认 code.required 为 true,language.required 为 false,且两项说明能直接用于客户端表单。字段顺序可能因 SDK 序列化实现不同而变化。
协议映射
客户端先通过 prompts/list 获取参数声明,再用 prompts/get 提交 arguments。可选参数未提交时,服务端使用声明的默认值;必填参数缺失时,请求应失败,不能用空字符串静默代替。
提示参数不是工具的 JSON Schema。不要依赖客户端完成枚举、长度或敏感词校验;服务端必须再次校验,并把未知参数、缺失参数和非法值区分记录。
风险与边界
当参数直接拼接进提示文本时,恶意内容可能改变原始指令或泄露上下文。触发条件是接收未限制的用户文本并与高权限指令混合;后果包括提示注入、超长请求和日志泄密。安全替代方案是限制长度和允许值、分隔用户内容、避免在参数中接收密钥,并在服务端日志中脱敏。
修改已发布参数名会使旧客户端缓存或自动化调用失效。需要变更时保留旧参数一段兼容期,或发布新的提示名称,不要原地改变含义。
排障清单
prompts/list没有参数:确认函数已被@mcp.prompt()注册,类型注解可被 SDK 解析。- 可选参数显示为必填:确认参数有默认值,例如
language="python"。 - 参数说明为空:确认使用
Annotated[..., Field(description="...")],并检查 Pydantic 与 MCP SDK 主版本兼容。 prompts/get缺参却进入处理函数:在入口增加显式校验,并记录客户端、提示名和缺失字段,不记录敏感原值。
兼容性
Python SDK 2.x 使用 MCPServer;旧版 1.x 常见类名为 FastMCP。升级时先固定依赖主版本并重新核对 prompts/list 输出,避免导入路径变化与参数元数据差异影响客户端。
正确处理 initialize、initialized 和关闭阶段的连接生命周期。
处理初始化生命周期
initialize、notifications/initialized 和连接关闭属于旧版 MCP 会话生命周期。正确顺序是先协商协议版本与能力,再进入业务调用,最后按底层传输关闭连接和释放资源;任何越序消息都应被拒绝或延后。
顺序与约束
旧版连接建立后,客户端必须先发送 initialize。服务端返回选定的协议版本、能力和实现信息后,客户端再发送无响应的 notifications/initialized,此后才进入正常操作阶段。
在收到 initialize 响应前,客户端除 ping 外不应发送其他请求;服务端在收到 notifications/initialized 前,除 ping 和日志通知外不应主动发起其他消息。业务调用只能使用双方已协商的能力。

可运行顺序校验
下面的本地状态机用于验证消息顺序。它不代替 SDK 的传输实现,但可直接放进单元测试,防止业务请求在初始化完成前进入处理器。
from enum import Enum
class State(str, Enum):
NEW = "NEW"
NEGOTIATING = "NEGOTIATING"
WAIT_INITIALIZED = "WAIT_INITIALIZED"
READY = "READY"
CLOSED = "CLOSED"
class LegacyLifecycle:
def __init__(self) -> None:
self.state = State.NEW
def apply(self, event: str) -> None:
transitions = {
(State.NEW, "initialize_request"): State.NEGOTIATING,
(State.NEGOTIATING, "initialize_response"): State.WAIT_INITIALIZED,
(State.WAIT_INITIALIZED, "initialized_notification"): State.READY,
(State.READY, "business_request"): State.READY,
(State.READY, "transport_closed"): State.CLOSED,
}
next_state = transitions.get((self.state, event))
if next_state is None:
raise RuntimeError(f"invalid event={event} in state={self.state}")
self.state = next_state
print(f"{event} -> {self.state}")
lifecycle = LegacyLifecycle()
for item in (
"initialize_request",
"initialize_response",
"initialized_notification",
"business_request",
"transport_closed",
):
lifecycle.apply(item)预期输出:
initialize_request -> State.NEGOTIATING
initialize_response -> State.WAIT_INITIALIZED
initialized_notification -> State.READY
business_request -> State.READY
transport_closed -> State.CLOSED把 business_request 移到 initialized_notification 前,脚本应抛出 RuntimeError。生产代码应将同类情况转换为明确的协议错误并关闭异常连接,避免半初始化会话继续占用资源。
关闭阶段
协议没有专用的 shutdown JSON-RPC 方法,不要自行发送同名请求。stdio 通常由客户端先关闭服务器子进程的输入流,等待其自行退出;超时后发送 SIGTERM,仍不退出再使用 SIGKILL。服务端应在退出前停止接收新任务,并在 finally 或生命周期清理器中关闭数据库连接、线程池和临时文件。
HTTP 通过关闭关联连接表示终止。所有请求都应设置超时;请求超时后停止等待,并在协议版本支持时发送取消通知。即使持续收到进度通知,也要保留最大总超时,防止失控任务永久占用连接。
风险与边界
未完成初始化就处理工具或资源请求,会绕过版本与能力协商,后果可能是字段解析错误、调用未授权能力或服务端崩溃。安全替代方案是在传输入口维护连接状态,只在 READY 状态分发业务方法。
关闭时直接杀死进程会丢失缓冲日志和未提交事务。仅在关闭输入流和 SIGTERM 均超时后使用 SIGKILL,并为关键写操作设计幂等键或事务恢复。
排障清单
- 首条消息不是
initialize:检查客户端是否复用了旧连接,或把业务请求提前写入发送队列。 - 初始化后一直不就绪:抓取 JSON-RPC 日志,确认客户端发送的是
notifications/initialized,且该通知没有id。 - 版本协商失败:记录客户端请求版本和服务端支持列表;没有共同版本时立即断开,不要猜测字段兼容。
- 能力已声明但调用报
Method not found:核对服务端返回的 capabilities 与实际注册处理器是否一致。 - 进程退出卡住:检查后台任务、线程池和子进程是否在关闭钩子中被等待,并为每一步设置独立超时。
兼容性
initialize 握手适用于 2025-11-25 及更早的旧版协议。2026-07-28 起的现代协议取消连接级初始化、会话和 notifications/initialized,改为每个请求携带协议版本与能力元数据,并可用 server/discover 查询支持版本。双栈实现应按传输规定识别新旧协议,不要强迫现代客户端执行旧握手。
在工具、资源或提示列表动态变化时通知已连接客户端。
通知能力列表变化
当工具、资源或提示的可用清单在连接期间发生增删、启停或定义变更时,发送 list_changed 通知,让客户端丢弃旧缓存并重新调用对应的 */list。资源内容变化但资源仍是同一个 URI 时,应发送 notifications/resources/updated,不要误报清单变化。
触发条件
先完成注册表或权限数据更新,再发送通知;客户端重新拉取时必须能立即读到新清单。批量变更应合并为一次通知,避免每次增删都触发重复刷新。
在 MCP 2026-07-28 中,客户端需要先通过 subscriptions/listen 订阅 toolsListChanged、resourcesListChanged 或 promptsListChanged。通知只表示“缓存已过期”,不携带完整的新清单。

TypeScript SDK v2 示例
下面示例注册一个工具,5 秒后禁用它。注册句柄的 disable() 会自动发送 notifications/tools/list_changed;只有 SDK 无法观察到外部注册表变化时,才手动调用 server.sendToolListChanged()。
import { McpServer } from '@modelcontextprotocol/server';
import { serveStdio } from '@modelcontextprotocol/server/stdio';
function buildServer(): McpServer {
const server = new McpServer({
name: 'dynamic-catalog',
version: '1.0.0',
});
const reportTool = server.registerTool(
'run-report',
{ description: 'Run the current report' },
async () => ({
content: [{ type: 'text', text: 'report queued' }],
}),
);
setTimeout(() => {
// 通过注册句柄变更能力,SDK 会同步发布列表变化通知。
reportTool.disable();
}, 5_000);
return server;
}
void serveStdio(buildServer);
console.error('dynamic-catalog MCP server running on stdio');预期结果
[stderr] dynamic-catalog MCP server running on stdio
[client notification] notifications/tools/list_changed客户端收到通知后应再次调用 tools/list;此时 run-report 不再出现在结果中。实际通知是否显示,取决于客户端是否已订阅并实现自动刷新。
通知类型速查
| 清单变化 | 服务端通知 | 客户端刷新 |
|---|---|---|
| 工具 | notifications/tools/list_changed |
tools/list |
| 资源 | notifications/resources/list_changed |
resources/list 与必要时 resources/templates/list |
| 提示 | notifications/prompts/list_changed |
prompts/list |
直接发送方法分别是 sendToolListChanged()、sendResourceListChanged() 和 sendPromptListChanged()。使用低层 Server 时必须预先声明对应能力的 listChanged: true;高层 McpServer 会随注册自动声明。
风险与边界
清单变更通知不能当作授权撤销的唯一手段。触发条件是权限或能力已变化;若客户端未及时刷新,旧工具仍可能显示。服务端仍须在每次调用时重新鉴权,安全替代方案是拒绝已失效调用并返回明确错误。
高频通知会造成客户端反复拉取列表、缓存抖动和模型上下文重建。对文件监听、插件扫描等高频事件先去重并做短时间防抖,只在最终可见清单确实变化后发送一次。
排障与兼容性
收不到通知时依次检查:服务端是否声明 listChanged、客户端是否打开对应 subscriptions/listen、通知是否在正确连接或订阅流上发送、客户端是否在收到后重新执行 */list。同时确认代理没有缓冲或提前关闭长连接。
2026-07-28 只向明确订阅的客户端发送列表变化,并在订阅流中关联 subscriptionId;2025 系列协议允许连接内主动发送。TypeScript SDK v2 的 serveStdio 可兼容两类客户端,但客户端本身仍可能忽略某些通知。生产环境应保留重连或固定入口工具作为降级方案。
通过 MCP 日志通知输出可分级且不会污染传输通道的运行信息。
发送协议日志
使用 notifications/message 向客户端发送带级别的请求内诊断信息,适合展示工具执行阶段、关键分支和可操作错误。它不是持久化审计日志,也不能替代服务端文件日志、集中日志或 OpenTelemetry。
发送条件与级别
MCP 定义 debug、info、notice、warning、error、critical、alert、emergency 八个级别。只发送达到客户端阈值的消息,并保持 logger 名称稳定,便于客户端过滤。
在 2026-07-28 中,客户端必须在当前请求的 _meta 中提供 io.modelcontextprotocol/logLevel;未提供时,服务端不得为该请求发送 notifications/message。日志必须在最终响应之前,沿该请求自己的响应流发送,不能放入 subscriptions/listen。

TypeScript SDK v2 示例
ctx.mcpReq.log() 会按客户端阈值过滤日志,并兼容旧协议的会话级日志设置。示例通过 stdio 启动一个带日志的 reindex 工具。
import { McpServer } from '@modelcontextprotocol/server';
import { serveStdio } from '@modelcontextprotocol/server/stdio';
function buildServer(): McpServer {
const server = new McpServer({
name: 'logging-demo',
version: '1.0.0',
});
server.registerTool(
'reindex',
{ description: 'Rebuild the search index' },
async (_args, ctx) => {
await ctx.mcpReq.log('info', 'reindex started');
const indexed = 42;
// 只记录排障所需结果,不写入文档内容、令牌或用户隐私。
await ctx.mcpReq.log(
'notice',
`reindex complete: indexed=${indexed}`,
);
return {
content: [{ type: 'text', text: `indexed ${indexed} documents` }],
};
},
);
return server;
}
void serveStdio(buildServer);
console.error('logging-demo MCP server running on stdio');预期结果
[client log] info: reindex started
[client log] notice: reindex complete: indexed=42
[tool result] indexed 42 documents客户端若把阈值设为 warning,前两条日志都会被过滤,只看到工具结果。未设置日志级别时,现代协议下同样只返回工具结果。
字段读取
| 字段 | 读取方法 |
|---|---|
level |
判断严重程度,并与客户端阈值比较 |
logger |
可选的模块名,如 database、indexer |
data |
JSON 可序列化内容;优先使用短消息或结构化上下文 |
data 不应复制完整请求、模型提示、访问令牌或数据库记录。需要关联调用时使用脱敏后的请求 ID、耗时、状态和计数,不要把秘密值作为“排障上下文”。
风险与边界
stdio 的 stdout 是 JSON-RPC 传输通道。触发条件是代码或依赖调用 console.log();后果是客户端把普通文本当协议报文并断开连接。安全替代方案是使用 console.error() 写入 stderr,或通过受控的协议日志 API 发送客户端可见信息。
日志过密会放大网络流量、拖慢最终响应并泄露内部实现。对循环、重试和批处理做采样或限频;错误消息保留错误类型、阶段和脱敏标识,不回传堆栈中的密钥、路径或用户数据。
排障与兼容性
看不到日志时检查:客户端是否为当前请求设置日志级别、消息级别是否低于阈值、日志调用是否发生在最终响应之前、客户端是否展示 notifications/message。HTTP 场景还要确认服务端返回可承载中间通知的 SSE 响应流。
notifications/message 在 2026-07-28 已进入弃用期,但仍保留兼容窗口;同时移除了旧的 logging/setLevel,改为请求级 _meta。新系统应把生产审计和长期观测写入服务端日志或 OpenTelemetry,只把协议日志用于短期、客户端可见的请求诊断。
为耗时操作发送进度通知,帮助客户端展示执行状态。
报告任务进度
用于文件处理、批量导入、索引构建等耗时操作。客户端只有在请求 _meta.progressToken 时才表示希望接收进度;服务端复用该令牌发送 notifications/progress,任务结束后再返回一次最终响应。
基本语法
请求中的 progressToken 必须是字符串或整数,并在所有活动请求中保持唯一。通知必须使用原令牌,progress 要持续递增;total 未知时可省略,message 用于展示当前阶段。

可运行示例
下面的 Node.js 脚本模拟一条请求和三次进度通知,可直接观察线上的 JSON-RPC 消息形态。
node <<'NODE'
const request = {
jsonrpc: "2.0",
id: 1,
method: "tools/call",
params: { _meta: { progressToken: "job-42" } }
};
const files = ["a.txt", "b.txt", "c.txt"];
const token = request.params._meta?.progressToken;
for (const [index, file] of files.entries()) {
if (token !== undefined) {
console.log(JSON.stringify({
jsonrpc: "2.0",
method: "notifications/progress",
params: {
progressToken: token,
progress: index + 1,
total: files.length,
message: `processed ${file}`
}
}));
}
}
console.log(JSON.stringify({
jsonrpc: "2.0",
id: request.id,
result: { content: [{ type: "text", text: "processed 3 files" }] }
}));
NODE预期输出
{"jsonrpc":"2.0","method":"notifications/progress","params":{"progressToken":"job-42","progress":1,"total":3,"message":"processed a.txt"}}
{"jsonrpc":"2.0","method":"notifications/progress","params":{"progressToken":"job-42","progress":2,"total":3,"message":"processed b.txt"}}
{"jsonrpc":"2.0","method":"notifications/progress","params":{"progressToken":"job-42","progress":3,"total":3,"message":"processed c.txt"}}
{"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"processed 3 files"}]}}读取时用 progressToken 关联原请求,用 progress / total 计算百分比;最后一行是正常响应,不是进度通知。
常用策略
- 客户端未提供令牌时跳过通知,不能自行生成令牌回传。
- 按阶段变化或约每 200~500 毫秒发送一次,避免逐条循环刷屏。
- 总量未知时只报递增的
progress和简短message;一旦给出total,尽量保持口径稳定。 - 最终响应、错误或取消发生后立即停止发送进度。
风险与边界
高频通知会放大序列化、网络和界面渲染开销,严重时反而拖慢任务;安全替代是节流并合并细粒度事件。进度通知只证明任务仍在推进,不能无限延长请求;客户端仍应设置可配置超时和绝对最大时限。
速查:无 progressToken 不通知;有令牌则原样回传、进度递增、完成即停。
在客户端取消操作时及时停止后台任务并释放资源。
响应取消请求
用于客户端停止耗时工具调用、下载、子进程或数据库操作。取消是协作式信号:服务端收到后应尽快停止工作、释放资源,并避免再为该请求发送响应或进度。
取消入口
stdio 传输通过 notifications/cancelled 携带原请求 requestId;Streamable HTTP 通过关闭该请求的 SSE 响应流表示取消,不应额外依赖取消通知。处理器内部应统一转换为 AbortSignal,让下游操作共享同一取消状态。

可运行示例
下面用 AbortController 模拟服务端任务表和取消通知。实际 MCP SDK 中可将同样的检查点替换为处理器上下文提供的请求级 AbortSignal。
node <<'NODE'
const jobs = new Map();
async function handleRequest(request) {
const controller = new AbortController();
jobs.set(request.id, controller);
try {
for (let step = 1; step <= 10; step++) {
await new Promise((resolve, reject) => {
const timer = setTimeout(resolve, 50);
controller.signal.addEventListener("abort", () => {
clearTimeout(timer);
reject(controller.signal.reason);
}, { once: true });
});
}
console.log(JSON.stringify({
jsonrpc: "2.0",
id: request.id,
result: { ok: true }
}));
} catch (error) {
console.error(`cancelled request=${request.id} reason=${error.message}`);
} finally {
jobs.delete(request.id);
}
}
function handleNotification(notification) {
if (notification.method !== "notifications/cancelled") return;
const { requestId, reason } = notification.params;
jobs.get(requestId)?.abort(new Error(reason ?? "cancelled"));
}
(async () => {
const running = handleRequest({ jsonrpc: "2.0", id: 7, method: "tools/call" });
setTimeout(() => handleNotification({
jsonrpc: "2.0",
method: "notifications/cancelled",
params: { requestId: 7, reason: "user stopped" }
}), 120);
await running;
console.log(`active jobs=${jobs.size}`);
})();
NODE预期输出
cancelled request=7 reason=user stopped
active jobs=0没有出现请求 7 的成功响应,且任务表已清空,说明取消路径和资源回收都已执行。
实现检查点
- 在循环、重试、分页和批处理边界检查取消状态,避免只在入口检查一次。
- 将信号传给支持取消的
fetch、数据库驱动和文件 API;不支持时在返回点丢弃结果。 - 子进程先发送温和终止信号,超时后再强制结束,同时关闭管道和临时文件。
finally中删除任务映射、释放锁和连接;重复取消、未知 ID、已完成请求应安全忽略。
风险与边界
取消可能与任务完成同时发生。若把“未找到任务”当成错误,会制造无意义告警;安全替代是按幂等方式忽略未知或已完成请求。若底层操作不可中断,直接返回“已取消”会掩盖仍在运行的副作用;应停止回传结果、记录后台收尾状态,并为不可撤销步骤设置明确边界。
速查:按传输识别取消信号,统一落到 AbortSignal,在检查点停止并用 finally 回收资源。