Ship an MCP
server.

Work in dependency order rather than starting with code. First decide whose permissions the server acts with, because that determines transport, deployment and which tools are possible. Then design a small set of task-shaped tools rather than mirroring your API endpoints. Write descriptions that state when not to use each tool and enforce constraints in a strict input schema. Build over stdio locally, deploy over streamable HTTP with real per-user authorisation, connect it to the model with both the server declaration and the toolset declaration, add write tools only after the read surface has run in production, and cover tool selection with an eval.

Between roughly four and ten. Past about twenty tools on a single server you are usually fronting more than one system and should split it, and past twenty to thirty tools across all connected servers the model's selection accuracy degrades noticeably and you should enable deferred loading with a tool-search tool. Tool count matters more than server count because every definition is sent on every request.

Nine times out of ten the description is the problem, not the code. The model only sees the name, description and input schema, so if the description does not clearly state when to use the tool, or overlaps with another tool's description, selection becomes inconsistent. Check for a competing tool with a similar description, add an explicit statement of when not to use it, name the units and identifiers in the schema, and confirm the toolset is actually declared rather than only the server.

They are the two halves of connecting a remote server, and both are required. The `mcp_servers` entry tells the API where the server is, with a type, a url and a name. The `mcp_toolset` entry in `tools` exposes that server's tools to the model, referencing the same name. A request with only one of the two is rejected as a validation error, which is where most first integrations stall for an afternoon.

Any write whose failure is expensive or irreversible should have either a human approval gate or a hard precondition the server can verify independently of what the model asserted, and ideally both above a value threshold. Beyond the gate, make writes narrow enough to name as a single business action, idempotent through a request-derived key so retries are safe, and reversible with the before state logged. A tool description is guidance to a probabilistic caller and must never be the only control on a destructive action.

Test the handler with ordinary unit tests, then add the test that actually matters: a tool-selection eval. Keep a fixed set of realistic prompts with a known-correct tool call for each, including several that should produce no tool call at all, and run it on every server change including description edits. In production, track the distribution of which tools get chosen over time, because a sharp drop for one tool usually means an edit broke its selection rather than users losing interest.

Yes, and often you should when the vendor of the underlying system publishes and maintains it, since they will track their own API changes better than you will. Read its auth model before trusting it and confirm it supports per-user authorisation rather than a single shared key. Be considerably more careful with unaudited community servers on the write path: a server you did not read, holding a production credential, exposing tools whose descriptions the model obeys, is a supply-chain decision. Read the source, pin the version, and start it on the read surface.

A working server against a single system is an afternoon. A server you can put in front of production data is closer to a week, and almost none of that extra time is protocol work. It goes into the identity and authorisation model, designing task-shaped tools instead of mirroring endpoints, the approval and idempotency machinery on the write path, tracing, and the selection eval. Teams that skip straight to the afternoon version typically pay the week back later with a rewrite.