How to Build an MCP Server: A Developer Tutorial

The Model Context Protocol is an open standard, introduced by Anthropic in late 2024, for exposing tools, resources, and prompts to AI agents through a single client-server interface. Before it, every integration between an assistant and an external system was bespoke glue; MCP replaces that with one connector shape, so a server you write once works with every client that speaks the protocol. If you want the conceptual grounding first — what the primitives are and why the standard exists — start with our developer's primer on MCP. This guide assumes you're past the what and want the how: an actual server, running, connected to your editor, in four steps.

We'll build the same trivial tool in both official SDKs so you can see the shape, then centre on the TypeScript path because it's the one most web teams will ship. Everything here is minimal on purpose — the point is the skeleton you'll reuse, not the business logic you'll fill in.

Concretely, a server does three jobs: it declares a set of tools with typed input schemas, it runs a handler when the agent calls one, and it returns a result. The agent decides when to call — tools are model-controlled — so your job is to make each tool obvious enough that the model calls the right one with the right arguments. That framing matters for every decision below: you are writing an API whose primary consumer is a language model reading your descriptions and schemas, not a human reading your docs.

Start with an empty project and add the official SDK. For TypeScript you need Node 18 or newer; for Python, 3.10 or newer. Pick one — the two blocks below are the same starting point in each ecosystem.

A tool is three things bound together: a name, an input schema, and a handler. The schema is not optional decoration — it's the contract the agent reads to know which arguments are valid, and it's the validation that rejects a bad call before your handler ever runs. In the TypeScript SDK you register it on an McpServer with registerTool, passing a zod shape as the inputSchema. The handler returns a content array; return structuredContent alongside it so the agent receives a typed object, not just a string it has to re-parse.

The Python SDK collapses almost all of that into a decorator. FastMCP ships inside the official mcp package, so there's nothing extra to install. You write an ordinary function, annotate it with @mcp.tool(), and FastMCP derives the input schema from your type hints and the tool description from the docstring. Return a dict and it becomes structured content automatically.

The transport decides how the client reaches your server, and it's the one line at the bottom of the file that changes. There are two you'll actually use:

• stdio — the server runs as a local child process the client spawns, exchanging JSON-RPC over stdin and stdout. Nothing listens on a port, nothing is exposed to the network, and it starts on demand. This is the correct default for a server that runs on the same machine as the editor, which is most first servers. Both snippets above use it (StdioServerTransport in TS, the default in mcp.run()).
• Streamable HTTP — the server runs as a long-lived web service the client reaches over a URL. Use it when the server is remote, shared by multiple users, or deployed centrally rather than shipped to each developer's machine. In the TypeScript SDK you swap StdioServerTransport for the Streamable HTTP transport and mount it on an HTTP handler; in Python you pass transport="streamable-http" to mcp.run(). The tools and schemas you wrote don't change at all.

Rule of thumb: build and test locally over stdio, and only reach for HTTP when you have a concrete reason to run the server somewhere other than the user's laptop.

A stdio server isn't started by hand — the client launches it. You tell the client how to spawn it with a small JSON config that names a command and its arguments. This is the same shape across Claude Code, Cursor, and VS Code; here it is for a compiled TypeScript server and for the Python one:

Drop that into the client's MCP config (in Claude Code, claude mcp add or the project's .mcp.json; Cursor and VS Code have an equivalent settings file), restart the client, and it will connect, send tools/list, and show get_forecast as available. Ask the agent something that needs a forecast and you'll see it call the tool with arguments it inferred from your schema. For a full editor-by-editor walkthrough of the config files and the gotchas, see our guide on connecting an MCP server to VS Code and Windsurf.

Getting a server running is the easy part. Getting an agent to use it well is a design problem, and it comes down to a handful of rules that all point the same direction — the model can only be as good as the surface you hand it.

• Scope tools tightly. A few well-designed tools beat many vague ones. The model chooses what to call by reading names and descriptions, so get_forecast and search_locations are easier to route than a single overloaded weather tool with a mode flag. Every ambiguous description is a chance for the wrong call.
• Validate every input. The schema is your guardrail. When an argument is malformed, reject it with a clear message rather than letting the handler throw an opaque error — a good MCP client surfaces that message back to the model, which can then fix its own argument and retry without a human in the loop.
• Return structured data, not a text blob. This is the one that quietly decides fix quality downstream. Handing back a typed object (structuredContent in TS, a returned dict in Python) lets the agent read fields directly; handing back a paragraph forces it to re-parse prose and guess. The schema on the way out matters as much as the one on the way in.
• Handle errors as readable text. A recoverable failure should come back as a message the model can act on, not a stack trace. "Unknown city 'Xyz' — check spelling or call search_locations first" is a tool doing its job; a 500 is not.

This is the exact principle BugMojo's MCP server is built around. Its get_bug tool doesn't return a title and a free-text description — the thin context a human typed from memory. It returns the full reproduction the browser extension captured at the moment the bug happened: an rrweb session replay, the console log, the network waterfall, and the environment, as structured fields. An agent calling it isn't guessing what "checkout is broken" means; it's reading the actual failing request and the actual console error, the same inputs a senior engineer would ask for. That's the difference between a first-attempt fix and an "almost right" one — and it's a direct consequence of treating the tool's output schema as context design, not an afterthought. If you want to see that play out end to end, read how AI agents actually fix bugs with MCP, and for the server's own architecture — its tools, transport, and the polymorphic agent assignee — see how the BugMojo MCP server works. When you're choosing servers to connect rather than build, our roundup of the best MCP servers for developers is the companion piece.