MCP Server 设计的 9 个常见错误，以及怎么避开

MCP server 的设计错误，大部分归结为两件事：模型分不清你的工具，或者某个工具失败时模型看不出哪里出了问题。把描述和错误契约修好，绝大多数误路由、无意义重试、假”没有结果”的回答就消失了——正是这些问题让 agent 显得不可靠。

这也是 Claude Certified Architect – Foundations 考试领域 2（Tool Design & MCP Integration，占 18%）的核心。情景题会描述一个行为异常的 server，问你哪种重新设计最不坏。下面九个错误在生产环境和考题里都反复出现，每个都附修法。

哪些工具描述的错误会导致误路由？

错误 1：工具描述只差一个词

三个提取工具分别描述为”从发票文档提取数据""……从合同文档……""……从报告文档……”。人看着区别明显，对模型来说这是三条几乎相同的字符串。某个实测系统里，30% 的合同被路由到了发票工具。执行准确率没问题，问题出在选择。

**修法：**每条描述都写清用途、输入格式、输出内容、使用场景，以及一条明确的边界加转向指引。一个可用的模板：

{
  "name": "extract_invoice",
  "description": "Extracts line items, quantities, totals and payment terms from invoice PDFs. Input: file path to a PDF. Returns: JSON with vendor, line_items[], total, due_date. Use for: supplier invoices, bills, receipts. NOT for contracts (parties, obligations, signatures) - use extract_contract.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "file_path": { "type": "string", "description": "Absolute path to the invoice PDF" }
    },
    "required": ["file_path"]
  }
}

四五十个词、带一句”NOT for”的描述，稳定优于五个词的描述。参见简略描述 30% 误路由，详细描述接近零和三个字段，全都关键：name、description、input_schema。

错误 2：用关键词规则而不是描述来修重叠

两个工具被混淆时，本能反应是往系统提示里加一条规则：“用户提到 refund 就调用 process_refund。“然后”我的退款到哪了？“就触发了一次新退款，而不是状态查询。某系统去掉关键词规则、只靠描述之后，路由准确率从 78% 升到 94%。

**修法：**先测出哪几对工具在互相误路由，只扩写这几对的描述，few-shot 示例留给真正模棱两可的剩余部分。细节见数据驱动修复描述：瞄准高误路由的工具对和去掉关键词规则后路由从 78% 提升到 94%。

错误 3：一个工具藏着多个”模式”

一个 analyze_document 工具，靠 mode 参数决定是提取、摘要还是核实论断，等于逼模型去猜一个描述里几乎没解释的操作。参数错误率在 35% 左右很常见。

**修法：**拆成用途单一、schema 聚焦的多个工具。每个工具只干一件事的拆分不叫工具泛滥，它消灭的是猜模式。

哪些错误处理的问题会引起错误重试和假答案？

错误 4：千篇一律的 “Operation failed”

超时、日期格式非法、账户被停用、触发策略上限，四种情况都返回同样的 isError: true 加一句 “Operation failed”，agent 对四种情况就只有一个策略：重试。其中三种再怎么重试也不会成功。经典画面是客户在等，agent 却在三十秒里对一个权限错误重试了五次。

**修法：**给错误分类，并说明重试有没有用。

{
  "content": [{ "type": "text",
    "text": "Validation error: 'date' must be ISO 8601 (YYYY-MM-DD). Received '15th of March, 2024'. Convert to '2024-03-15' and retry." }],
  "isError": true,
  "structuredContent": {
    "errorCategory": "validation",
    "isRetryable": true,
    "invalidField": "date",
    "expectedFormat": "YYYY-MM-DD"
  }
}

瞬时错误可以重试；校验错误修正后可以重试；业务错误和权限错误不能重试，应该附带一条面向客户的消息和建议动作。恢复率从通用错误的约 15% 提升到结构化错误的 78–95%。数字错误码没用，模型查不了码表。参见结构化错误：78-95% 恢复率 vs 通用”Operation Failed”的 15%、没有分类，Agent 在权限错误上浪费 5 次重试和”Operation Failed” × 5 次重试 × 30 秒 = 客户白等。

错误 5：把失败伪装成空结果

数据库挂了，工具却返回 isError: false 加一句 “No results found”。agent 于是告诉客户”您的订单不存在”，而客户手里拿着确认邮件。换到研究场景，同一个 bug 会把一次宕机变成”这个主题没有任何论文”。

**修法：**查询没有执行，就返回 isError: true 并说明尝试了什么（“查询 order_id=ORD-12345 时超时”）。查询执行了但没匹配到任何东西，isError: false 才是正确的。这两种结果对一个粗糙的实现来说长得一样，对 agent 来说意思相反。参见”您的订单不存在”——但它存在，只是数据库挂了和 Foundations 篇的别把错误伪装成空结果。

哪些结构性错误会伤害选择准确率和安全？

错误 6：把可浏览的内容暴露成工具

五百篇知识库文章做成五百个工具，选择准确率直接崩掉。就算只做一个 search_kb 工具，agent 也得先知道自己要搜什么。

**修法：**只读目录用 MCP Resources。agent 先调 resources/list 看有什么，再对需要的条目调 resources/read。Resources 不计入 agent 需要从中选择的工具集合，所以一个有 3 个工具、500 个 resource 的 agent，仍然只在 3 个里选。经验法则：观察类的是 Resource，有副作用的动作是 Tool。参见 MCP Resources：不用工具调用就能浏览内容和 Tools、Resources、Prompts：MCP 的三大原语。

错误 7：一个 agent 面前工具太多

选择准确率随工具数量急剧下降：3 个工具时接近 97%，8 个时约 82%，18 个时只剩一半左右。“以防万一”加的工具不是免费的。工具过多的 agent 还会越出自己的角色，比如一个负责综合的 agent 因为碰巧有搜索工具就跑去重新搜索。

**修法：**每个 agent 只给它角色需要的工具；系统确实需要 15 个以上工具时，把它们分散到协调者背后的多个专职子代理上。最小权限同时也是准确率优化。参见 3 个工具 = 97% 准确率，18 个 = 51%：工具数量曲线和最小权限：每个 Agent 只拿角色所需的工具。

错误 8：泄露密钥，或者放错作用域

团队共享的 server 放在仓库根目录的 .mcp.json，提交进 git；个人 server 放在 ~/.claude.json。两者都不该放进 CLAUDE.md——那是指令文件，不是配置文件。而 .mcp.json 既然要提交，硬编码在里面的 token 就会永远留在 git 历史里。把文件加进 .gitignore 看似”修好”了泄露，实际上取消了共享这个初衷；base64 是混淆，不是安全。

修法：

{
  "mcpServers": {
    "github": {
      "command": "github-mcp-server",
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    }
  }
}

每个开发者在本地设置自己的环境变量，共享文件里只有引用。参见项目级放 .mcp.json，用户级放 ~/.claude.json和 ${ENV_VAR}：让密钥远离版本控制。另外记住，所有配置好的 server 都在启动时连接，你每加一个 server，agent 面前的工具总数就多一截。

错误 9：已经有现成的，还要自己造

官方或社区已经有 GitHub、Jira 的 server，你还自己写一个，就意味着它的 bug、认证流程、升级从此都归你管。fork 一份也是同样的代价。自建 server 只在私有内部 API 和别人没有的工作流上才值得。

**修法：**标准集成用社区 server，需要稳定就钉住版本。参见标准集成用社区 Server。顺便留意 Foundations 篇 camelCase 陷阱：MCP 工具定义 vs Claude API 里的命名坑：MCP 用 inputSchema，Claude Messages API 用 input_schema，两边互相复制粘贴会静默失败。

考试到底在考什么？

几乎每道领域 2 的情景题都可以归结为三个判断：模型有没有足够的信号选对工具；模型有没有足够的信号从失败中恢复；每项能力是不是通过正确的原语、在正确的作用域暴露出来的。干扰选项会加强措辞、加重试、加工具。得分选项会改进描述、结构化错误、把目录挪到 Resources、按角色限制工具、把密钥留在环境变量里。

下一步

从头到尾读一遍领域 2 学习指南；错误处理这组任务篇幅短，但考得很重。然后做一次免费模拟考，它按官方 18% 的权重抽取领域 2 情景题，把答错的对照上面链接的文章复盘。125 美元报名费、120 分钟形式等当前考试信息，报名前请到 Anthropic / Pearson VUE 官方页面核对。