给自己的系统造一个 MCP 服务

这篇适合谁 / 不适合谁

适合：

• 内部有查询/工单/发布/数据系统，想让 AI 直接操作
• 已有可用的 API（REST / GraphQL / SDK），不需要从零写后端
• 能接受先做一个 3 到 5 个工具的小版本验证

不适合：

• 想让 AI 直接连生产数据库执行任意 SQL（这是权限事故，不是能力问题）
• 没有 API、只有内网页面：先解决接口，再谈 MCP
• 期待一次做完整个平台：先做一个场景跑通

开始前准备什么

1. 3 到 5 个真实任务。写成句子："查一下订单 X 的物流状态"、"把工单 Y 转给 Z"。这是工具设计的唯一输入。
2. 目标系统的 API 文档与凭据（最好是只读 token + 最小权限）。
3. 一个能跑 Python 或 TypeScript 的环境。

操作步骤

1. 装 skill

mcp-builder 源码见 anthropics/skills，协议文档见 modelcontextprotocol.io，规范见 agentskills.io。

git clone --depth 1 --filter=blob:none --sparse https://github.com/anthropics/skills
cd skills && git sparse-checkout set skills/mcp-builder skills/skill-creator

复制到客户端技能目录（Claude Code ~/.claude/skills/、CodeBuddy ~/.codebuddy/skills/、Trae ~/.trae/skills/ 等）。

2. 先设计工具清单，不要写代码

我要给内部工单系统做 MCP server，这是用户会让 AI 做的 5 件事：
（粘贴任务句子）

请输出工具设计：
- 每个工具：名字（动词开头）、一句话描述、入参（必填/选填）、返回值结构
- 名字和描述要写成"模型能看懂什么时候该用它"，不是"接口名叫什么"
- 标出哪些工具是只读、哪些会写数据
- 如果某件事不适合做成工具，直接说不适合，并说明原因

判断标准：每个工具对应一个用户会说出口的动作。如果一个工具需要模型先猜 ID 再调用，说明你该加一个"搜索"工具。

3. 写 server（先只读）

让它先实现只读工具，确认能跑通后再加写操作。写操作的工具必须有：

• 明确的幂等说明（重复调用会怎样）
• 参数校验与错误分类（参数错 / 权限不足 / 下游故障 三类分开）
• 危险操作的二次确认描述

4. 连接并用真实问题测试

接到客户端后，用用户原话测试，不要用工具名测试：

"帮我看看工单 8842 现在卡在谁那里"

如果模型选错工具，90% 是第 2 步的工具描述写得像接口文档而不像人话。改描述，不要改代码。

5. 加错误处理与限流

给所有工具加统一错误处理：
- 参数错误返回"缺什么、正确格式是什么"
- 权限不足返回"需要什么权限"，不要返回原始 403
- 下游超时返回"系统忙，稍后重试"，不要抛堆栈
- 对写操作加频率限制与操作日志

6. 把常用操作封成 skill

server 稳定后，用 skill-creator 把"每周汇总未处理工单"这类组合操作写成 skill，团队就不必记住工具名。

会踩的坑

FAQ

MCP 和 Function Calling 有什么区别？

MCP 是"工具怎么被发现与连接"的协议，Function Calling 是模型决定调用哪个函数的能力。MCP 让你写一次 server，多个客户端都能用。

需要开放端口吗？

本地 stdio 模式的 server 不需要。要多人共用才需要部署成远程服务，那时必须做鉴权。

模型选错工具怎么办？

先改工具描述。描述里写清楚"什么时候用"和"什么时候别用"，比重写实现有效得多。

写操作怎么防止误触？

工具描述里声明副作用，客户端侧设置为需要确认，server 侧做幂等与审计日志。

能连数据库吗？

能，但不要暴露"执行任意 SQL"。暴露"查询某订单状态"这类带参数校验的业务查询。

怎么判断该做 MCP 还是该做 skill？

需要访问外部系统 → MCP。只是把提示词和流程固化 → skill。两者常配套使用。