Build an MCP server for your own system
Skills used in this guide (2)
用于创建高质量 MCP（模型上下文协议）服务器的指南，使 LLM 能通过设计良好的工具与外部服务交互。在构建 MCP 服务器以集成外部 API 或服务时使用，无论使用 Python（FastMCP）还是 Node/TypeScript（MCP SDK）。
npx skills add anthropics/skills -g创建新技能、修改并改进现有技能，衡量技能表现。当用户想从零创建技能、编辑或优化现有技能、运行评测测试技能、通过方差分析基准测试技能性能，或优化技能描述以提升触发准确度时使用。
npx skills add anthropics/skills -g
The common mistake is exposing your database, schema or API as a pile of tools. You end up with dozens of tools, the model picks the wrong one, and every call fails. Design tools around the handful of things a person would actually ask for. One action, one tool.
Who this is for
Good fit
- Internal ticketing, order, release or data systems you want AI to operate
- You already have an API (REST, GraphQL or SDK), so no backend work is needed
- You can ship a three-to-five tool version first
Bad fit
- Letting AI run arbitrary SQL against production. That is a permissions incident, not a capability
- No API, only internal web pages. Solve the interface first
- Building the whole platform in one go
Prepare
- Three to five real tasks, written as sentences people would say. This is the only input to tool design.
- API docs and credentials with minimum scope, ideally read-only.
- A Python or TypeScript environment.
Steps
1. Install
git clone --depth 1 --filter=blob:none --sparse https://github.com/anthropics/skills
cd skills && git sparse-checkout set skills/mcp-builder skills/skill-creatorCopy both into your client skills directory.
2. Design the tool list before writing code
Ask for each tool: a verb-first name, a one-line description, parameters marked required or optional, the return shape, and a read or write flag. Descriptions must say when the model should use the tool, not what the endpoint is called. Ask it to reject tasks that should not become tools.
Test: every tool maps to an action a user would say out loud. If the model must guess an ID first, you are missing a search tool.
3. Ship read-only first
Add write tools only after reads work. Every write tool needs an idempotency note, parameter validation, and error categories split into bad input, insufficient permission and downstream failure.
4. Test with real sentences
Connect the server and ask in the user's own words, not with tool names. If the model picks the wrong tool, the description reads like API docs. Fix the description, not the code.
5. Unify error handling
Return what is missing and the correct format for bad input, what permission is needed instead of a raw 403, and a retry message instead of a stack trace. Add rate limits and an audit log for writes.
6. Wrap common flows in a skill
Once the server is stable, use a skill to encode composite operations such as a weekly open-ticket digest, so the team never has to remember tool names.
Traps
| Trap | Symptom | Fix |
|---|---|---|
| Too many tools | Model keeps choosing wrong | One action per tool, start with five |
| Docs-style descriptions | Model does not know when to call | Write "use when the user wants to..." |
| Raw SQL surface | One bad call deletes data | Expose validated business queries only |
| Stack traces | Model cannot self-correct | Three human-readable error categories |
| Boiling the ocean | Nothing works after two weeks | One scenario end to end first |
FAQ
MCP versus function calling? MCP is how tools are discovered and connected; function calling is the model deciding to call. MCP lets you write a server once and use it from many clients.
Do I need to open a port? Not for local stdio servers. Remote deployment requires authentication.
Wrong tool picked? Rewrite the description with explicit use and non-use cases.
How do I avoid accidental writes? Declare side effects in the description, require confirmation client-side, and make the server idempotent with an audit log.
Can it connect to a database? Yes, but expose validated queries, never "run any SQL".
MCP or a skill? External system access is MCP. Codifying prompts and workflows is a skill. They are usually used together.