MCP 开发指南
MCP 开发教程：从工具设计到安全上线
把 API、数据库或内部系统封装成 AI Agent 能发现、理解和调用的标准工具，并用真正可执行的权限边界控制风险。
MCP（Model Context Protocol）是一套连接 AI 应用与外部工具、数据和提示模板的开放协议。开发 MCP Server 的价值，不只是“让大模型调用一个函数”，而是为工具发现、参数描述、结果返回和连接生命周期建立统一接口。
一个好用的 MCP Server 应该像设计良好的产品 API：工具少而清晰、输入可验证、输出可追踪、错误可恢复。不要把整套后台管理接口直接暴露给模型，再用提示词要求它“小心使用”。
先判断应该提供 Tool、Resource 还是 Prompt
Tool 适合执行查询或动作；Resource 适合读取可寻址的上下文；Prompt 适合复用经过设计的交互模板。把所有能力都做成 Tool 会增加模型选择难度，也会让权限设计变得模糊。
工具描述决定调用质量
名称要使用明确的动词和对象，例如 get_order_status，而不是万能的 run_api。描述中写清适用场景、副作用、必填参数和返回结构；枚举、长度、格式和数值范围应由 JSON Schema 或服务端验证强制执行。
选择 stdio 还是 Streamable HTTP
本地桌面客户端通常适合 stdio：进程生命周期简单，凭据留在本机。远程或多人服务通常采用 Streamable HTTP，但必须补齐 OAuth 或强认证、TLS、限流、租户隔离和审计，不能直接暴露匿名端点。
权限必须在后端生效
模型提示词不是安全边界。数据库账号、云角色、API Token 和业务审批才是可执行的控制。读取和写入应使用不同身份或不同工具；删除、付款、发布、发信等高影响动作必须要求人工确认。
为失败和重试设计协议行为
工具应返回结构化错误，而不是一长段不可解析日志。写操作要支持幂等键，避免客户端超时重试造成重复订单或重复消息；长任务应返回任务 ID，让客户端查询进度。
从零开始的实施步骤
- 定义一个最小用例 — 选择一个可验证的任务，写出输入、输出、失败条件和权限要求。
- 选择官方 SDK — 根据运行环境使用当前官方 TypeScript、Python 或其他 SDK，并锁定依赖版本。
- 实现只读工具 — 先完成发现、参数校验、超时、行数限制和脱敏，再考虑写操作。
- 用 Inspector 和真实客户端测试 — 覆盖正常输入、缺失字段、提示注入、超大结果、权限拒绝和服务中断。
- 接入 OpenClaw — 把经过验证的 MCP Server 连接到测试 Agent，观察真实工具选择和错误恢复，再逐步开放。
- 监控后再上线 — 记录调用者、工具、参数摘要、耗时、结果状态和业务关联 ID，并设置异常告警。
上线前检查清单
- 每个工具只有一个明确职责，名称和描述不存在歧义。
- 所有参数都在服务端验证，输出大小、耗时和并发都有上限。
- 凭据只保存在密钥系统或运行环境中，不进入提示词和日志。
- 运行身份遵循最小权限，读写分离，高影响动作需要人工批准。
- 远程连接启用 TLS、强认证、限流、审计和租户隔离。
- 写操作具备幂等性，故障时可以安全重试和回滚。
常见问题
MCP Server 可以用什么语言开发？
协议不限定语言。通常优先选择有成熟官方 SDK、团队熟悉且便于部署的语言，例如 TypeScript 或 Python。
开发 MCP 一定要部署公网服务器吗？
不一定。个人桌面场景可以使用 stdio 在本地运行；只有跨设备、多人或集中管理时才需要远程服务。
如何防止 AI Agent 误删数据？
不要只依赖提示词。移除删除权限、使用专用只读身份，并把必要的删除动作放入独立工具和人工审批流程。
相关中文指南
- MCP 开发教程 — 设计并安全部署 Agent 工具
- AI Agent 工作流 — 自动化、审批、重试与监控
- AI Agent 工具 — 搜索、浏览器、代码、文件与 MCP
- OpenClaw MCP 中文指南 — 了解 MCP 与 OpenClaw 的连接方式