随手记：MCP 配置不手抄了，bl mcp connect 替我写，交给 agent 前先真调一次

最近在给手上的 coding agent 接 MCP 服务，手抄配置抄到第四次 401，终于承认这事不该手做：endpoint、transport、Authorization，还有两个听都没听过的来源追踪 header，错一个就是一屏读不懂的报错。

转机是阿里云百炼命令行里的 bl mcp 组。connect 一条命令把服务写进 agent 的私有配置，我打开 .qwen/settings.json 看，mcpServers 下多出一个条目，httpUrl 加四个 header，整整齐齐。组内鉴权也分工：connect、tools、call 要 Key，disconnect 连 Key 都不要，纯本地按账本指纹删。它还在主目录留了一本账，.bailian/mcp-registrations.json，里面有端点、传输方式、CLI 版本和一个 sha256 指纹，卸载的时候靠指纹认"自己写的那份"。

bl mcp connect --server TextGenerateImage --transport streamable-http --agent qwen-code

顺便说下方法：每次实验我都用临时目录当 HOME，connect 和 disconnect 都写在那儿，真实主目录里任何 agent 配置一个字节没碰。在这种事上胆小一点没坏处。生命周期跑下来是四态：第一次接返回 added；不动它再跑一次返回 unchanged；事先放一个手写的旧条目在旁边，旧条目一个字节都没被碰；干净卸载返回 removed，配置清空、账本变空对象。唯一别扭的路是我手改了受管条目之后：connect 和 disconnect 都报错退出码 1，说条目在注册后被改过、让我手工解决，谁也不肯覆盖我的手改。想想也对，卸载只删自己写的，指纹对不上就停手，宁可报错不误删。只是这条要写进自己的笔记：受管条目别手改。

交给 agent 之前我还有个新习惯：终端先真调一次。tools 子命令把工具清单和参数 schema 打出来，call 子命令真调一把，四点四秒回来 isError 为 false，content 里的 text 是段 JSON 字符串，还得再 parse 一层才拿到结果地址，这个小坑卡了我十分钟，记下来省得你再卡。

还有两个小发现。一是主目录下有个 telemetry.jsonl，每条命令追加一行，记命令名、耗时毫秒、成败和鉴权方式，我那次 connect 写着一千二百零四毫秒；想给团队做接入审计，这行是现成的，只是它和密钥副本住一个屋檐下，归置的时候别漏。二是 tools 打出来的 schema 里藏着三行硬边界：正向提示词超八百字自动截断、反向超五百自动截断、尺寸不传默认一千三百二十八见方。这些事手写配置时代都得撞墙才知道。

报错也有层次：参数不在白名单，客户端退出码 2 拦下并把合法值列给你；服务码或工具名不存在，服务端退出码 1，前者回一句"MCP服务不存在"；列目录的 list 要 Console 登录，我当天会话过期，退出码 3。看退出码就知道错在哪一层，比读报错散文快。

call 的返回里还有个 request_id 和一条带过期时间的签名链接，图是一千零二十四见方、一百一十三万字节出头，想留档就当时下载，过期不候。另外跑探针时命令行弹过一次版本横幅，说有新版本；我留在 2.5.0，因为同日第一个包的读数都取在这版，升不升留给你，升完把四态和错误阶梯重跑一遍再信旧结论。

两个小提醒：配置里那行 Authorization 是 Key 的明文副本，那文件得按密钥文件管，别提交进仓库；传输方式决定端点尾缀，streamable-http 是 /mcp、sse 是 /sse，按 agent 支持情况选。还有一条别想错：改模型 base-url 不会动 MCP 端点，help 写明这版注册的是官方中国站端点，base-url 只管模型调用。

最后给自己写了三句 onboarding：受管条目别手改、要改先 disconnect；配置文件当密钥文件管；接完先 tools 后 call、isError 为 false 再交给 agent。三句话管住这次测出来的全部坑。

账本里还有两个细节值得记：键是 agent 名加服务码拼的，值里那个指纹是六十四位十六进制；我做保护性实验时预置的旧条目 url 写的是 example.invalid、token 是个假的 legacy 值，connect 前后逐字段相等，一个字没被碰。sse 那种传输的端点尾缀是 /sse，和 streamable-http 的 /mcp 对着，header 一样，选哪个只看你的 agent 客户端认哪个。

感受是：单 agent 接一两个服务，图形入口更直观；但同时用几个 agent、接同一批服务、还想进脚本和团队 onboarding 的，这组命令把抄 N 份 JSON 变成跑 N 次命令，还带一本可审计的账。入口照旧，CLI 安装页装命令行，控制台密钥管理页领 Key。第五次 401 没再来，记一笔。