How to build an MCP server (TypeScript and Python examples)
Build an MCP server step by step with the official TypeScript and Python SDKs: define tools, run over stdio, connect it to Claude Code, avoid common mistakes.
A team keeps pasting the same internal data into Claude Code: feature flag states, on-call schedules, service owners. Each answer is one API call away, but the agent can't make it. An MCP server lets it.
This guide builds a small server in TypeScript and Python, following the official build-server guide and the MCP architecture docs, checked on 16 November 2026.
What you're building
MCP uses a client-server architecture. An MCP host, such as Claude Code, Claude Desktop, or VS Code, starts one MCP client per server. Your server provides any of three primitives:
| Primitive | What it is | Example |
|---|---|---|
| Tools | Functions the model can call | get_service_owner(service) |
| Resources | Data the application can read | A runbook file |
| Prompts | Reusable prompt templates | "Summarize this incident" |
Messages are JSON-RPC 2.0. Clients discover tools with tools/list and run them with tools/call. Local servers usually use the stdio transport; remote servers use Streamable HTTP.
Most servers only need tools. That's what we'll build.
TypeScript
Install the SDK and zod:
npm install @modelcontextprotocol/server zod
npm install -D @types/node typescript
src/index.ts:
import { McpServer } from "@modelcontextprotocol/server";
import { serveStdio } from "@modelcontextprotocol/server/stdio";
import { z } from "zod";
const OWNERS: Record<string, string> = {
payments: "Payments team (#payments-oncall)",
search: "Discovery team (#search)",
};
// serveStdio calls this whenever it needs an instance,
// so it must return a fresh server each time.
function createServer() {
const server = new McpServer({ name: "service-owners", version: "1.0.0" });
server.registerTool(
"get_service_owner",
{
description:
"Look up which team owns a service and how to reach them. " +
"Use before changing code in a service you don't own.",
inputSchema: z.object({
service: z.string().describe("Service name, e.g. payments"),
}),
},
async ({ service }) => ({
content: [
{ type: "text", text: OWNERS[service] ?? `No owner found for ${service}` },
],
}),
);
return server;
}
serveStdio(createServer, {
onerror: (error) => console.error("Server error:", error),
});
console.error("service-owners MCP server running on stdio");
The official guide notes that serveStdio negotiates the protocol revision with each client, so one server works with both newer clients and those using the older initialize handshake.
Python
uv add "mcp[cli]"
owners.py:
from mcp.server import MCPServer
mcp = MCPServer("service-owners")
OWNERS = {
"payments": "Payments team (#payments-oncall)",
"search": "Discovery team (#search)",
}
@mcp.tool()
async def get_service_owner(service: str) -> str:
"""Look up which team owns a service and how to reach them.
Use before changing code in a service you don't own.
Args:
service: Service name, e.g. payments
"""
return OWNERS.get(service, f"No owner found for {service}")
if __name__ == "__main__":
mcp.run(transport="stdio")
Per the guide, MCPServer uses type hints and docstrings to generate the tool definitions.
The one rule that breaks servers
The MCP docs are emphatic: for stdio servers, never write to stdout. print() in Python and console.log() in Node write to stdout and corrupt the JSON-RPC messages. Log to stderr, as the TypeScript example does with console.error.
Connect it to Claude Code
claude mcp add service-owners -- node build/index.js
# or
claude mcp add service-owners -- uv run owners.py
Add --scope project to write it to .mcp.json so the whole team gets it. Then ask Claude something that needs the tool and check /mcp to see it connected. More in Claude Code MCP setup.
Writing good tools
- Descriptions are for the model. They decide when the tool gets called. Say what it does and when to use it.
- Few, focused tools. Anthropic's context engineering guidance warns that bloated tool sets lead to ambiguous choices.
- Return compact output. Every result lands in the context window.
- Read-only first. Tools that change things need careful permissions; see MCP security.
- Clear errors. Return a message the model can act on, not a stack trace.
Testing
The MCP project provides the MCP Inspector, a development tool for exercising servers and clients. Use it to call tools directly before connecting an agent.
Where Lockstep fits
Lockstep is an MCP server for one specific kind of context: your team's approved decisions. It captures them from PRDs, Slack, and pull requests, routes each to its owner for approval, and serves them to any MCP client. Claude Code sessions also get them automatically in a briefing.
See how it works.
Sources checked 16 November 2026
- https://modelcontextprotocol.io/docs/develop/build-server
- https://modelcontextprotocol.io/docs/learn/architecture
- https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
Related reading
For protocols beyond MCP, see MCP vs A2A vs ACP. For servers worth installing, see the best MCP servers for engineering teams. For when MCP is worth it over an API, see MCP vs API. For connecting agents to each other, see A2A protocol example.
Frequently asked questions
- What is an MCP server?
- A program that provides context to AI applications over the Model Context Protocol: tools the model can call, resources it can read, and prompts. An MCP host such as Claude Code creates one MCP client per server it connects to.
- How do I build an MCP server in TypeScript?
- Install @modelcontextprotocol/server and zod, create an McpServer with a name and version, register tools with registerTool (a name, a description, a zod input schema, and an async handler), then serve it with serveStdio. The official build-server guide walks through a full example.
- How do I build an MCP server in Python?
- Add the mcp package with uv add "mcp[cli]", create an MCPServer instance, decorate async functions with @mcp.tool(), and call mcp.run(transport="stdio"). Type hints and docstrings generate the tool definitions.
- Why does my stdio MCP server break?
- The most common cause is writing to stdout. The MCP docs warn that print() in Python or console.log() in Node writes to stdout and corrupts the JSON-RPC messages. Log to stderr instead.
- How do I connect my MCP server to Claude Code?
- For a local stdio server, run claude mcp add with a name, then a double dash and the command that starts it, for example claude mcp add weather -- node build/index.js. Use --scope project to write it to .mcp.json for the team.
Keep reading