MCP Server 上线之后：怎么知道模型都在拿你的工具干什么-开发者社区

MCP Server 上线之后：怎么知道模型都在拿你的工具干什么

前言

上一篇聊 MCP Server 的测试，结尾留了个钩子：可观测性。这篇把它补上。

先描述一个上线后最常见的场景：用户反馈"AI 助手答非所问"，你怀疑是模型乱调了工具，但手头没有任何记录——不知道那次会话里模型看到了哪些工具、发了什么参数、工具返回了什么。你唯一能做的是在自己电脑上连一遍，复现看看。"感觉修好了"，但你其实说不清刚才那次的真实原因。

传统 Web 服务有成熟的可观测性方案，日志、指标、链路追踪三大件。MCP Server 大体也能套用，但有两个本质差异，直接决定了方案怎么做：

调用方是模型，参数是模型生成的。参数里可能带着用户的敏感数据(文件路径、查询语句、邮件内容)，日志里全量打印参数，等于把用户数据抄了一份到日志文件——你自己制造了一个泄露面；
一次模型决策可能触发一串工具调用。链路的"根"不在 HTTP 入口，而在某轮对话里，传统按请求串 trace 的思路需要调整。

这篇文章讲我落地的做法：协议内日志、结构化调用日志、按工具分维度的指标、可回放的审计记录。代码仍是 TypeScript 官方 SDK。

一、先分清两条通道：协议内日志 vs 本地日志

MCP 协议自带 logging 能力，这是很多人没注意到的。Server 声明capabilities.logging之后，可以随时向客户端推日志消息：

const server = new Server( { name: "todo-server", version: "1.0.0" }, { capabilities: { tools: {}, logging: {} } }, ); // 工具执行中向客户端/用户报告进度和状态 await server.sendLoggingMessage({ level: "info", logger: "todo-server", data: "已扫描 120 个文件，开始匹配关键词", });

客户端(如果实现了 logging)会把消息展示给用户。这适合放过程可见的信息：长任务做到哪一步、准备批量处理什么。对用户来说，工具不再是"按下回车后黑箱三分钟"。

但要清楚它的边界：协议内日志是给"这次会话的用户"看的，不可检索、不会持久化(取决于客户端)、你自己的排查也用不上。所以本地结构化日志同样要做，两者不互相替代：

协议内日志：面向用户，报进度、报状态；
本地日志：面向你自己，记录完整调用事实，供排查和审计。

还有一个 stdio 特有的约束，测试篇提过再强调一次：stdio 模式下 stdout 是协议通道，本地日志只能写 stderr 或文件。日志框架配置错目的地，是 stdio server 的头号自毁方式。

二、工具调用日志：记什么、不记什么

核心原则：一次 tools/call 记一行结构化日志，够排查问题，但不复制用户数据。

type ToolCallLog = { ts: string; // ISO 时间 sessionId: string; // 会话标识(自增即可) tool: string; // 工具名 argDigest: string; // 参数摘要,不是参数全文 outcome: "ok" | "tool_error" | "thrown"; durationMs: number; resultDigest?: string; // 结果摘要 };

关键设计是argDigest(参数摘要)：

function digestArgs(args: Record<string, unknown>): string { return Object.entries(args) .map(([k, v]) => { const s = String(v); const shown = s.length > 24 ? s.slice(0, 24) + `…(${s.length})` : s; return `${k}=${shown}`; }) .join("&"); }

记参数的"形状"而不记内容：路径记到文件名、查询记前 24 个字符加长度。排查"模型传了空参数""参数类型不对"这类问题完全够用，同时避免把用户邮件正文、数据库记录写进日志。如果某个工具确实需要完整参数才能排查，做成开关配置 + 默认关闭，并在文档里写明这会记录用户内容。

用装饰器把记录逻辑统一包住所有工具，避免每个 handler 里手写：

const timed = <T>( name: string, fn: (args: Record<string, unknown>) => Promise<T> ) => async (args: Record<string, unknown>) => { const start = Date.now(); let outcome: ToolCallLog["outcome"] = "ok"; try { return await fn(args); } catch (e) { outcome = "thrown"; throw e; } finally { log.info({ tool: name, argDigest: digestArgs(args), outcome, durationMs: Date.now() - start, }); } };

注意outcome只在catch里改标记、finally里统一落日志——isError形式的"业务失败"不抛异常，会在正常返回路径记录，想区分的话在返回前检查一次result.isError把它标成tool_error。