一句话总结:不用装任何 SDK,Node 里四十行就能拉起一个 MCP 客户端。但第一版一定报错,因为协议里有四个不写在明面上的约定:Accept 头要同时报两种类型、初始化要发两次、通知类请求没有回包、响应可能是 SSE 格式。
我这段时间给站里的发布流程写了一个小客户端,用来调 Z-Blog 的 MCP 服务端发文章。最开始想装官方 SDK,看了下依赖数量,改成了自己写。
结果第一版每个请求都失败。四个问题一个接一个冒出来,每个都花了我一轮排查。这篇把四个坑和解法写清楚,代码放在最后,可以直接抄。
先理解一次调用长什么样
MCP 是 JSON-RPC 2.0 套在 HTTP 上。一次完整会话是三步:先握手,再告诉对方「我准备好了」,然后才是你要干的事。
握手发的是 initialize,带上协议版本和你支持的客户端能力。对方回一个结果,里面写着它支持的版本、能力、服务名。
第二步是 notifications/initialized。它不是请求,是通知,用来告知握手完成。这一步很多人会漏,漏了的话有些服务端会拒绝后续调用。
第三步才是干活的:tools/list 看有哪些工具,tools/call 调其中一个。

图 1:第 2 步没有回包,这是第一版崩掉的地方
坑一:Accept 头要同时报两种类型
第一版我给的是 Content-Type: application/json,Accept 沿用浏览器的默认值。服务端直接拒了,理由是它可能用两种方式回包。
正确写法是 Accept 同时接受两种:application/json 和 text/event-stream。
这个要求的来源是协议允许服务端选择传输形态:同步返回一小段 JSON,或者用 SSE 流式回。 不改这个头,你连第一关都过不去,而且错误信息通常只说「不接受」,不说该写什么。
坑二:两次初始化,第二次没有回包
握手那步看着简单,但有个细节:notifications/initialized 是通知,服务端不会回任何内容。
我第一版对所有请求统一处理返回,结果在第二步崩了:拿回来的响应体是空字符串,JSON.parse 直接抛语法错误。
解法就一句:方法名以 notifications/ 开头时,发完就走,不要读响应体。
这一条不写在教程里,但它是协议规定的语义:通知不需要回复。写客户端的人得自己记住。
坑三:回包可能是 SSE,也可能是纯 JSON
同一套代码,我调一个服务端拿到的是标准 JSON,调另一个拿到的是以 data: 开头的一行文本。
两种都合法。客户端必须都能处理,判据很简单:响应体去掉首尾空白后如果以左花括号开头,就按 JSON 解析;否则找以 data: 开头的那一行,去掉前缀再解析。
这里有个容易忽略的写法细节:前缀后面可能有一个空格,也可能没有。用 slice(5) 然后再 trim 一次最稳。
如果你的客户端跑在浏览器里,还要注意服务端可能连发多条 data 行;命令行场景一般只回一条,但这不该假设。
坑四:工具返回的是一层字符串,不是对象
这个坑最隐蔽。你调 tools/call,拿到的是一个 result,里面有个 content 数组,每项带 type 和 text。
问题在于:text 是一个字符串,而很多服务端往里塞的是再序列化一次的 JSON。
所以正确姿势是先读 result.content[0].text,再对这段文本做一次 JSON.parse。
我第一次没做第二次解析,打印出来是一坨带反斜杠的字符串,还以为服务端编码出了问题。
顺带一个防御:成功时 result 有内容,失败时可能是 error,两者都要判。我在上传图片时踩到过,同名文件已存在,服务端返回错误,脚本直接崩在解构上。
完整代码
下面这段是能跑的最小实现,只用 Node 内置的 fetch,不需要任何依赖。把地址和令牌换成你自己的。
const url = process.env.MCP_URL;
const H = {
'Authorization': 'Bearer ' + process.env.MCP_TOKEN,
'Content-Type': 'application/json',
'Accept': 'application/json, text/event-stream'
};
async function rpc(body) {
const r = await fetch(url, { method: 'POST', headers: H, body: JSON.stringify(body) });
if ((body.method || '').startsWith('notifications/')) return null;
const t = (await r.text()).trim();
if (t.startsWith('{')) return JSON.parse(t);
const line = t.split('\n').find(l => l.startsWith('data:'));
return JSON.parse(line.slice(5).trim());
}
await rpc({ jsonrpc: '2.0', id: 1, method: 'initialize', params: {
protocolVersion: '2025-06-18', capabilities: {},
clientInfo: { name: 'my-client', version: '1' } } });
await rpc({ jsonrpc: '2.0', method: 'notifications/initialized' });
调用工具就是再加一段:
const res = await rpc({ jsonrpc: '2.0', id: 2, method: 'tools/call', params: {
name: 'zblog_list_articles', arguments: { count: 5 } } });
const payload = JSON.parse(res.result.content[0].text);
console.log(payload);
想看有哪些工具,把方法换成 tools/list,参数传空对象。这一步建议先做,比读文档快。
调试顺序,以及三个我没解决的问题
排查建议按这个顺序:先单独发 initialize,能拿到结果说明地址、令牌、Accept 头都对;再发 tools/list,能列出来说明握手完整;最后才调具体工具。
这套顺序的好处是每次只验证一层。反过来,一上来就调工具,报错时你分不清是认证问题、握手问题还是参数问题。 三个我没解决的问题,一并写在这里:一是协议版本号,我写的是 2025-06-18,换服务端可能要改,我不确定现在有几种版本在跑;二是错误码处理,我只区分了有没有 result,没有按 code 细分;三是并发,多个请求同时发时 id 怎么保证唯一,我用了递增,够用但不算严谨。
最后提醒一句:令牌不要写进代码。官方 MCP 那篇提到 VS Code 的配置会用输入变量承接令牌,就是同一个道理。我这边放环境变量里,脚本本身可以放进仓库。
写完这套东西再看MCP 协议那篇,会发现协议本身不复杂,麻烦全在传输层的这些约定上。四十行能跑,但每一行都对应一个踩过的坑。
FAQ
Q:必须用 Node 吗?
不必。这四条约定的本质是 HTTP 头、两次初始化和两层解析,换成 Python 或 Go 都是同样的结构。
Q:为什么不用官方 SDK?
只想发一个请求时,自己写四十行比研究 SDK 的初始化流程快。项目变复杂了再换回去。
Q:报 406 怎么办?
先看 Accept 头有没有同时写上 application/json 和 text/event-stream。
参考资料
- MCP 规范 · 2025-06-18(初始化、通知与工具调用的定义)
- GitHub · github-mcp-server(一个可对照的官方服务端实现)
代码与口径:文中四段代码是我在自己环境里跑通的版本,去掉了业务参数;四个坑都是实际报错后修掉的,不是照文档推的。协议版本号 2025-06-18 是当时用的值,其他服务端是否要求不同版本我不确定。关于 SSE 多条 data 行的处理,我只写了判断逻辑,没有找到会连发多条的服务端来实测。
- FAQ
- 参考资料
发表评论
◎欢迎参与讨论,请在这里发表您的看法、交流您的观点。