How to build an MCP server

When you should build one — and when you shouldn't

MCP is a real open standard introduced by Anthropic in late 2024. An MCP server exposes capabilities — tools, resources, and prompts — to an MCP client such as Claude Desktop, Claude Code, or Cursor, over JSON-RPC. The value is standardisation: build the integration once, and any compliant client can use it, instead of re-implementing a connector per assistant.

The first question is whether you should build at all. There is a growing ecosystem of existing servers for common systems — filesystems, popular databases, GitHub, and so on. If an official or well-maintained server already covers your system, use it. Building your own is worth it when the integration is specific to your domain: your internal APIs, your data model, your business actions, your access rules. That is exactly the surface no off-the-shelf server can know about.

The second question is whether an MCP server is even the right shape. MCP shines when a human-in-the-loop or agentic client needs to discover and call your capabilities dynamically across a session. If what you actually need is a fixed, deterministic pipeline that always runs the same steps, a plain script or service is simpler and easier to reason about. Reach for MCP when the calling pattern is open-ended and you want the model to choose which tool to use and when.

The pieces of an MCP server

An MCP server exposes three primitives. Tools are actions the model can invoke — query a database, file a ticket, call an internal API. Each tool has a name, a description, and a typed input schema, and it returns a result. Resources are readable data the client can pull into context — a file, a record, a document — addressed by URI. Prompts are reusable, parameterised templates the client can surface to the user, useful for encoding a standard workflow.

Tools are where most of the design effort goes, because the model decides whether and how to call them based on the name, description, and schema you write. Treat those as the interface: a clear description and a precise input schema are the difference between a tool the model uses correctly and one it misuses. Keep each tool doing one well-defined thing rather than exposing a single do-everything endpoint.

Underneath sits the transport. stdio runs the server as a local subprocess of the client, communicating over standard in/out — this is the default for local, single-user setups and the easiest to start with. HTTP transport runs the server as a networked service, which is what you want for a shared, remote, or multi-user deployment. The protocol underneath both is JSON-RPC: the client discovers your capabilities, then calls them, and your server responds.

A minimal Python server

The official Python MCP SDK removes almost all of the boilerplate. Conceptually, a minimal server is short: you create a server instance, register at least one tool, and start it on a transport. Registering a tool means giving it a name, a human-readable description, and an input schema (the SDK lets you derive the schema from typed function arguments), then writing the handler that runs when the tool is called and returns a result.

So the whole shape of a first server is: define one tool — say, a function that takes a typed argument, does the work (query a store, hit an API), and returns text or structured data; let the SDK expose its schema from the argument types and docstring; and run the server over stdio so a local client can launch it. That is genuinely all a working server needs — everything else is adding more tools, resources, and prompts in the same pattern.

The discipline here is to keep handlers thin and honest. A handler should validate its inputs, do one thing, and return a clear result or a clear error — the model reads error messages and will adapt to them, so a descriptive failure is more useful than a stack trace. Avoid side effects the caller can't see, and don't let a single tool quietly reach across half your infrastructure.

Testing it and connecting a client

You want two feedback loops. The first is direct: exercise the server without a model in the way, so you can confirm it lists the tools you expect and that calling a tool with known inputs returns what it should. Because the protocol is JSON-RPC over a transport, you can drive it programmatically or with the SDK's own tooling — this is where you catch schema mistakes and handler bugs cheaply, before a client is involved.

The second loop is end-to-end: register the server with a real client and watch the model use it. For a stdio server, that means adding it to the client's MCP configuration — pointing Claude Desktop, Claude Code, or Cursor at the command that launches your server. Then give the model a task that should trigger your tool and observe whether it discovers the tool, picks it, and calls it with sensible arguments. If it doesn't, the fix is almost always in the tool's name, description, or schema rather than the code.

This second loop is also your usability test. The model is your user, and how it reads your descriptions tells you whether the interface is clear. Ambiguous tool names, overlapping tools, or under-specified schemas show up immediately as the model hesitating, guessing arguments, or calling the wrong thing.

Hardening for production

A server that reads a local file for one developer and a server that executes actions against production systems for a team are different risk profiles. The moment your server can do something consequential, three concerns become non-negotiable. Authentication and authorisation: the server must know who is calling and what they're allowed to do — the AI client is not a trust boundary, so identity and permissions have to be enforced server-side, especially over HTTP transport. Scoping: give each tool the narrowest access it needs, so a compromised or misused tool has a small blast radius rather than the keys to everything.

The third is auditability. Because a model chooses when and how to call your tools, you need a durable record of what was called, by whom, with what arguments, and what happened — both to debug behaviour and to answer the security question of what the assistant actually did. Treat every tool that writes or acts as you would a privileged API endpoint: validate inputs, rate-limit, and prefer explicit, reversible actions over broad ones.

This is the part where a quick prototype and a shippable server diverge, and it's the work we focus on in our MCP server builds: taking a server from "it works on my machine against Claude Desktop" to something with real auth, least-privilege scoping, audit logging, and a deployment story your security team will sign off on. The SDK gets you a working server in an afternoon; the hardening is what makes it safe to point at production.