AI Agent / 知识点
MCP 开发速查手册
手册条目
根据本地集成或远程访问需求选择 stdio 或 Streamable HTTP。
选择 stdio 或 Streamable HTTP
先看进程边界:由 MCP 宿主在本机启动、只服务当前宿主时选 stdio;需要独立部署、跨网络访问或同时服务多个客户端时选 Streamable HTTP。不要因为“以后可能远程”就提前引入 HTTP 运维成本。

选择表
| 判断项 | stdio | Streamable HTTP |
|---|---|---|
| 启动方式 | 客户端拉起子进程 | 服务独立运行 |
| 典型范围 | 单机、单宿主、开发工具 | 远程服务、多客户端、容器或集群 |
| 通信入口 | stdin / stdout |
单一 MCP URL,例如 /mcp |
| 日志位置 | 只能写 stderr,不能污染 stdout |
应用日志系统;响应仍须符合 MCP |
| 安全重点 | 可执行文件路径、环境变量、最小权限 | TLS、认证授权、Host/Origin 校验、限流 |
配置示意
下面展示常见宿主配置形态。不同宿主的字段名可能略有差异,但进程型配置与 URL 型配置的边界不变。
{
"mcpServers": {
"local-tools": {
"type": "stdio",
"command": "node",
"args": ["/absolute/path/server.js"]
},
"remote-tools": {
"type": "streamable-http",
"url": "https://mcp.example.com/mcp"
}
}
}生效行为:local-tools 由宿主创建子进程并通过标准流通信;remote-tools 连接已有 HTTP 端点。验证时分别检查子进程是否被拉起,以及远程端点能否完成发现、列出工具和调用工具。
风险与边界
选择 stdio 时,服务向 stdout 打印普通日志会破坏逐行 JSON-RPC,结果通常是初始化失败或消息解析错误。安全替代是把日志写到 stderr,并确保每条协议消息独占一行。
选择 Streamable HTTP 时,直接监听 0.0.0.0 且没有认证、TLS、Host/Origin 校验,会暴露工具调用能力,并可能遭受 DNS rebinding。安全替代是本地仅绑定 127.0.0.1;远程部署放在受控网关后,启用 HTTPS、令牌或 OAuth、来源校验和速率限制。
不要为新项目选择旧式 HTTP+SSE。以 2026-07-28 规范为基线,Streamable HTTP 使用单一 POST 端点,每个请求返回 JSON 或请求级 SSE;独立 GET 流和协议级会话属于旧版本兼容行为。
排障清单
stdio启动即断开:检查绝对路径、运行时版本、工作目录、环境变量和文件权限。stdio出现解析错误:确认stdout只有 MCP 消息,普通日志全部转到stderr。- HTTP 返回
403:检查 Host、Origin、反向代理改写和允许来源。 - HTTP 能连通但工具不可见:确认客户端连接的是完整
/mcpURL,并检查协议版本与服务注册逻辑。
速查结论:同机、宿主拉起、单客户端优先 stdio;独立部署、跨网络或多客户端选择 Streamable HTTP。
创建符合 MCP 要求的远程 Streamable HTTP 服务端点。
实现 Streamable HTTP
使用 TypeScript SDK v2 的 createMcpHandler 创建每请求一个 McpServer 的无状态端点,再通过 Node HTTP 适配器挂载到 /mcp。以下示例注册 echo 工具,并用官方客户端完成端到端验证。

安装依赖
mkdir mcp-http-demo
cd mcp-http-demo
npm init -y
npm pkg set type=module
npm install @modelcontextprotocol/server @modelcontextprotocol/client @modelcontextprotocol/node zod
npm install --save-dev tsx typescript @types/node预期输出
added <N> packages<N> 取决于 npm 版本和已有缓存;命令全部退出码为 0 即表示依赖安装成功。
服务端
创建 server.ts。前置校验必须在 MCP 处理器之前执行;本地示例只监听回环地址,避免无意暴露到局域网。
import { createServer } from 'node:http';
import { createMcpHandler, McpServer } from '@modelcontextprotocol/server';
import {
localhostHostValidation,
localhostOriginValidation,
toNodeHandler
} from '@modelcontextprotocol/node';
import * as z from 'zod/v4';
const handler = createMcpHandler(() => {
// 工厂每个 HTTP 请求创建一个服务器实例,不在实例内保存跨请求状态。
const server = new McpServer({ name: 'echo-http', version: '1.0.0' });
server.registerTool(
'echo',
{
description: 'Return the supplied text',
inputSchema: z.object({ text: z.string().min(1) })
},
async ({ text }) => ({
content: [{ type: 'text', text }]
})
);
return server;
});
const nodeHandler = toNodeHandler(handler);
const validateHost = localhostHostValidation();
const validateOrigin = localhostOriginValidation();
const httpServer = createServer((req, res) => {
const pathname = new URL(req.url ?? '/', 'http://localhost').pathname;
if (pathname !== '/mcp') {
res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
res.end('Not Found');
return;
}
// Host 与 Origin 校验失败时直接返回,不让请求进入 MCP 处理器。
if (!validateHost(req, res) || !validateOrigin(req, res)) return;
void nodeHandler(req, res);
});
httpServer.listen(3000, '127.0.0.1', () => {
console.log('MCP endpoint: http://127.0.0.1:3000/mcp');
});
process.on('SIGINT', async () => {
await handler.close();
httpServer.close(() => process.exit(0));
});启动服务
npx tsx server.ts预期输出
MCP endpoint: http://127.0.0.1:3000/mcp客户端验证
保持服务端运行,再创建 client.ts。客户端负责生成正确的协议元数据和 HTTP 头,不要用手写 curl 请求替代完整握手测试。
import {
Client,
StreamableHTTPClientTransport
} from '@modelcontextprotocol/client';
const client = new Client({ name: 'smoke-test', version: '1.0.0' });
const transport = new StreamableHTTPClientTransport(
new URL('http://127.0.0.1:3000/mcp')
);
try {
await client.connect(transport);
const { tools } = await client.listTools();
console.log(`tools: ${tools.map(tool => tool.name).join(',')}`);
const result = await client.callTool({
name: 'echo',
arguments: { text: 'hello' }
});
const text = result.content.find(item => item.type === 'text');
console.log(`echo: ${text?.text ?? '<missing>'}`);
} finally {
await transport.terminateSession();
await client.close();
}运行验证
npx tsx client.ts预期输出
tools: echo
echo: hello风险与边界
createMcpHandler 的工厂按请求创建实例。在实例字段中保存登录态、任务进度或业务缓存,会在后续请求中丢失;安全替代是把数据库连接池、缓存客户端和持久化状态放在模块级共享资源或外部存储中。
远程发布时,缺少 HTTPS、认证授权和 Origin 校验会让未授权客户端调用工具。不要简单把监听地址改成 0.0.0.0;应在网关或框架中完成令牌验证、来源校验、限流和审计,再把认证结果传给 MCP 处理器。
请求需要进度通知时,响应可能升级为请求级 SSE。若经 Nginx 后消息成批到达,检查代理缓冲和超时;不要通过旧式独立 GET SSE 端点修补,新规范使用单个 POST 端点。
排障清单
404 Not Found:确认客户端 URL 精确为http://127.0.0.1:3000/mcp。403 Forbidden:检查 Host/Origin 是否被代理改写,或改用框架提供的 MCP 应用工厂配置允许来源。- 工具调用参数错误:先看
tools/list返回的inputSchema,确保参数名为text且非空。 - 连接后状态丢失:把跨请求数据移出每请求创建的
McpServer实例。 - SSE 延迟:关闭反向代理响应缓冲,并提高流式请求读取超时。
兼容性提示:该写法针对 SDK v2 与 2026-07-28 规范。旧教程中的 StreamableHTTPServerTransport、GET 流和 Mcp-Session-Id 属于 v1 或旧协议实现,迁移时不要混用两套生命周期。
正确创建、传递、恢复和终止 Streamable HTTP 会话。
管理 Streamable HTTP 会话
Streamable HTTP 的“会话”必须先按协议版本区分:2026-07-28 现代协议已移除传输层会话;2025-03-26~2025-11-25 的旧版 Streamable HTTP 可能由服务端签发 Mcp-Session-Id。生产代码应让 SDK 管理会话头、恢复和终止,不要自行拼接或跨用户复用会话 ID。:contentReference[oaicite:0]{index=0}
会话边界
| 协议时代 | 创建与传递 | 终止与恢复 |
|---|---|---|
现代 2026-07-28 |
每个请求自描述,不创建 Mcp-Session-Id |
无传输会话可终止;业务状态应使用显式句柄参数 |
旧版 2025-03-26~2025-11-25 |
初始化响应可返回 Mcp-Session-Id,后续请求必须携带 |
客户端可发 HTTP DELETE 终止;无效或过期会话通常返回 404 |

推荐用法
前置条件是 MCP Server 已在 MCP_URL 指向的端点运行并支持基础 ping 请求。SDK v2 的 mode: 'auto' 会识别现代协议,并在面对仅支持旧协议的服务端时回退到旧版初始化流程。terminateSession() 在服务端未签发会话 ID 时不会发送终止请求,因此同一清理逻辑可覆盖两种时代。:contentReference[oaicite:1]{index=1}
import {
Client,
StreamableHTTPClientTransport
} from '@modelcontextprotocol/client';
const endpoint = new URL(
process.env.MCP_URL ?? 'http://127.0.0.1:3000/mcp'
);
const client = new Client(
{ name: 'session-check', version: '1.0.0' },
{ versionNegotiation: { mode: 'auto' } }
);
const transport = new StreamableHTTPClientTransport(endpoint);
await client.connect(transport);
try {
await client.ping();
console.log(`era=${client.getProtocolEra()}`);
console.log('ping=ok');
} finally {
// 旧版会话发送 DELETE;现代协议无会话时直接返回。
await transport.terminateSession();
await client.close();
console.log('closed');
}预期输出(连接现代服务端)
era=modern
ping=ok
closed连接旧版服务端时第一行是 era=legacy;其余输出相同。
恢复与失效处理
旧版会话出现 404 时,表示该 ID 已过期、被删除,或请求被负载均衡到没有该会话状态的实例。不要继续重试旧 ID;应丢弃原 Client 和 transport,重新创建并执行连接协商。现代协议没有隐藏的传输会话,跨调用状态应由工具返回显式句柄,再由后续调用作为参数传回。:contentReference[oaicite:2]{index=2}
网络短暂中断后,可以先让当前 transport 按 SDK 能力重连;一旦服务端明确返回会话不存在,就必须重新初始化。恢复连接只恢复协议通信,不等于恢复尚未持久化的业务事务。
风险与边界
- 旧版会话保存在单实例内存,而负载均衡未配置粘性路由时,后续请求可能落到其他实例并返回
404。安全替代是升级到现代无会话协议,或使用粘性路由、共享会话存储。 - 把
Mcp-Session-Id写入日志、缓存后跨用户复用,可能造成状态串用或信息泄露。安全替代是每个客户端连接独占 transport,并对会话头做日志脱敏。 - 请求仍在执行时调用
terminateSession()或close(),会中断在途请求。安全替代是在所有请求 settled 后,于finally中按“终止旧版会话,再关闭客户端”的顺序清理。
排障清单
400:确认旧版非初始化请求是否缺少会话 ID,并检查是否绕过了 SDK transport。404:确认会话是否过期、已被删除,或负载均衡是否破坏实例亲和性。405:现代服务端收到旧版GET或DELETE时可返回该状态;检查双方协商出的协议时代。- 会话持续增长:确认异常路径也执行
terminateSession()和client.close(),并为旧版服务端设置空闲过期策略。
速查:现代协议不管理传输会话;旧版会话交给 SDK,404 后重新连接,结束时先终止会话再关闭客户端。
创建客户端会话并通过指定传输方式连接 MCP Server。
初始化 MCP 客户端
初始化客户端的最短路径是:创建 Client、选择 transport、调用 connect(),再读取服务端能力后执行具体方法。远程服务通常使用 Streamable HTTP,本地子进程使用 stdio;不要把传输创建、协议协商和业务调用揉进同一个不可清理的全局对象。
初始化流程

Client 保存客户端名称和版本;transport 决定数据如何到达 Server;connect() 完成协议时代协商并建立可用连接。SDK v2 可通过 versionNegotiation.mode = 'auto' 同时兼容现代 2026-07-28 与旧版初始化握手,连接后可用 ping() 做不依赖工具清单的基础连通性验证。:contentReference[oaicite:3]{index=3}
HTTP 主示例
前置条件是已安装 @modelcontextprotocol/client,并且 MCP_URL 指向真实 MCP HTTP 端点。
import {
Client,
StreamableHTTPClientTransport
} from '@modelcontextprotocol/client';
const endpoint = new URL(
process.env.MCP_URL ?? 'http://127.0.0.1:3000/mcp'
);
const client = new Client(
{ name: 'ops-client', version: '1.0.0' },
{ versionNegotiation: { mode: 'auto' } }
);
const transport = new StreamableHTTPClientTransport(endpoint);
await client.connect(transport);
try {
await client.ping();
const server = client.getServerVersion();
console.log(`era=${client.getProtocolEra()}`);
console.log(
`server=${server?.name ?? 'unknown'}@${server?.version ?? 'unknown'}`
);
console.log('ping=ok');
} finally {
await transport.terminateSession();
await client.close();
}预期输出
era=modern
server=<SERVER_NAME>@<VERSION>
ping=ok<SERVER_NAME> 和 <VERSION> 由目标 Server 决定;旧版服务端第一行显示 era=legacy。
传输选择
| 场景 | transport | 关键输入 |
|---|---|---|
| 远程 HTTP 服务 | StreamableHTTPClientTransport |
完整 MCP 端点 URL、认证配置、超时策略 |
| 本地子进程 | StdioClientTransport |
可执行命令、参数、必要环境变量 |
| 同进程测试 | InMemoryTransport |
成对创建的客户端与服务端 transport |
stdio transport 在 SDK v2 中从 @modelcontextprotocol/client/stdio 导入;HTTP transport 从 @modelcontextprotocol/client 导入。一个 Client 对应一个 Server 连接,不要把同一个实例同时连接到多个 transport。:contentReference[oaicite:4]{index=4}
连接后检查
connect() 成功后再读取 getProtocolEra()、getServerVersion()、getServerCapabilities() 和 getInstructions()。能力未声明时不要直接调用对应方法;例如调用工具前先确认 tools 能力,再执行 listTools()。
生产代码应把连接和关闭放在同一生命周期内。命令行程序适合 try/finally;常驻服务应在进程退出、租户切换或凭证撤销时关闭旧客户端,并为每个授权主体隔离认证上下文。
排障清单
ECONNREFUSED:检查主机、端口、容器网络和 Server 是否监听;URL 路径常见值是/mcp,但必须以实际部署为准。401或403:先处理 OAuth、令牌或 scope;认证失败不是“旧协议证据”,不要盲目回退。- 协商失败:
auto模式可兼容两种时代;若使用版本 pin,目标 Server 不支持该版本时会直接失败。 - 已连接但方法报错:检查服务端能力声明、工具名和输入 schema,不要把业务错误误判为 transport 故障。
- 进程不退出:确认
finally中调用client.close();stdio 客户端未关闭时,子进程可能继续存活。
兼容性
SDK v2 使用拆分包 @modelcontextprotocol/client;v1 常见导入路径属于 @modelcontextprotocol/sdk/client/...。同一项目不要混用两套类型和 transport。需要兼容只支持旧 HTTP+SSE 的服务端时,先尝试 Streamable HTTP,再用全新的 Client 实例显式回退 SSEClientTransport;新项目不应优先采用已弃用的 HTTP+SSE。:contentReference[oaicite:5]{index=5}
速查:先选 transport,再 connect();连接成功后读取协商结果与能力,业务结束后始终关闭客户端。
读取服务端声明的工具、资源、提示和其他可用能力。
发现服务端能力
用于客户端首次连接、展示能力面板或排查“方法不存在”时,先确认服务端支持的协议版本和能力,再按声明读取工具、资源、资源模板与提示列表。以下按 MCP 2026-07-28 编写。
命令定位
server/discover 一次返回服务端支持的版本、能力、身份和使用说明;发现某项能力后,再调用对应列表方法获取可用对象。不要把“存在 tools 能力”理解为“工具列表一定非空”。
| 目标 | JSON-RPC 方法 | 主要读取字段 |
|---|---|---|
| 服务端概况 | server/discover |
supportedVersions、capabilities、instructions、服务端信息 |
| 工具 | tools/list |
tools[].name、description、inputSchema、outputSchema |
| 资源 | resources/list |
resources[].uri、name、mimeType |
| 资源模板 | resources/templates/list |
resourceTemplates[].uriTemplate |
| 提示 | prompts/list |
prompts[].name、arguments |

高频用法
前置条件:目标服务已在 http://127.0.0.1:3000/mcp 提供 Streamable HTTP;本机安装 curl 和 jq。脚本为每个请求携带协议版本、客户端身份与客户端能力。
#!/usr/bin/env bash
set -euo pipefail
MCP_URL="${MCP_URL:-http://127.0.0.1:3000/mcp}"
rpc() {
local method="$1"
local id="$2"
local body
# 2026-07-28 为无状态协议,每次请求都要携带完整 _meta。
body="$(jq -cn --arg method "$method" --arg id "$id" '{
jsonrpc: "2.0",
id: $id,
method: $method,
params: {
_meta: {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientInfo": {
name: "capability-probe",
version: "1.0.0"
},
"io.modelcontextprotocol/clientCapabilities": {}
}
}
}')"
curl -sS "$MCP_URL" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'MCP-Protocol-Version: 2026-07-28' \
-H "Mcp-Method: $method" \
--data "$body"
printf '\n'
}
rpc server/discover discover-1
rpc tools/list tools-1
rpc resources/list resources-1
rpc resources/templates/list templates-1
rpc prompts/list prompts-1预期输出
{"jsonrpc":"2.0","id":"discover-1","result":{"resultType":"complete","supportedVersions":["2026-07-28"],"capabilities":{"tools":{},"resources":{},"prompts":{}},"_meta":{"io.modelcontextprotocol/serverInfo":{"name":"<SERVER_NAME>","version":"<VERSION>"}}}}
{"jsonrpc":"2.0","id":"tools-1","result":{"resultType":"complete","tools":[{"name":"<TOOL_NAME>","description":"<DESCRIPTION>","inputSchema":{"type":"object"}}]}}
{"jsonrpc":"2.0","id":"resources-1","result":{"resultType":"complete","resources":[{"uri":"<RESOURCE_URI>","name":"<RESOURCE_NAME>"}]}}
{"jsonrpc":"2.0","id":"templates-1","result":{"resultType":"complete","resourceTemplates":[]}}
{"jsonrpc":"2.0","id":"prompts-1","result":{"resultType":"complete","prompts":[{"name":"<PROMPT_NAME>"}]}}<SERVER_NAME>、对象名称和数量由服务端决定。若 HTTP 响应类型为 text/event-stream,输出会带 SSE 事件行,应使用 MCP SDK 或 SSE 解析器读取 JSON-RPC 消息,不能直接整段交给 jq。
输出字段说明
capabilities 只表示服务端声明支持某类协议方法;具体对象以相应 */list 结果为准。列表中的 nextCursor 是不透明游标,存在时将其放入下一次请求的 params.cursor,直到不再返回。ttlMs 与 cacheScope 可用于决定缓存时长和共享范围。
工具的 inputSchema 是调用参数约束;资源以 uri 唯一定位;提示的 arguments 描述可传入的模板参数。客户端应保留未知字段,避免协议扩展后因严格丢字段导致兼容问题。
风险与边界
服务端身份和描述均为自声明信息,不能作为授权或信任依据。发现结果可能因调用者凭证不同而变化;必须使用与后续调用相同的认证上下文进行探测。
不要无限跟随 nextCursor。游标重复、页数异常或列表持续增长时应设置最大页数并记录告警,安全替代方案是中止本轮发现并保留上一份已验证缓存。
兼容性
2026-07-28 使用无状态请求和 server/discover,不再依赖 initialize 会话。连接 2025-11-25 及更早服务端时,需要走旧版初始化握手;双版本 stdio 客户端可先发送 server/discover,收到 JSON-RPC -32601 后再回退旧流程。
从客户端传递参数、调用指定工具并解析返回结果。
调用工具
用于客户端已经从 tools/list 获得工具定义后,校验参数、发送 tools/call 并区分成功、工具执行失败、协议错误和补充输入流程。以下按 MCP 2026-07-28 编写。
基本语法
请求方法固定为 tools/call,params.name 必须与工具名逐字一致,params.arguments 必须满足该工具的 inputSchema。Streamable HTTP 还要发送与正文一致的 MCP-Protocol-Version、Mcp-Method 和 Mcp-Name 请求头。
{
"jsonrpc": "2.0",
"id": "tool-1",
"method": "tools/call",
"params": {
"name": "get_weather",
"arguments": {
"location": "Shanghai"
},
"_meta": {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientInfo": {
"name": "tool-runner",
"version": "1.0.0"
},
"io.modelcontextprotocol/clientCapabilities": {}
}
}
}该请求会调用名为 get_weather 的工具。验证方法是检查响应的 JSON-RPC id 是否仍为 tool-1,再根据 result.resultType 或顶层 error 分流。

高频用法
前置条件:示例服务已提供 get_weather 工具,且其 inputSchema 接受字符串字段 location。脚本先构造请求,再保留原始响应供排障。
#!/usr/bin/env bash
set -euo pipefail
MCP_URL="${MCP_URL:-http://127.0.0.1:3000/mcp}"
MCP_TOOL="${MCP_TOOL:-get_weather}"
MCP_ARGS="${MCP_ARGS:-{"location":"Shanghai"}}"
# --argjson 会在发送前校验 MCP_ARGS 是否为合法 JSON。
BODY="$(jq -cn \
--arg name "$MCP_TOOL" \
--argjson arguments "$MCP_ARGS" '{
jsonrpc: "2.0",
id: "tool-1",
method: "tools/call",
params: {
name: $name,
arguments: $arguments,
_meta: {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientInfo": {
name: "tool-runner",
version: "1.0.0"
},
"io.modelcontextprotocol/clientCapabilities": {}
}
}
}')"
curl -sS "$MCP_URL" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'MCP-Protocol-Version: 2026-07-28' \
-H 'Mcp-Method: tools/call' \
-H "Mcp-Name: $MCP_TOOL" \
--data "$BODY"
printf '\n'预期输出
{
"jsonrpc": "2.0",
"id": "tool-1",
"result": {
"resultType": "complete",
"content": [
{
"type": "text",
"text": "Shanghai: 28°C, cloudy"
}
],
"structuredContent": {
"temperature": 28,
"conditions": "cloudy"
},
"isError": false
}
}示例输出对应一个同时返回文本和结构化结果的实现;实际字段取决于工具定义。若响应是 SSE,必须逐事件解析后再读取 JSON-RPC 对象。
输出字段说明
resultType: complete 表示本轮调用结束。content 可包含文本、图片、音频、资源链接或嵌入资源;structuredContent 应在工具声明 outputSchema 时按该模式校验。isError: true 表示工具代码已经运行但业务执行失败,不等同于顶层 JSON-RPC error。
resultType: input_required 表示服务端需要额外输入。客户端应展示 inputRequests,收集用户选择后,用新的 JSON-RPC id 重发原方法,并原样携带 requestState 与对应的 inputResponses。
风险与边界
删除、发布、付款或写数据库等有副作用工具,触发条件是调用可能改变外部状态;后果是误操作或重复执行。安全替代方案是调用前展示工具名和关键参数、要求人工确认,并只对明确幂等的调用自动重试。
不要只信任工具描述或注解。客户端应按 inputSchema 校验参数、按 outputSchema 校验结构化结果,并限制响应大小。若参数在 schema 中标记了 x-mcp-header,HTTP 客户端必须同步镜像该值;密码、令牌和个人信息不应使用此标记,因为请求头可能被网关和日志系统看到。
网络超时不代表服务端没有执行。对非幂等工具应先查询执行状态或使用业务幂等键,而不是立即重放相同请求。
排障清单
- HTTP
400且提示头不一致:核对MCP-Protocol-Version、Mcp-Method、Mcp-Name与正文对应字段。 - JSON-RPC
-32601:工具调用方法或协议版本不受支持,先重新发现版本与能力。 - 顶层
error:按协议错误处理;result.isError=true:读取content中的工具错误信息。 - 参数被拒绝:重新读取最新
tools/list,按当前inputSchema修正类型、必填项和附加字段。
兼容性
2026-07-28 每次调用都携带 _meta,HTTP 不使用 Mcp-Session-Id。旧版服务端通常先执行 initialize,返回结构也可能没有 resultType;客户端应按协商出的协议版本选择解析器,不能混用两套请求格式。
从客户端按 URI 获取资源内容及其媒体类型信息。
读取资源
已知资源 URI,需要从 MCP 服务端取得正文、二进制数据及媒体类型时使用 resources/read。URI 不确定时先调用 resources/list,不要猜测服务端路径。
基本语法
下面示例面向 MCP 2026-07-28 的 Streamable HTTP 端点。将 <PORT> 替换为实际端口;服务端可能选择返回 JSON,也可能返回请求级 SSE 流。
export MCP_URL='http://127.0.0.1:<PORT>/mcp'
curl -sS "$MCP_URL" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'MCP-Protocol-Version: 2026-07-28' \
-H 'Mcp-Method: resources/read' \
-H 'Mcp-Name: file:///project/README.md' \
--data-binary @- <<'JSON'
{"jsonrpc":"2.0","id":"read-1","method":"resources/read","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"ops-client","version":"1.0.0"},"io.modelcontextprotocol/clientCapabilities":{}},"uri":"file:///project/README.md"}}
JSON预期输出
{"jsonrpc":"2.0","id":"read-1","result":{"resultType":"complete","contents":[{"uri":"file:///project/README.md","mimeType":"text/markdown","text":"# Project\n..."}],"ttlMs":60000,"cacheScope":"private"}}读取时先确认 id 与请求一致,再遍历 result.contents。实际正文、缓存时长和 URI 可能不同;若响应为 SSE,最终 JSON-RPC 响应通常出现在 data: 行中。
常用参数
params.uri:要读取的唯一资源标识,可使用file://、https://、git://或服务端自定义方案。params._meta:2026-07-28 请求必填,至少包含协议版本和客户端能力;HTTP 头中的版本必须与正文一致。Mcp-Method:必须为resources/read。Mcp-Name:必须与正文中的params.uri完全一致;URI 含非 ASCII、控制字符或首尾空格时,客户端应按协议使用 Base64 哨兵格式编码。
高频用法
读取文本资源时使用 contents[].text,并按 mimeType 选择 Markdown、JSON 或纯文本解析器。读取图片、压缩包等二进制资源时使用 contents[].blob,其值是 Base64 数据,解码前应检查类型和大小限制。
一次读取可能返回多个 contents,例如目录资源展开为多个文件;不要只取第一项。需要重复读取时参考 ttlMs,并严格遵守 cacheScope:private 结果只能在同一授权上下文复用,public 才可跨授权上下文共享缓存。
输出字段说明
| 字段 | 读取方式 |
|---|---|
resultType |
complete 表示结果已完成;input_required 表示服务端还需要客户端补充输入 |
contents |
资源内容数组,每项至少包含 uri,并使用 text 或 blob 承载数据 |
mimeType |
决定解析、展示或保存方式,缺失时不要仅凭扩展名执行文件 |
ttlMs |
结果保持新鲜的毫秒数,0 表示应视为立即过期 |
cacheScope |
private 按授权上下文隔离,public 才允许共享缓存 |
风险与边界
当服务端把 file:// URI 直接映射到本地文件系统时,未规范化路径可能触发目录穿越,后果是读取密钥、配置或用户文件。安全做法是服务端先规范化路径、限制允许根目录、校验授权,并拒绝越界 URI;客户端也不要把模型生成的 URI 无条件提交。
二进制资源可能体积很大或伪造 mimeType,直接解码会造成内存压力或危险文件落盘。应先限制响应大小、校验实际格式,并把未知类型保存到隔离目录而不是自动打开。
排障清单
- 返回
-32602:检查 URI 是否存在、格式是否合法、当前凭证是否有权访问;旧版服务端也可能返回-32002。 - HTTP
400且错误码为-32020:核对MCP-Protocol-Version、Mcp-Method、Mcp-Name与请求正文是否逐字一致。 - HTTP
404且错误码为-32601:服务端未实现resources/read,先检查发现结果中的resources能力。 contents为空:不要当作“资源不存在”;规范实现应对不存在的资源返回错误。- 收到
input_required:保留服务端给出的requestState,补充inputResponses后重试原请求。
兼容性
2026-07-28 使用逐请求元数据,不再依赖 initialize、Mcp-Session-Id 或独立 GET SSE 流。连接旧版服务端时优先交给对应版本的 MCP SDK 处理;旧响应没有 resultType 时,兼容客户端应按 complete 处理。
传入提示参数并获取服务端生成的消息序列。
获取提示消息
已知提示名称,需要把参数交给服务端并取得可直接交给模型的消息序列时使用 prompts/get。它只解析提示模板,不代表已经执行模型推理。
基本语法
下面示例获取名为 code_review 的提示。参数值必须是字符串;将 <PORT> 替换为实际端口。
export MCP_URL='http://127.0.0.1:<PORT>/mcp'
curl -sS "$MCP_URL" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'MCP-Protocol-Version: 2026-07-28' \
-H 'Mcp-Method: prompts/get' \
-H 'Mcp-Name: code_review' \
--data-binary @- <<'JSON'
{"jsonrpc":"2.0","id":"prompt-1","method":"prompts/get","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"ops-client","version":"1.0.0"},"io.modelcontextprotocol/clientCapabilities":{}},"name":"code_review","arguments":{"language":"python","code":"print('hello')"}}}
JSON预期输出
{"jsonrpc":"2.0","id":"prompt-1","result":{"resultType":"complete","description":"Code review prompt","messages":[{"role":"user","content":{"type":"text","text":"Review this python code:\nprint('hello')"}}]}}读取时按数组顺序保留 messages,不要合并或重排角色。实际描述和生成文本由服务端模板决定;若返回 SSE,最终 JSON-RPC 响应通常位于 data: 行。
常用参数
params.name:提示模板的唯一名称。名称不确定时先调用prompts/list。params.arguments:可选字符串键值表,键名必须与提示定义一致;缺少必填参数通常返回-32602。params._meta:2026-07-28 请求必填,声明协议版本和本次请求的客户端能力。inputResponses、requestState:仅在服务端返回input_required后用于下一轮重试。Mcp-Method与Mcp-Name:HTTP 传输中分别镜像方法名和提示名,必须与正文一致。
高频用法
先用 prompts/list 读取提示名、参数说明和 required 标记,再构造 arguments,可避免把显示标题误当作 name。对用户填写的长代码、查询条件或文档内容,应在提交前检查长度并明确是否允许发送到远端服务。
返回的 messages 可以包含多条 user 或 assistant 消息。content.type 不只可能是 text,还可能是 image、audio、resource_link 或嵌入式 resource;客户端应按类型分派,不能默认所有内容都有 text 字段。
输出字段说明
| 字段 | 读取方式 |
|---|---|
resultType |
complete 表示提示已解析;input_required 表示还需补充输入 |
description |
可选的人类可读说明,不应当作模型消息发送 |
messages |
按顺序发送给模型的消息数组 |
messages[].role |
取值为 user 或 assistant,决定消息角色 |
messages[].content |
单个内容块,按 type 读取文本、多媒体或资源信息 |
风险与边界
提示参数可能包含代码、日志、个人信息或密钥。触发条件是客户端把用户原文直接发送给不受信任或跨租户的 MCP 服务端,后果是敏感数据泄露。安全替代方案是先做脱敏和授权确认,只连接经过验证的服务端,并按租户隔离凭证、日志和缓存。
服务端返回的提示文本属于不可信输入,可能夹带提示注入或要求模型调用高风险工具。不要因为内容来自 MCP 提示就自动提升权限;应继续执行本地系统指令、工具白名单和用户确认策略。
排障清单
- 返回
-32602:检查name是否来自当前prompts/list,以及所有必填参数是否存在且值为字符串。 - 返回
-32603:服务端模板渲染或后端依赖异常,结合请求id查服务端日志,不要盲目重复高频重试。 - HTTP
400且错误码为-32020:核对协议版本、Mcp-Method、Mcp-Name与正文是否完全一致。 messages中没有text:先检查content.type,它可能是资源链接、嵌入资源、图片或音频。- 收到
input_required:展示服务端请求的输入,取得用户同意后用inputResponses和原requestState重试。
兼容性
2026-07-28 要求每个请求携带 _meta,Streamable HTTP 还要求对应的版本、方法和名称请求头。旧版 2025 客户端通常依赖初始化会话,不能直接照搬本示例;应使用与服务端协议版本匹配的 SDK。旧响应缺少 resultType 时,兼容客户端应按 complete 处理。
使用游标连续读取数量较多的工具、资源或提示列表。
处理分页结果
当 tools/list、resources/list、resources/templates/list 或 prompts/list 返回数量较多时,持续读取 nextCursor,直到响应不再提供游标。客户端只负责原样回传游标,不能推测页码、偏移量或固定页大小。
基本语法
首次请求不传 cursor;响应存在 nextCursor 时,把它放入下一次同方法请求的 params.cursor。在 MCP 2026-07-28 中,每个请求还应携带协议版本和本次请求的客户端能力。
{
"jsonrpc": "2.0",
"id": "list-1",
"method": "tools/list",
"params": {
"_meta": {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientInfo": {
"name": "ops-client",
"version": "1.0.0"
},
"io.modelcontextprotocol/clientCapabilities": {}
}
}
}预期结果:若仍有数据,响应包含当前页 tools 和 nextCursor。
{
"jsonrpc": "2.0",
"id": "list-1",
"result": {
"resultType": "complete",
"tools": [
{
"name": "search",
"description": "Search documents",
"inputSchema": {
"type": "object"
}
}
],
"nextCursor": "eyJvZmZzZXQiOjF9",
"ttlMs": 300000,
"cacheScope": "private"
}
}
高频用法
下面的 Node.js 示例可直接运行,演示正确的停止条件。实际接入时只需把 callMcp 替换成 SDK 或传输层的请求函数。
const pages = new Map([
["FIRST", { tools: [{ name: "search" }], nextCursor: "" }],
["", { tools: [{ name: "fetch" }], nextCursor: "page-3" }],
["page-3", { tools: [{ name: "store" }] }]
]);
async function callMcp(_method, params) {
const key = Object.hasOwn(params, "cursor") ? params.cursor : "FIRST";
return pages.get(key);
}
async function listAll(method, field) {
const items = [];
let cursor;
do {
const params = cursor === undefined ? {} : { cursor };
const result = await callMcp(method, params);
items.push(...result[field]);
cursor = result.nextCursor;
// 空字符串是合法游标;只有 null 或字段缺失才表示结束。
} while (cursor !== undefined && cursor !== null);
return items;
}
const tools = await listAll("tools/list", "tools");
console.log(tools.map((item) => item.name).join(", "));预期输出
search, fetch, store同一循环可用于 resources/list、resources/templates/list 和 prompts/list,只需替换方法名以及响应数组字段。不要并发请求同一游标链的后续页,因为后一页游标通常依赖前一页响应。
输出字段说明
nextCursor:不透明续读令牌;字段缺失或值为null表示结束,空字符串仍应继续。ttlMs:响应建议缓存时长,单位为毫秒;过期后重新从第一页获取,不复用旧游标。cacheScope:缓存范围提示;private数据不能跨用户或凭据共享。- 列表字段:按方法分别读取
tools、resources、resourceTemplates或prompts。
风险与边界
把游标当页码解析、拼接或递增,可能造成重复、漏项或 -32602 Invalid params。安全做法是原样保存并回传;若游标过期,清空已缓存游标并从第一页重试。
服务端列表在遍历期间发生变化时,跨页结果可能重复或缺失。需要强一致快照时,应由服务端提供稳定游标或版本标识;客户端至少按唯一键去重,并设置最大页数、最大条目数和总超时,避免异常服务端造成无限循环。
排障清单
- 第一页有数据但后续未读取:检查是否遗漏
nextCursor。 - 空游标被当作结束:不要写
while (cursor),应显式判断null和字段缺失。 - 重复请求同一页:确认更新的是本次响应的
nextCursor,并记录方法名、请求 ID 和游标摘要。 - 返回
-32602:游标可能无效、过期或属于另一用户会话;从第一页重新获取。 - 数量异常:核对数组字段名,并检查是否错误复用了其他方法的游标。
由客户端向服务端声明允许访问的文件系统根目录。
提供 Roots
Roots 用于让 MCP 客户端告诉服务端“当前相关的文件或目录有哪些”。它只是工作范围提示,不是文件系统沙箱;客户端仍要控制实际权限,服务端也必须对每个路径做边界校验。
基本语法
在 MCP 2026-07-28 中,客户端在每次请求的 _meta.io.modelcontextprotocol/clientCapabilities 中声明 roots。服务端需要根目录时,通过 input_required 返回 roots/list 输入请求,客户端取得用户授权后,用相同键把根列表放入重试请求的 inputResponses。
{
"jsonrpc": "2.0",
"id": "call-1",
"method": "tools/call",
"params": {
"_meta": {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientInfo": {
"name": "workspace-client",
"version": "1.0.0"
},
"io.modelcontextprotocol/clientCapabilities": {
"roots": {}
}
},
"name": "scan_project",
"arguments": {}
}
}预期结果:服务端需要工作目录时,先返回待处理的 roots/list 请求和可回传的 requestState。
{
"jsonrpc": "2.0",
"id": "call-1",
"result": {
"resultType": "input_required",
"inputRequests": {
"workspace_roots": {
"method": "roots/list"
}
},
"requestState": "<ID>"
}
}客户端重试原调用,并返回已授权的根目录。inputResponses 的键必须与 inputRequests 完全一致。
{
"jsonrpc": "2.0",
"id": "call-2",
"method": "tools/call",
"params": {
"_meta": {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientInfo": {
"name": "workspace-client",
"version": "1.0.0"
},
"io.modelcontextprotocol/clientCapabilities": {
"roots": {}
}
},
"name": "scan_project",
"arguments": {},
"requestState": "<ID>",
"inputResponses": {
"workspace_roots": {
"roots": [
{
"uri": "file:///home/user/projects/payhub",
"name": "PayHub"
}
]
}
}
}
}预期结果:服务端只以返回的 file:// URI 作为候选工作范围,并继续执行原工具调用;实际路径、请求 ID 和状态令牌会不同。

字段说明
roots能力:表示客户端能够回答根目录请求;未声明时,服务端不得假定该能力存在。uri:根目录或文件的唯一标识,Roots 当前只接受规范化的file://URI。name:可选显示名,不能替代uri做权限判断。requestState:服务端生成的不透明续办状态;客户端应原样回传,不解析、不修改。inputRequests与inputResponses:键一一对应,用于关联服务端提出的输入请求和客户端结果。
风险与边界
把 Roots 当成强制沙箱会产生越权风险:恶意或有缺陷的服务端仍可能尝试访问根目录之外。安全替代方案是在客户端进程、容器、操作系统账户或文件代理层实施真实权限隔离,并在每次读写前将规范化目标路径与允许根目录比较。
直接接受用户输入的 file:// URI 可能触发路径穿越、符号链接逃逸或大小写绕过。应先解析 URI、拒绝非本地文件方案、解析真实路径,再检查它是否位于授权根目录内;写操作还应单独确认,不能因目录已列为 Root 就默认允许修改。
排障清单
- 服务端未请求 Roots:检查本次请求的客户端能力中是否包含
roots。 - 重试后仍返回
input_required:确认已回传原始requestState,且inputResponses键与服务端键一致。 - URI 无法读取:检查是否使用绝对
file://URI、路径是否存在,以及运行 MCP 客户端的账户权限。 - Windows 路径异常:使用
file:///C:/work/project,不要直接传C:\work\project。 - 根目录更新后仍使用旧值:清理服务端缓存;旧版协议还需处理
notifications/roots/list_changed。
兼容性
Roots 从 MCP 2026-07-28 起已弃用,但在弃用窗口内仍保留兼容能力。新实现优先把目录作为工具参数、资源 URI 或服务端配置显式传递;维护旧客户端时,2025-11-25 及更早版本使用初始化能力协商,并由服务端直接发送 roots/list JSON-RPC 请求,不能与新版本的 input_required 流程混用。
让服务端通过客户端发起受控的模型生成请求。
请求模型采样
用于维护已有 MCP Sampling 集成:服务端在处理 prompts/get、resources/read 或 tools/call 时,请客户端代为调用模型,并由客户端控制模型选择、权限与用户审批。按 2026-07-28 规范,Sampling 已弃用;新系统应优先直接集成模型提供商 API。
命令定位
方法名是 sampling/createMessage。在现代协议中,服务端不能主动发送独立 JSON-RPC 请求,而要返回 resultType: "input_required",把采样请求放入 result.inputRequests.<requestKey>;客户端完成采样后,用新的请求 ID 重试原请求,并在 params.inputResponses 中返回同名结果。

基本语法
下面是 tools/call 处理中请求客户端生成一句诊断摘要的协议报文示例。<STATE>、<MODEL> 是动态值。服务端首次返回:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"resultType": "input_required",
"inputRequests": {
"model_summary": {
"method": "sampling/createMessage",
"params": {
"messages": [
{
"role": "user",
"content": {
"type": "text",
"text": "请将以下诊断结果压缩为一句话:数据库连接池已耗尽"
}
}
],
"systemPrompt": "只输出结论,不扩展建议。",
"temperature": 0.1,
"maxTokens": 80
}
}
},
"requestState": "<STATE>"
}
}客户端完成采样后,以新 ID 重试原请求:
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"_meta": {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientInfo": {
"name": "ExampleClient",
"version": "1.0.0"
},
"io.modelcontextprotocol/clientCapabilities": {
"sampling": {}
}
},
"name": "diagnose_service",
"arguments": {
"service": "orders"
},
"inputResponses": {
"model_summary": {
"role": "assistant",
"content": {
"type": "text",
"text": "订单服务异常由数据库连接池耗尽引起。"
},
"model": "<MODEL>",
"stopReason": "endTurn"
}
},
"requestState": "<STATE>"
}
}预期结果:
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"resultType": "complete",
"content": [
{
"type": "text",
"text": "订单服务异常由数据库连接池耗尽引起。"
}
],
"isError": false
}
}读取方法:inputResponses.model_summary 必须对应首次 inputRequests.model_summary;重试 ID 必须不同;requestState 必须逐字回传。最终结果出现 resultType: "complete" 才表示原请求结束。
常用参数
| 参数 | 用法 |
|---|---|
messages |
必填,按 user、assistant 角色提供上下文;内容可为文本及客户端支持的其他块。 |
systemPrompt |
可选,约束任务边界;客户端可以修改或忽略。 |
modelPreferences |
可选,提供模型名称提示及成本、速度、智能优先级;只是建议,不保证命中。 |
temperature |
可选,低值适合分类、摘要和结构化生成。 |
maxTokens |
必填,限制最大生成量;客户端可以实际生成更少。 |
includeContext: "thisServer" 与 "allServers" 已弃用,除非客户端明确声明 sampling.context,否则不要使用。需要工具调用时还必须检查客户端是否声明 sampling.tools。
输出字段说明
role 通常为 assistant;content 是模型生成内容;model 是客户端实际选择的模型;stopReason 常见值为 endTurn、stopSequence、maxTokens 或 toolUse。不要把模型提示名称当成最终模型标识。
风险与边界
- 未经审核直接采样会让提示词、资源内容或业务数据进入客户端模型。后果可能是敏感信息泄露;安全替代方案是最小化上下文、展示待发送内容并允许用户拒绝或编辑。
- 未限制
maxTokens、重试次数或工具循环会增加费用并造成长时间占用。应设置令牌上限、超时、总轮次和取消路径。 requestState经客户端回传,可能被篡改或重放。只要它影响权限、资源或业务结果,就应使用 HMAC 或 AEAD 保护完整性,并绑定用户、原请求摘要和短 TTL。- Sampling 在
2026-07-28已弃用。新实现继续采用会增加迁移成本;安全替代方案是由服务端直接调用模型提供商 API,并自行实施密钥隔离、审批和审计。
兼容性
2026-07-28 使用 MRTR:服务端返回 InputRequiredResult,客户端再重试原请求。2025-11-25 及更早版本采用连接内的服务端主动请求,报文方向不同。双版本实现必须按每次请求携带的协议版本分支处理,不能把两种流程混用。
使用 Elicitation 在任务执行过程中安全地补充用户信息或确认。
请求用户输入
使用 Elicitation 在工具或资源处理过程中补充缺失字段、选择方案或确认高风险操作。普通结构化信息使用 form 模式;密码、API Key、访问令牌、支付凭据和第三方授权必须改用 url 模式,让敏感数据在 MCP 客户端之外完成。
命令定位
方法名是 elicitation/create。在 2026-07-28 协议中,它必须放在服务端返回的 InputRequiredResult.inputRequests 中,且只能嵌套于 prompts/get、resources/read 或 tools/call 的处理中。客户端每次请求都要在 _meta.io.modelcontextprotocol/clientCapabilities.elicitation 声明支持的 form、url 模式。

基本语法
下面的协议报文示例在删除临时文件前请求用户确认。requestedSchema 只收集一个布尔值,客户端可直接渲染为确认控件。服务端首次返回:
{
"jsonrpc": "2.0",
"id": 10,
"result": {
"resultType": "input_required",
"inputRequests": {
"confirm_delete": {
"method": "elicitation/create",
"params": {
"mode": "form",
"message": "是否删除 3 个临时文件?此操作不可撤销。",
"requestedSchema": {
"type": "object",
"properties": {
"confirmed": {
"type": "boolean",
"title": "确认删除",
"default": false
}
},
"required": [
"confirmed"
]
}
}
}
},
"requestState": "<STATE>"
}
}用户确认后,客户端以新 ID 重试原请求:
{
"jsonrpc": "2.0",
"id": 11,
"method": "tools/call",
"params": {
"_meta": {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientInfo": {
"name": "ExampleClient",
"version": "1.0.0"
},
"io.modelcontextprotocol/clientCapabilities": {
"elicitation": {
"form": {},
"url": {}
}
}
},
"name": "cleanup_temp_files",
"arguments": {
"scope": "session"
},
"inputResponses": {
"confirm_delete": {
"action": "accept",
"content": {
"confirmed": true
}
}
},
"requestState": "<STATE>"
}
}预期结果:
{
"jsonrpc": "2.0",
"id": 11,
"result": {
"resultType": "complete",
"content": [
{
"type": "text",
"text": "已删除 3 个临时文件。"
}
],
"isError": false
}
}读取方法:只有 action: "accept" 且 content.confirmed 为 true 时才执行删除;decline 和 cancel 都应走无副作用退出路径。重试时必须保持 inputResponses 键名与首次 inputRequests 键名一致。
高频用法
- 补全非敏感字段:项目名、日期、数量、邮箱、枚举选项等使用
form,并用requestedSchema限制类型和范围。 - 确认高风险操作:删除、覆盖、发布或付费前请求布尔确认;服务端仍需再次校验权限和当前状态。
- 处理敏感交互:密码、密钥、支付和第三方授权使用
url,客户端只负责展示目标地址并征得跳转同意,不接收敏感结果。
表单 Schema 应保持扁平对象,属性使用字符串、数字、整数、布尔值或受限枚举;不要发送嵌套对象、对象数组或依赖复杂条件的表单。
输出字段说明
action 有三种结果:accept 表示用户提交或同意,decline 表示明确拒绝,cancel 表示中止交互。form 模式的 accept 通常带有匹配 Schema 的 content;url 模式不返回敏感内容,且 accept 只代表同意打开外部流程,不代表外部操作已经完成。
风险与边界
- 用
form请求密码、API Key、令牌或支付凭据会让秘密经过 MCP 客户端,造成泄露风险。必须改用url模式,并让用户确认目标域名。 - 只依赖客户端校验可能被恶意客户端绕过,导致越权或脏数据。客户端用于改善体验,服务端必须重新校验 Schema、权限、资源状态和业务约束。
- 把用户输入、外部 URL 或完整表单写入日志可能泄露个人信息。应只记录请求键、动作、校验结果和脱敏字段。
requestState可被篡改或重放。影响授权或业务结果时,使用 HMAC 或 AEAD,并绑定用户、原请求和短 TTL;一次性操作还要在服务端记录已消费状态。
排障清单
- 没有弹出输入界面:检查客户端是否在本次请求的能力中声明对应
elicitation.form或elicitation.url。 - 服务端反复返回
input_required:检查重试是否携带同名inputResponses,以及requestState是否原样回传。 - 用户已提交但业务未执行:区分
accept、decline、cancel,并验证content是否满足 Schema 和业务条件。 - URL 流程一直未完成:
accept仅表示同意跳转;服务端需根据自己的外部状态判断完成度,未完成时可再次返回input_required。 - 重试被拒绝:现代 MRTR 的重试必须使用新的 JSON-RPC ID,且请求方法和关键参数应与原请求匹配。
兼容性
2026-07-28 使用 MRTR,不再由服务端在连接上直接推送 elicitation/create。旧版 URL 模式中的 elicitationId 与 notifications/elicitation/complete 已移除,相关关联信息应放入受保护的 requestState 或服务端状态。为兼容旧客户端,空的 elicitation 能力对象只等价于支持 form,不能据此发送 url 请求。
为基于 HTTP 的 MCP 服务实现符合规范的 OAuth 授权流程。
配置远程 MCP 服务鉴权
用于保护基于 HTTP 的远程 MCP 服务。完成后,未携带凭据的请求收到 401 与资源元数据地址;客户端完成 OAuth 授权后,以 Bearer Token 调用,服务端校验签发方、受众、有效期和权限范围。
流程定位
远程 MCP 服务是 OAuth 资源服务器,MCP 客户端是 OAuth 客户端,授权服务器负责登录、同意和签发令牌。交互式用户场景使用授权码流程并启用 PKCE;无人值守的服务间调用应使用双方明确支持的客户端凭据扩展,不要伪装成交互式用户。

服务端配置要点
资源服务器必须发布受保护资源元数据,至少声明自身规范化资源 URI 和授权服务器。无令牌或令牌失效时返回 401;权限不足时返回 403,并在挑战中给出当前操作需要的 scope。
{
"resource": "https://mcp.example.com/mcp",
"authorization_servers": [
"https://auth.example.com"
],
"scopes_supported": [
"mcp:tools",
"mcp:resources"
]
}将该文档发布到 RFC 9728 规定的 /.well-known/oauth-protected-resource 路径;若一个主机承载多个 MCP 资源,路径映射必须与实际 resource 保持一致。授权服务器还应发布 OAuth 授权服务器元数据或 OIDC Discovery 文档。
未授权响应示例:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="mcp", resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource", scope="mcp:tools"客户端在授权请求和令牌请求中都应发送 resource=https://mcp.example.com/mcp。服务端只接受受众与该规范化 URI 匹配的令牌,并通过本地验签或令牌内省验证 iss、aud、exp、scope 和撤销状态。
验证配置
替换示例域名后执行。第一条检查挑战头,第二条检查资源元数据是否可发现且字段一致。
MCP_URL="https://mcp.example.com/mcp"
PRM_URL="https://mcp.example.com/.well-known/oauth-protected-resource"
curl -sS -D - -o /dev/null "$MCP_URL"
curl -sS "$PRM_URL" | python3 -m json.tool预期输出:
HTTP/2 401
www-authenticate: Bearer realm="mcp", resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource", scope="mcp:tools"
{
"resource": "https://mcp.example.com/mcp",
"authorization_servers": [
"https://auth.example.com"
],
"scopes_supported": [
"mcp:tools",
"mcp:resources"
]
}实际 HTTP 版本、头字段大小写和顺序可能不同;重点核对状态码、resource_metadata 地址、resource 与授权服务器地址。
风险与边界
- 若接受签发给其他 API 的令牌,或把客户端令牌原样转发给下游,会触发令牌透传和混淆代理风险,可能越权访问并破坏审计。安全替代是拒绝错误受众令牌,由 MCP 服务使用自己的下游凭据或受控令牌交换。
- 若把访问令牌放进查询参数,代理日志、浏览器历史和监控系统可能泄漏令牌。只通过
Authorization: Bearer <token>传递,并强制 HTTPS。 - 若回调地址宽松匹配、未使用 PKCE
S256,或未绑定state与预期 issuer,授权码可能被截获或发生 mix-up。应精确登记回调 URI,并为每次授权保存一次性校验状态。 - scope 过大时,单个令牌泄漏会扩大影响面。挑战头只声明当前操作需要的最小权限,工具执行前再次做资源级授权。
排障清单
- 持续
401:检查 PRM 路径是否可访问、WWW-Authenticate是否指向正确地址,以及令牌是否过期。 - 报
invalid_token:比对授权服务器 issuer、JWKS 或内省端点、签名算法、时钟偏差和aud。 - 报
insufficient_scope:核对挑战头 scope、授权请求 scope 与工具实际要求,重新授权后再试。 - 浏览器授权后无法回调:检查登记的 redirect URI 是否与请求值逐字一致,并确认反向代理传递了正确的外部协议和主机名。
stdio 传输不使用这套 HTTP OAuth 流程,应改为由父进程通过环境或安全存储传入凭据。
通过环境变量或安全配置向本地 MCP 服务传递访问凭据。
管理 stdio 凭据
用于本地 stdio MCP 服务访问外部 API、数据库或云资源。凭据由启动 MCP 服务的父进程注入,服务端只从环境读取;不要把密钥写进源码、命令行参数或 stdout。
传递方式
优先使用“系统钥匙串或密钥管理器 + 启动包装脚本”。包装脚本在启动前读取秘密、导出到子进程环境,并用 exec 替换自身。这样 MCP 客户端配置只保存脚本路径,不保存明文密钥。
直接在客户端配置的 env 字段写入凭据只适合受控开发机,因为配置文件通常是明文。.env 仅用于本地开发,必须加入忽略规则并限制权限;生产环境使用操作系统钥匙串、容器 Secret 或集中式密钥管理服务。
macOS 安全存储示例
以下命令将令牌写入登录钥匙串。输入通过静默提示读取,避免出现在 shell 历史中。
read -r -s -p "MCP API token: " TOKEN
printf '\n'
security add-generic-password \
-U \
-a "$USER" \
-s "internal-mcp-api-token" \
-w "$TOKEN"
unset TOKEN预期结果:
无输出且退出码为 0;钥匙串中已存在服务名 internal-mcp-api-token 的密码项。验证读取过程但不打印秘密:
MCP_API_TOKEN="$(
security find-generic-password \
-a "$USER" \
-s "internal-mcp-api-token" \
-w
)" python3 -c 'import os; value=os.getenv("MCP_API_TOKEN", ""); print(f"credential_loaded={bool(value)} length={len(value)}")'预期输出:
credential_loaded=True length=<N><N> 是实际令牌长度。若命令返回非零,先确认钥匙串项目名称和账户名是否一致。
启动包装脚本
下面是片段示例,依赖 macOS security、Node.js 和实际服务入口。保存为仅当前用户可写的脚本,再让 MCP 客户端执行该脚本。
#!/usr/bin/env bash
set -euo pipefail
MCP_API_TOKEN="$(
security find-generic-password \
-a "$USER" \
-s "internal-mcp-api-token" \
-w
)"
if [[ -z "$MCP_API_TOKEN" ]]; then
printf '%s\n' "credential error: empty MCP_API_TOKEN" >&2
exit 78
fi
export MCP_API_TOKEN
exec node "/opt/internal-mcp/server.js"生效行为:Node.js 进程继承 MCP_API_TOKEN,包装脚本不再驻留。验证时让服务把“凭据是否存在”写入 stderr,绝不能输出秘密值;stdout 必须只承载 MCP 协议消息。MCP 客户端配置只引用脚本:
{
"mcpServers": {
"internal-api": {
"command": "/usr/local/bin/start-internal-mcp"
}
}
}不同客户端的配置字段可能不同;不要假定 env 中的 ${MCP_API_TOKEN} 会自动展开,未明确支持时使用包装脚本。
风险与边界
- 将密钥作为
--token参数启动时,其他本机进程可能通过进程列表读取。安全替代是环境注入、文件描述符或系统密钥存储。 - 把秘密写入 stdout 会破坏 stdio JSON-RPC 数据流,并可能被客户端日志永久保存。诊断信息写 stderr,且只记录是否加载、来源和脱敏标识。
- 把明文密钥提交到仓库、镜像层或共享配置后,即使删除文件也可能保留在历史中。立即吊销并轮换,不要只做一次提交删除。
- 环境变量会被所有子进程继承。服务调用外部命令前应构造最小环境,避免把主凭据传播给不受信任的工具。
排障清单
- 服务启动即退出:在同一用户会话手动执行包装脚本,检查密钥管理器权限、入口路径和退出码。
- 服务提示缺少凭据:确认变量名大小写一致,且读取秘密与
exec发生在同一脚本进程。 - 客户端解析错误:检查服务是否向 stdout 输出了日志、欢迎语或堆栈;全部移到 stderr。
- 轮换后仍用旧值:彻底重启 MCP 子进程。环境变量在进程启动时复制,不会随密钥管理器内容自动更新。
速查原则:秘密只在启动边界注入、只传给目标进程、只在内存中短期存在,日志始终脱敏。
连接并检查服务端能力、请求参数、响应内容和协议日志。
使用 MCP Inspector
MCP Inspector 用于在接入宿主前验证服务是否能完成连接、能力发现、参数校验、工具调用和协议日志输出。先用 Web 界面交互排查,再用 CLI 把同一检查接入脚本或 CI。
命令定位
Inspector 通过 @modelcontextprotocol/inspector 运行,默认启动 Web 客户端;--cli 适合一次请求后退出。stdio 服务把启动命令及参数直接写在 Inspector 后面,远程服务则使用服务 URL 和对应传输类型。
# Web:启动服务并打开交互界面
npx @modelcontextprotocol/inspector node build/index.js
# CLI:完成初始化后列出工具,并输出便于脚本处理的 JSON
npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list --format json预期输出
Web 模式:终端打印包含一次性会话令牌的本地访问地址
CLI 模式:stdout 输出 JSON,对象的 result.tools 中包含工具名称、描述和输入模式实际地址、端口和工具列表取决于本机环境与服务实现。
界面检查顺序
连接成功后按以下顺序检查:
- 确认初始化完成,协议版本和服务端能力符合预期。
- 打开 Tools、Resources、Prompts,核对声明项是否完整,名称和模式是否稳定。
- 选择工具,先提交合法参数,再提交缺字段、错类型和边界值。
- 对照响应内容与协议日志,确认请求 ID、错误分类、通知和服务端日志没有串线。
高频用法
调用单个工具时优先使用 CLI,参数较复杂时用完整 JSON,避免 key=value 的自动类型转换改变字符串值。
npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/call --tool-name echo --tool-args-json '{"text":"ping"}' --format json预期输出
{"result":{"content":[{"type":"text","text":"ping"}]}}如果服务返回额外元数据,外层字段可能增加,但应能在 result 中读取调用结果。
风险与边界
显式绑定全网卡、暴露代理端口或关闭鉴权时,局域网用户可能访问 Inspector 后端并触发服务进程。安全替代方案是保持回环地址、保留一次性令牌,并通过受控隧道访问。
对写库、发消息、删文件等有副作用的工具直接点击调用,可能污染生产数据。应连接测试环境,使用只读账号或替身依赖,并为危险操作增加服务端确认与幂等保护。
stdio 服务若把普通日志写到 stdout,会破坏 JSON-RPC 消息流,表现为初始化失败或随机解析错误。业务日志应写 stderr,stdout 只保留协议消息。
排障清单
- 连接即退出:先在终端单独运行服务命令,检查入口路径、Node 版本和缺失环境变量。
- 能连接但列表为空:核对服务是否声明对应 capability,并确认注册逻辑在
connect前执行。 - 表单没有参数:检查工具
inputSchema是否为有效 JSON Schema,字段类型和required是否正确。 - 调用无响应:查看协议监控中的请求与响应 ID,同时检查服务端是否阻塞、超时或等待未提供的交互。
- CLI 管道失败:使用
--format json,并确保服务日志没有混入 stdout。
兼容性
当前 Inspector v2 需要 Node.js 22.19.0 或更高版本。旧版 Inspector 的命令参数和界面可能不同;团队应固定 npm 版本,并在升级后重新跑能力发现与工具调用冒烟测试。
为初始化、能力发现、工具调用和异常响应编写自动化测试。
编写 MCP 协议测试
协议测试应从客户端视角验证完整握手,而不是只调用服务端函数。最小覆盖包括初始化、能力发现、成功调用、参数错误和未知方法,确保升级 SDK 或修改传输层后仍符合协议行为。
测试链路

测试应通过真实传输连接服务。connect() 成功代表初始化握手完成;之后再断言工具列表和调用结果,能发现仅做单元测试无法覆盖的 framing、生命周期和能力声明问题。
可运行示例
先安装测试依赖:
npm install -D vitest
npm install @modelcontextprotocol/client @modelcontextprotocol/server zod
mkdir -p test预期结果
依赖安装完成,并创建 test 目录创建 test/fixture-server.mjs:
import { McpServer } from '@modelcontextprotocol/server';
import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
import * as z from 'zod/v4';
const server = new McpServer({ name: 'protocol-fixture', version: '1.0.0' });
server.registerTool(
'echo',
{
description: 'Echo input text',
inputSchema: z.object({ text: z.string().min(1) })
},
async ({ text }) => ({
content: [{ type: 'text', text }]
})
);
await server.connect(new StdioServerTransport());该夹具只向 stdout 写协议消息;测试日志应写 stderr。
创建 test/protocol.test.mjs:
import { afterAll, beforeAll, describe, expect, it } from 'vitest';
import { Client } from '@modelcontextprotocol/client';
import { StdioClientTransport } from '@modelcontextprotocol/client/stdio';
const client = new Client({ name: 'protocol-test', version: '1.0.0' });
beforeAll(async () => {
const transport = new StdioClientTransport({
command: process.execPath,
args: ['test/fixture-server.mjs']
});
// connect 会启动子进程并完成 initialize 握手。
await client.connect(transport);
});
afterAll(async () => {
await client.close();
});
describe('MCP protocol', () => {
it('discovers registered tools', async () => {
const { tools } = await client.listTools();
expect(tools.map(tool => tool.name)).toContain('echo');
expect(tools.find(tool => tool.name === 'echo')?.inputSchema.type).toBe('object');
});
it('calls a tool successfully', async () => {
const result = await client.callTool({
name: 'echo',
arguments: { text: 'ping' }
});
expect(result.isError).not.toBe(true);
expect(result.content).toContainEqual({ type: 'text', text: 'ping' });
});
it('returns a tool error for invalid arguments', async () => {
const result = await client.callTool({
name: 'echo',
arguments: { text: '' }
});
expect(result.isError).toBe(true);
});
it('throws a protocol error for an unknown tool', async () => {
await expect(
client.callTool({ name: 'missing-tool', arguments: {} })
).rejects.toThrow();
});
});运行测试:
npx vitest run test/protocol.test.mjs预期输出
✓ test/protocol.test.mjs (4 tests)
Test Files 1 passed (1)
Tests 4 passed (4)耗时和排版可能随 Vitest 版本不同,但四个断言都应通过。
断言边界
参数校验失败通常是工具结果,使用 isError: true 表示模型可读取并修正参数;未知工具属于协议级失败,客户端调用会抛出异常。不要把两者都断言为相同错误文本,否则 SDK 更新措辞就会造成脆弱测试。
初始化测试不要只检查进程存活。至少在连接后执行一次 tools/list,这样能同时验证版本协商、能力声明、消息 framing 和请求响应关联。
风险与边界
测试连接生产服务并调用有副作用工具时,可能创建真实订单、发送通知或修改数据。安全替代方案是使用专用测试服务、隔离账号和固定夹具,并把写操作替换为可验证的假实现。
未在 afterAll 或 finally 中关闭客户端,会遗留子进程并导致后续测试占用端口或挂起。所有失败路径都应执行 client.close(),CI 还应设置整体超时。
只使用 SDK 发包无法覆盖畸形 JSON、重复请求 ID 或非法消息顺序,因为 SDK 会在发送前阻止部分错误。需要验证解析器防御时,另写原始传输夹具,并将其与常规协议测试分组运行。
排障清单
- 测试一直不退出:确认
afterAll执行,并检查服务是否忽略 stdin 关闭。 - 初始化失败:检查服务 stdout 是否混入日志,协议日志应与业务日志分流。
- 本地通过、CI 失败:固定 Node、SDK 和 Inspector 版本,避免最新依赖改变协议行为。
- 错误断言频繁波动:优先断言
isError、错误码或结果结构,不匹配完整自然语言。 - HTTP 与 stdio 表现不同:复用同一组断言,只替换 transport 工厂,分别运行两套测试。
定位普通日志写入标准输出导致 stdio 消息解析失败的问题。
排查 stdout 污染
stdio 模式下,stdout 只用于传输逐行 JSON-RPC 消息;启动横幅、调试打印或日志只要混入其中,就会让客户端在解析第一条非法行时断开。日志应写入 stderr 或文件。:contentReference[oaicite:0]{index=0}
命令定位
先把服务端的两个输出流分开捕获,再逐行检查 stdout。将 SERVER_COMMAND 改成实际启动命令;测试输入使用一次 initialize 请求,协议版本应替换为客户端和服务端共同支持的版本。
SERVER_COMMAND='python3 server.py'
printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"stdout-diag","version":"1.0.0"}}}' \
| bash -lc "$SERVER_COMMAND" >mcp.stdout 2>mcp.stderr || true
python3 - <<'PY'
import json
from pathlib import Path
path = Path("mcp.stdout")
valid = 0
invalid = []
for number, raw in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
if not raw.strip():
continue
try:
message = json.loads(raw)
if not isinstance(message, dict) or message.get("jsonrpc") != "2.0":
raise ValueError("不是 JSON-RPC 2.0 对象")
valid += 1
except Exception as exc:
invalid.append((number, raw[:120], str(exc)))
print(f"VALID={valid} INVALID={len(invalid)}")
for number, raw, reason in invalid:
print(f"line {number}: {raw}")
print(f"reason: {reason}")
print("RESULT=STDOUT_POLLUTED" if invalid else "RESULT=STDOUT_CLEAN")
PY预期输出(存在启动日志污染时,具体行号和文本可能不同):
VALID=1 INVALID=1
line 1: INFO MCP server started
reason: Expecting value: line 1 column 1 (char 0)
RESULT=STDOUT_POLLUTED读取方法:INVALID 大于 0 即确认污染;查看 mcp.stderr 可确认正常日志是否已进入错误流。若 VALID=0 INVALID=0,服务可能在返回初始化响应前退出,应继续检查退出码和 mcp.stderr。
高频污染源
常见来源不是协议实现本身,而是进程启动阶段和依赖库:
- JavaScript/TypeScript 的
console.log()、Python 的print()、Java 的System.out.print*()。 - Web 框架启动横幅、包管理器提示、调试器 banner、异常栈被配置到标准输出。
- 子进程继承父进程
stdout,把编译器或外部命令输出直接写入协议流。 - 日志框架的 Console Appender、Handler 或 Transport 默认绑定到
stdout。
安全改法是把普通日志改到 stderr:Node.js 使用 console.error(),Python 使用 logging 或 print(..., file=sys.stderr),Java 将控制台 Appender 目标设为 System.err。MCP 官方传输规范明确要求 stdio 服务端不得向 stdout 写入非 MCP 消息。:contentReference[oaicite:1]{index=1}
风险与边界
不要通过 > /dev/null、关闭 stdout 或把整个标准输出重定向到日志文件来“消除日志”;这会同时吞掉合法 JSON-RPC 响应,结果仍是连接失败。应只调整日志目的地,并保留协议写入器独占 stdout。
该限制针对 stdio 传输。Streamable HTTP 的应用日志不会直接插入 HTTP 响应体,但仍应由日志框架管理,避免与反向代理、容器采集或测试输出混淆。
排障清单
- 确认客户端启动的是预期可执行文件,命令前没有 shell profile、包装脚本或包管理器提示。
- 从进程启动第一行开始检查,不能只看初始化响应之后的输出。
- 搜索直接打印调用,并检查日志框架最终 Appender/Handler 指向。
- 暂停第三方库日志或把其级别降到
WARN,用于定位污染来源;不要长期关闭错误日志。 - 修复后重新捕获,必须得到
RESULT=STDOUT_CLEAN,且客户端能完成初始化。
速查结论:stdio 下把 stdout 当作协议专用通道,所有人类可读日志都写入 stderr。
检查协议版本、初始化顺序和能力协商导致的连接失败。
排查初始化失败
初始化失败优先核对三件事:initialize 是否为首次交互、双方是否协商出共同支持的 protocolVersion、客户端是否在收到响应后发送 notifications/initialized。任一步骤缺失或乱序,都可能表现为连接立即关闭、超时或后续方法不可用。:contentReference[oaicite:2]{index=2}
初始化顺序

正确顺序是:客户端先发送带请求 id 的 initialize;服务端用相同 id 返回协商版本、能力和实现信息;客户端确认可接受后发送不带 id 的 notifications/initialized;随后双方才进入常规操作。通知不应收到响应。:contentReference[oaicite:3]{index=3}
验证初始化轨迹
下面脚本生成一份最小正确轨迹并校验顺序。排查真实连接时,把 mcp-init-trace.jsonl 替换为抓取结果,保持每行包含 dir 和 msg 两个字段。
cat >mcp-init-trace.jsonl <<'JSONL'
{"dir":"C>S","msg":{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"diag-client","version":"1.0.0"}}}}
{"dir":"S>C","msg":{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-11-25","capabilities":{"tools":{}},"serverInfo":{"name":"demo-server","version":"1.0.0"}}}
{"dir":"C>S","msg":{"jsonrpc":"2.0","method":"notifications/initialized"}}
JSONL
python3 - <<'PY'
import json
from pathlib import Path
events = [json.loads(line) for line in Path("mcp-init-trace.jsonl").read_text().splitlines()]
request, response, ready = events
assert request["dir"] == "C>S"
assert request["msg"]["method"] == "initialize"
assert request["msg"]["jsonrpc"] == "2.0"
assert "id" in request["msg"]
assert response["dir"] == "S>C"
assert response["msg"]["id"] == request["msg"]["id"]
assert "result" in response["msg"]
requested = request["msg"]["params"]["protocolVersion"]
selected = response["msg"]["result"]["protocolVersion"]
assert ready["dir"] == "C>S"
assert ready["msg"]["method"] == "notifications/initialized"
assert "id" not in ready["msg"]
print("ORDER=OK")
print(f"REQUESTED_VERSION={requested}")
print(f"SELECTED_VERSION={selected}")
print("READY=YES")
PY预期输出:
ORDER=OK
REQUESTED_VERSION=2025-11-25
SELECTED_VERSION=2025-11-25
READY=YES版本值会随实际实现变化。若断言失败,异常所在行就是首个顺序或字段问题;先修复该处,再检查后续消息,避免被连锁错误误导。
输出字段说明
| 字段 | 检查点 |
|---|---|
protocolVersion |
服务端可接受请求版本时应回同一版本;否则可返回其支持的另一版本,客户端不支持时应断开 |
capabilities |
只声明实际支持的功能;缺失能力按“不支持”处理,不能仅凭方法名称推断 |
clientInfo / serverInfo |
至少提供实现名称和版本,用于识别连错进程或旧二进制 |
id |
初始化响应必须与请求 id 一致;notifications/initialized 不得带 id |
error |
若存在,优先记录错误码、消息和数据,不要只保留宿主应用的“连接失败”摘要 |
高频故障
- 协议版本不兼容:服务端返回客户端不支持的版本。后果是客户端应断开;安全方案是维护明确的支持版本集合,并使用双方交集,而不是无条件硬编码最新版本。
- 初始化乱序:客户端在初始化响应前发送
tools/list等请求,或遗漏notifications/initialized。后果是请求被拒绝、超时或服务端保持未就绪状态;安全方案是用连接状态机串行推进。 - 能力声明不一致:声明
tools、resources、sampling等能力,却没有对应处理器,或调用未协商能力。后果通常是初始化后首次调用失败;安全方案是从实际注册的处理器生成能力声明。 - JSON-RPC 结构错误:请求缺少
jsonrpc: "2.0"、请求id重复或响应id不匹配。后果是客户端无法关联响应;安全方案是在传输边界执行 schema 校验并记录原始消息。
排障清单
- 先排除上一条所述的
stdout污染,确保抓到的是完整 JSON-RPC 消息。 - 确认
initialize是首个非 ping 请求,且没有被放入批处理。 - 对照客户端与服务端支持版本,检查服务端返回值是否在客户端集合内。
- 核对双方能力声明与实际处理器注册结果,不要用空对象之外的字段“占位”。
- 确认初始化响应和请求
id相同,随后出现无id的notifications/initialized。 - 只有完成上述步骤后再排查工具、资源或提示词接口,避免把生命周期问题误判为功能问题。
速查结论:按“请求初始化 → 协商版本与能力 → 就绪通知 → 正常操作”的顺序逐帧核对,通常能在第一处偏差定位根因。
定位端点地址、请求头、跨域、代理和会话配置问题。
排查远程 MCP 连接失败
用于定位“客户端连不上远程 MCP 服务、浏览器报网络错误、代理后超时或收到异常状态码”的问题。先用最小 POST 请求确认故障位于 DNS/TLS、反向代理、鉴权、协议头还是旧版会话兼容层。

最小探测
以下请求使用 2026-07-28 协议的 server/discover。未配置令牌时会省略 Authorization,便于观察服务是否主动返回 OAuth 挑战。
MCP_URL="${MCP_URL:-https://mcp.example.com/mcp}"
TOKEN="${TOKEN:-}"
AUTH_HEADERS=()
if [[ -n "$TOKEN" ]]; then
AUTH_HEADERS=(-H "Authorization: Bearer $TOKEN")
fi
curl -sS --http1.1 \
-D /tmp/mcp-headers.txt \
-o /tmp/mcp-body.txt \
-w 'HTTP %{http_code}\n' \
-X POST "$MCP_URL" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'MCP-Protocol-Version: 2026-07-28' \
-H 'Mcp-Method: server/discover' \
"${AUTH_HEADERS[@]}" \
--data '{"jsonrpc":"2.0","id":"discover-1","method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"curl-check","version":"1.0.0"},"io.modelcontextprotocol/clientCapabilities":{}}}}'
cat /tmp/mcp-headers.txt
cat /tmp/mcp-body.txt预期输出:
HTTP 200
HTTP/1.1 200 OK
Content-Type: application/json
{"jsonrpc":"2.0","id":"discover-1","result":{"resultType":"complete","supportedVersions":["2026-07-28"],"capabilities":{"tools":{},"resources":{}},"_meta":{"io.modelcontextprotocol/serverInfo":{"name":"ExampleServer","version":"1.0.0"}}}}服务名、能力字段和响应头会因实现不同而变化;关键是状态码、Content-Type、响应是否能持续读取,以及代理是否保留 MCP 请求头。
按状态码定位
HTTP 000、DNS 错误或 TLS 握手失败:检查域名解析、证书链、SNI、出口防火墙和代理变量;先不要排查 MCP JSON。301/302:端点路径、尾斜杠或 HTTP 到 HTTPS 跳转配置错误。MCP 客户端不一定保留 POST 请求体和授权头,安全做法是直接配置最终 HTTPS 端点。400:优先核对 JSON-RPC 格式、MCP-Protocol-Version、Mcp-Method及正文_meta。协议版本不支持时,读取错误体中的supported后选择共同版本重试。401:进入令牌与授权服务器发现排查;不要误判成网络问题。403:可能是Origin不在允许列表、令牌权限不足或业务访问策略拒绝。先看WWW-Authenticate,再看网关和服务日志。404/405:通常是路径或协议代际不匹配。2026-07-28 端点只接收 POST;旧客户端发送 GET、DELETE 或依赖会话头时可能收到405。502/504:请求已到反向代理但未正常到达上游,检查 upstream 地址、连接超时、读取超时和容器监听地址。
请求头与代理
远程 Streamable HTTP 请求至少要正确传递 Content-Type、同时包含 JSON 与 SSE 的 Accept、协议版本头和方法头;tools/call、resources/read、prompts/get 还需要正确的 Mcp-Name。正文 _meta 是协议元数据的事实来源,代理不应改写正文或丢弃 Mcp-* 头。
浏览器中“curl 成功、页面失败”通常指向 CORS 或预检。允许实际前端来源、POST 方法以及 Authorization、Content-Type、MCP-Protocol-Version、Mcp-Method、Mcp-Name 等请求头;使用自定义 Mcp-Param-* 时也要允许并转发。SSE 被延迟或一次性返回时,关闭代理响应缓冲并延长读取超时。
会话与兼容性
2026-07-28 已移除协议级会话、独立 GET 流和 Last-Event-ID 恢复机制。2025-03-26 至 2025-11-25 的服务可能返回 Mcp-Session-Id,客户端后续请求必须携带;带旧会话收到 404 时应重新初始化。客户端和服务端跨代连接时,应显式启用共同版本,而不是混用两代行为。
风险与边界
不要为“先连通”而关闭 Origin 校验、对携带凭据的浏览器请求开放任意来源,或在代理日志中记录完整 Authorization、Cookie 和会话标识。这样会引入 DNS 重绑定、令牌泄露和会话劫持风险。安全替代方案是精确来源白名单、端到端 HTTPS、敏感头脱敏,以及按协议版本分别配置兼容路径。
检查授权服务器发现、访问令牌、权限范围和资源访问策略。
排查 MCP 401 与 403
用于区分“没有可用凭据”和“凭据有效但无权执行当前操作”。先读取状态码与 WWW-Authenticate,再验证受保护资源元数据、令牌目标资源、权限范围和业务访问策略。

状态码含义
| 状态 | 常见触发条件 | 正确处理 |
|---|---|---|
401 Unauthorized |
未带令牌、令牌过期或撤销、签名无效、令牌不是签发给当前 MCP 资源 | 读取挑战信息,完成发现、刷新或重新授权 |
403 Forbidden |
令牌有效但 scope、角色、租户或资源策略不足;也可能是非法 Origin 在鉴权前被拒绝 |
查看 insufficient_scope 和服务端拒绝原因,补权限或修正策略 |
400 Bad Request |
授权请求、回调参数或协议请求格式错误 | 修正请求,不要循环刷新令牌 |
对比探测
脚本分别发送无令牌和带令牌请求。将 TOKEN 设置为当前访问令牌;不要把真实令牌写进脚本或提交到仓库。
MCP_URL="${MCP_URL:-https://mcp.example.com/mcp}"
TOKEN="${TOKEN:-}"
probe() {
local mode="$1"
local auth=()
if [[ "$mode" == "bearer" && -n "$TOKEN" ]]; then
auth=(-H "Authorization: Bearer $TOKEN")
fi
echo "=== $mode ==="
curl -sS --http1.1 -D - -o /dev/null \
-X POST "$MCP_URL" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'MCP-Protocol-Version: 2026-07-28' \
-H 'Mcp-Method: server/discover' \
"${auth[@]}" \
--data '{"jsonrpc":"2.0","id":"auth-check","method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"auth-check","version":"1.0.0"},"io.modelcontextprotocol/clientCapabilities":{}}}}'
}
probe none
probe bearer预期输出:
=== none ===
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource"
=== bearer ===
HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope", scope="files:write", resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource"真实服务可能直接返回 200,也可能给出不同 scope。无令牌为 401、带令牌仍为 401,重点查令牌;带令牌变成 403 insufficient_scope,重点查授权范围。
排查 401
先确认每个 HTTP 请求都使用 Authorization: Bearer <token>,令牌没有放在查询字符串。读取 resource_metadata 指向的受保护资源元数据;缺少挑战地址时,再检查端点路径对应的 /.well-known/oauth-protected-resource/... 和根路径回退地址。
元数据中的 authorization_servers 至少应有一个可用发行方。继续核对授权服务器元数据的 issuer 是否与发现地址严格一致,以及授权请求和令牌请求是否都携带当前 MCP 服务的规范化 resource。令牌过期、尚未生效、被撤销、签名密钥不匹配或 audience 指向其他服务,都应重新获取令牌,而不是在资源服务器放宽校验。
OAuth 回调失败时检查 redirect URI 是否逐字匹配注册值;localhost 与 127.0.0.1 即使指向同一机器,也属于不同 URI。清除陈旧客户端注册或缓存令牌前,先确认当前服务是否切换了授权服务器。
排查 403
先检查响应是否包含 error="insufficient_scope" 和 scope。客户端应把当前已持有范围与挑战要求范围取并集,执行一次升级授权,再用新令牌重试原请求;设置有限重试次数,避免错误 scope 配置造成授权循环。
没有 insufficient_scope 时,检查 Origin 白名单、用户角色、租户边界、资源所有权、工具级策略和环境限制。若同一令牌能调用只读工具却不能调用写入工具,通常不是令牌格式问题,而是操作级 scope 或服务端策略不足。
风险与边界
不要通过接受任意 audience、跳过签名或过期校验、把高权限 scope 默认授予所有客户端来消除 401/403;后果是令牌可跨服务重放或普通用户获得敏感操作权限。安全替代方案是令牌绑定目标资源、最小权限、短生命周期、按操作升级授权,并在日志中仅记录令牌指纹、issuer、audience、scope 和拒绝规则,不记录完整令牌。