PrompTom
Tous les 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.

Ce qu'il fait

  • 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.

À quoi il sert

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.

Où le placer

  1. 1Créez le dossier .claude/skills/mcp-server dans votre projet
  2. 2Placez-y un fichier SKILL.md avec le texte ci-dessous
  3. 3C'est tout. Claude Code charge le skill lui-même quand une tâche correspond à la description

Pour que le skill soit disponible dans tous vos projets et pas un seul, placez-le dans ~/.claude/skills au lieu du dossier du projet.

Fichier SKILL.md

# 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

Le fichier de ce skill fait partie de la sélection PRO

Débloquer l'accès
Building an MCP server — PrompTom