Build an MCP server
Last reviewed October 23, 2026
This page gets you to a working MCP server with one tool, in TypeScript or Python, that any MCP client can start and call. Keep it that small until it works end to end. The first problems you meet will be wiring problems (the wrong path, a stray print, a client that cannot find your program), and wiring is far easier to debug with one tool than with twenty.
Which version of the protocol?
Build against specification 2026-07-28, the current one (specification). It is stateless: every request carries its own protocol version and the client's capabilities, so there is no handshake to get wrong and no session to lose. Roots, Sampling and Logging are deprecated, and so is the old HTTP+SSE transport (changelog).
Plenty of clients still speak the 2025 version. You do not have to choose: the current SDKs answer both, as long as you start the server the way the examples below do.
Tools, resources and prompts: what goes where?
A tool is a function the model decides to call: search the tickets, create an invoice, run the query. A resource is data the application decides to hand the model, such as a file or a record, addressed by a URI. A prompt is a template a person picks, usually from a slash-command menu (server features).
Start with tools. They are what agents use, and every client supports them. Add resources when you have data a person will want to attach on purpose, and prompts when you notice people typing the same long request again and again.
Which SDK?
Use an official SDK rather than implementing the protocol yourself. The best supported are TypeScript, Python, C#, Go, Rust and Ruby; Java is next, then Swift, PHP and Kotlin, each at github.com/modelcontextprotocol/<language>-sdk (SDK list). TypeScript and Python have the most examples and the most answered questions, which counts for a lot when something odd happens on a Friday afternoon.
stdio or Streamable HTTP?
A server that runs on the user's own machine uses stdio: the client starts your program and the two talk over standard input and output. That makes stdout sacred. Print anything else to it, a debug line or a progress bar, and you corrupt the message stream; send logs to stderr instead.
A server that runs somewhere else uses Streamable HTTP: each message is a POST to one endpoint, and the reply comes back as JSON or a short-lived event stream (transports). A remote server also needs authorization and some care about who can reach it; the security step covers both. If you are unsure, start with stdio. You can add HTTP later without changing your tools.
A minimal server in TypeScript
Version 2 of the TypeScript SDK lives in @modelcontextprotocol/server (2.4.0 when this was written) and needs Node 20 or later (TypeScript SDK). In an empty folder:
npm init -y
npm pkg set type=module
npm install @modelcontextprotocol/server zodimport { McpServer } from "@modelcontextprotocol/server";
import { serveStdio } from "@modelcontextprotocol/server/stdio";
import * as z from "zod/v4";
// A new server for each client connection.
function createServer() {
const server = new McpServer({ name: "add-numbers", version: "1.0.0" });
server.registerTool(
"add",
{
description: "Add two numbers",
inputSchema: z.object({ a: z.number(), b: z.number() }),
},
async ({ a, b }) => ({
content: [{ type: "text", text: String(a + b) }],
}),
);
return server;
}
serveStdio(createServer, {
onerror: (error) => console.error("add-numbers error:", error),
});
console.error("add-numbers running on stdio");Two things here trip people up. serveStdio takes a function that builds a server, not a server, because it may need a fresh one per connection. And it is why this server answers both protocol versions. If you connect a transport yourself with server.connect(new StdioServerTransport()), the code builds, but only clients on the 2025 protocol can talk to it (official tutorial). Notice also that the only thing printed goes to console.error, which is stderr.
A minimal server in Python
The Python SDK is the mcp package (2.3.0 when this was written) and needs Python 3.11 or later. Version 2 renamed FastMCP to MCPServer, and the old import no longer exists (what changed in v2). The separate fastmcp package on PyPI is a community project, not this SDK.
The SDK's own instructions use uv, which creates the project, keeps its dependencies in a lock file and runs it without your activating anything:
uv init add-numbers
cd add-numbers
uv add "mcp[cli]"from mcp.server import MCPServer
mcp = MCPServer("add-numbers")
@mcp.tool()
def add(a: int, b: int) -> int:
"""Add two numbers."""
return a + b
if __name__ == "__main__":
mcp.run(transport="stdio")uv run server.pyWithout uv, a virtual environment and pip do the same job:
python3 -m venv .venv
.venv/bin/pip install "mcp[cli]"
.venv/bin/python server.pyThe SDK reads the type hints and the docstring to build the tool's input schema and description, so both are part of your interface, not decoration. Use the logging module for anything you want to see; it writes to stderr.
Write tool descriptions for a model
The model chooses your tool from its name and description alone, so they deserve more care than most docstrings get. Name tools with a verb and an object (create_invoice, not invoice). Say in the description what the tool changes, not only what it returns, and give each input a unit or a format where one applies. Keep descriptions plain and factual; a description that tells the model how to behave reads as an injection attempt to clients and to safety scans, this site's included.
Building something else? See the guides to a skill and a plugin or marketplace.