Anthropic / mcp-builder
When should you build an MCP server instead of a skill?
When the agent needs to do something, not to know something.
What to remember
- Tool design is the whole game. A poorly named tool is an unused tool.
- Fewer, well scoped tools beat many overlapping ones.
- Error messages are part of the interface, because the agent reads them and decides what to do next.
- Servers grant capability, and capability needs authorisation boundaries.
01What it changes in practice
The difficulty in MCP work is not the protocol, it is the interface design. An agent picks tools from names and descriptions, so a tool called process that takes an options object will be misused constantly.
Building with explicit guidance keeps the surface small and legible, which is what makes the difference between a server the agent uses correctly and one it avoids or misapplies.
02Where it disappoints
It does not decide your security model. What the agent may read, write and delete is a decision that belongs to you and needs enforcing on the server side.
Protocol details also move. Check the current specification rather than assuming the skill's snapshot is up to date.
Install and first run
- Install it from anthropics/skills under Apache 2.0.
- Design the tool surface first: few tools, clear names, obvious arguments.
- Test with the vaguest realistic request, because that is what exposes bad tool boundaries.
Questions people actually ask
- Skill or MCP server?
- Skill for procedure and conventions. Server for capability, meaning access to a system the agent cannot otherwise reach.
- What is the most common design mistake?
- Too many overlapping tools with vague names, which makes selection unreliable.
- Do error messages matter?
- Yes. The agent reads them and chooses its next step, so treat them as part of the interface.
Sources
Machine readable versions of this page