API → MCP

Wrap an API as a local MCP server that is actually pleasant to use: few tools, each answering a whole question, honest about what it does not know.

The canon here is extracted from three servers already running in this workspace. Read the relevant one when a decision is unclear — they are the ground truth, this file is the summary:

• fitcrm-mcp/server.py — a fitness CRM whose API is barely documented. The hardest-won file: real endpoint paths that the docs slug did not match, broken pagination that made a revenue number wrong by 3×, one field that lies and one that turned out to be trustworthy. Its get_class_schedule docstring is the model of how to record that (see "Write the traps into the docstring" below).
• tidycal-mcp/server.py — a documented API with an OpenAPI spec. Cleanest structure: single _request layer, read/write annotations, env-gated writes, --check, and a slimmed composite (tidycal_agenda).
• victor-mcp/server.py — composite tools over a stack (Twenty + Notion) where raw CRUD already exists elsewhere. Source of get_guide, two-phase confirm_token, honest empties, graceful degradation.

Decide first: is a server the right answer?

Before writing anything, check in this order:

1. Does an official MCP already exist? Many products ship one. Search their docs. A hosted server that covers the job wins — less to maintain.
2. If it exists but is gated or crippled (read-only, Pro-only, missing the endpoints needed), a local server is justified — say so in the README, as tidycal-mcp does.
3. One user, one machine → local stdio server. Multi-tenant, clients logging in with their own accounts → that is OAuth 2.1 + DCR + PKCE + three well-known endpoints, a different and much larger job; use the agents-sdk skill instead.
4. Would a plain script do? If the user needs one number once a month, a script beats a server. A server earns its place when Claude must reach the data mid-conversation, repeatedly, unprompted.