mcp-builder 帮你把已有 API 包装成 Agent 能发现和调用的 MCP 工具。重点不只是让协议握手成功，还包括工具名是否清楚、参数是否可验证、分页是否完整，以及失败时能否知道下一步。它适合开发自己的服务连接器，不是安装后就能访问所有外部系统的万能接口。
安装与调用
在 Claude Code 的聊天输入框依次发送下面两条命令。这是插件命令，不是在系统终端运行的 Shell 命令；第二条安装的是包含 mcp-builder 的官方技能包。
/plugin marketplace add anthropics/skills
/plugin install example-skills@anthropic-agent-skills
安装后，在同一项目的会话里明确说“使用 mcp-builder”，再提供文件或任务。下面的提示词是可修改的首次输入示例。安装会加入技能说明与资源；它不会替你准备输入资料，也不代表所有依赖已经在本机安装。若找不到技能，先检查插件是否安装并启用，以及会话是否已加载最新插件，再继续任务。
从一个只读工作流起步
使用 mcp-builder 为我们的知识库 API 建一个 MCP server。
先读 docs/api.md，首版只支持搜索文档与读取文档详情。
使用 TypeScript，本地通过 stdio 连接；密钥从环境变量读取。
先给出工具名、输入输出结构和分页方案，再实现并用测试数据验证。
先限定服务、语言和客户端使用方式。技能建议 TypeScript，也提供 Python 路线；本地子进程连接可用 stdio，远程服务则需要考虑 Streamable HTTP。不要把本地运行命令直接当作远程部署方案。目标 API 的认证、限流、数据结构仍须从该服务自己的文档确认。
为“搜索文档”说明查询、返回数量和下一页信息，为“读取详情”说明文档 ID、正文和错误情况。可采用 knowledge_search_documents 一类带服务前缀的名字，减少同时接入多个 MCP 时的歧义。输出应足够支持下一步操作，但不要一次返回整库正文；分页和过滤比让模型处理巨大响应更可控。
实现后测试两层能力
第一层是工程正确性：构建是否通过，客户端能否列出工具，有效和无效参数分别怎样返回，凭据缺失或上游超时时是否给出可行动的错误。stdio 的标准输出应留给协议消息，普通日志写到标准错误，避免把调试文字混进通信。工具的只读或幂等注解需要与实际行为一致，但不能当作权限隔离本身。
第二层是任务能力：让模型只靠这些工具回答现实问题，例如在固定时间范围内找出两份文档之间的关系。官方评估流程使用独立、只读的问题和可比对答案；题目不能依赖上一题先写入的数据。你可以先用少量代表性问题找接口缺口，再扩展到指南建议的十题。
补充评估脚本会调用模型服务，需要相应依赖、API 凭据和可用模型配置；不要以为能编译 server 就已经具备评估环境。交付时应包含源码、启动说明、环境变量名称、工具清单和测试结果，而不是把真实密钥写进示例配置。如果搜索能返回结果但回答总漏信息，先检查分页、字段描述和输出内容，再决定是否增加更多工具。
从一个真正要完成的任务设计工具
先选一个窄场景，例如“按客户编号读取最近三张发票”，列出 Agent 必须知道的参数、API 可返回的字段、分页方式和认证边界。让 Agent 先设计工具名与输入 schema，再写服务器。若工具返回大量与任务无关的原始 JSON，Agent 仍可能找不到发票状态；输出结构应保留关键字段、游标和可解释的错误。
完成后至少走三类调用：正常编号、无权限编号、需要翻页的客户。协议连接成功只验证了一层；还要检查参数校验、错误是否会被误当成空结果，以及工具描述是否足够让 Agent 选择正确动作。官方流程另外强调评价问题，应选真实用户会问、且确实需要调用工具才能回答的问题，而不是只测启动成功。
把权限边界当作工具设计的一部分
若同一 API 既能读公开资料又能改客户记录，不要塞进一个名称含糊的万能工具。分开只读与写入动作，明确每个工具所需身份、输入与可能后果，并让错误响应区分“找不到”和“没有权限”。测试时用没有权限的账号走一遍，确认 Agent 不会把 403 解释为客户不存在。工具描述越贴近任务，Agent 越容易在正确时机调用，也越方便审核危险写入。
评估脚本报错先看运行环境
如果 Phase 4 评估在 connections.py 导入 streamablehttp_client 时就失败，错误发生在连接服务之前，不等于你的 MCP 工具实现有问题。一个公开复现案例发现 mcp Python SDK 2.1.1 与当时的示例脚本名称不匹配，而 1.29.1 可运行。先记录 SDK 版本、错误栈和运行命令，在隔离环境里按对应版本核对导入方式，然后再评估服务器行为；不要为了绕过导入错误去改工具业务逻辑。