PrompTom
All skills

Building an MCP server

mcp-serverPROmcpintegrations

Not a wrapper around every endpoint, but a set of tools a model can use without being coached.

What it does

  • Triggers on “connect this service to Claude”, “we need MCP”, “expose our API to an agent”.
  • Requires designing tools around intentions rather than endpoints: a twelve-endpoint API usually makes three good tools, and a one-to-one mapping produces a surface the model has to assemble a workflow from — and assembles wrong.
  • Treats the tool description as the documentation: the model chooses on that alone, so it must say how this tool differs from its neighbour.
  • Demands constraints in the schema: enums, formats, required fields. Every constraint is a class of mistake the model can no longer make.
  • Forbids returning a raw dump of a hundred fields: it spends context and buries the answer. Return what the next call will need.
  • Requires errors to carry the reason and the fix: “not authorised” produces a retry loop, “the token lacks the orders:read scope” produces a next step.
  • Warns separately about stdout: under stdio transport, stdout is the protocol, and one stray print kills the server.

Why you'd want it

The protocol itself is not hard; the SDK covers it. Design is where it breaks: tools that mirror endpoints require somebody to know the call order, and the model does not — so it invents one. Plus two quiet killers: printing to stdout, and unbounded output that ends the conversation before the task.

Where to put it

  1. 1Create the folder .claude/skills/mcp-server in your project
  2. 2Put a SKILL.md file in it with the text below
  3. 3That's it. Claude Code loads the skill itself when a task matches the description

To make the skill available in every project rather than one, put it in ~/.claude/skills instead of the project folder.

SKILL.md file

# Building an MCP server

An MCP server exposes tools to a model. The hard part is not the
protocol — the SDK handles that. The hard part is designing tools a
model can actually use without a human reading the API docs for it.

## Design the tools before writing any

**One tool per user intention, not per API endpoint.** An API with
twelve endpoints usually makes three good tools. Wrapping each endpoint
one-to-one produces a surface the model has to assemble a workflow from,
and it assembles it wrong.

**Name them as verbs on objects:** `search_orders`, `create_invoice`.
Not `handler_v2`.

**Descriptions are the documentation.** The model chooses a tool from
its description alone. Say what it does, when to use it rather than the
neighbouring tool, and what it does not do.

**Constrain the inputs in the schema.** Enums for fixed choices, formats

This skill's file is part of the PRO collection

Unlock access
Building an MCP server — PrompTom