How do you build a simple MCP server?

What do you need before you start?

An MCP server is a program that offers tools, resources or prompts to an AI application over the Model Context Protocol; the plain terms thread explains the parts. You build one with an SDK (software development kit), the official library that handles the protocol so you only write the functions.

Check the version first, because the SDKs changed in 2026. As of the docs read on 16 October 2026, the Python SDK README says v2 "is the current stable release line" and supports the 2026-07-28 MCP specification. It also warns that pip install mcp now installs 2.x, so older tutorials that import FastMCP were written for v1. The official build-a-server tutorial lists these requirements:

	Python	TypeScript
Runtime	Python 3.10 or higher	Node.js 20 or higher
SDK	mcp 2.0.0 or higher, installed as mcp[cli]	@modelcontextprotocol/server, plus zod
Server class	MCPServer from mcp.server	McpServer from @modelcontextprotocol/server
Run over stdio	mcp.run(transport="stdio")	serveStdio(createServer, ...)
Quick test	uv run mcp dev server.py	npx @modelcontextprotocol/inspector --cli node build/index.js --protocol-era modern --method tools/list

The steps below use Python. The tutorial also covers Java, Kotlin, C#, Ruby, Rust and Go.

Step by step: a one-tool server in Python

These steps follow the official tutorial and the SDK README. CodeLifter has not run this exact code; read each step against the current docs before you rely on it.

1. Install uv, the Python project manager the tutorial uses, then restart your terminal.

2. Create the project:

   uv init demo-server
   cd demo-server
   uv venv
   source .venv/bin/activate
   uv add "mcp[cli]"
   

   On Windows, activate with .venv\Scripts\activate instead.

3. Create server.py with one tool. This is the README's example plus the tutorial's run line:

   from mcp.server import MCPServer
   
   mcp = MCPServer("Demo")
   
   @mcp.tool()
   def add(a: int, b: int) -> int:
       """Add two numbers."""
       return a + b
   
   if __name__ == "__main__":
       mcp.run(transport="stdio")
   

   The type hints become the tool's input schema and the docstring becomes its description. The README makes the point directly: "a: int, b: int is the schema".

4. Open it in the Inspector with uv run mcp dev server.py. The README says that calling add with a=1 and b=2 returns 3.

5. Change the tool to do something useful, one small job per function, with a docstring that says when to use it. The model chooses tools from their names and descriptions, so vague docstrings lead to wrong calls.

Why does a stdio server break when you print?

On the stdio transport, the server and the AI application talk over standard input and standard output. The tutorial is blunt: "Never write to stdout. Writing to stdout will corrupt the JSON-RPC messages and break your server." In Python that rules out print(). Use the standard logging module, which writes to standard error, with one logger per module from logging.getLogger(__name__). In TypeScript, use console.error() instead of console.log(). HTTP servers do not have this problem.

How do you connect it to Claude Desktop?

The tutorial uses Claude Desktop as the host. Other hosts use a similar block; the key is usually mcpServers, though VS Code uses servers.

1. Open ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, or $env:AppData\Claude\claude_desktop_config.json on Windows (PowerShell). Create it if it does not exist.

2. Add the server with an absolute path:

   {
     "mcpServers": {
       "demo": {
         "command": "uv",
         "args": ["--directory", "/ABSOLUTE/PATH/TO/demo-server", "run", "server.py"]
       }
     }
   }
   

3. If the app cannot find uv, put the full path from which uv (or where uv on Windows) in command.

4. Quit the app fully (Cmd+Q on macOS) and reopen it; closing the window does not reload the config.

5. If the tool does not appear, read ~/Library/Logs/Claude/mcp.log and mcp-server-demo.log on macOS. The second file holds your server's standard error output.

What should you check before you share it?

A server runs with the permissions of whoever starts it. The MCP security best practices recommend "a progressive, least-privilege scope model", and the tools specification tells clients to treat tool annotations as untrusted unless they come from trusted servers. Before you publish:

1. Make each tool do one narrow thing, and reject inputs outside what it needs (paths outside one folder, for example).
2. Read secrets from environment variables, never from the code; the API keys thread covers why.
3. Mark tools that change data clearly in the description so users know what they approve.
4. Add a licence and a README with the exact install line.

The CodeLifter MCP directory shows how published servers document their tools and access, and the Filesystem sandbox thread shows how users will try to contain yours.

Short version

• Install the official SDK: uv add "mcp[cli]" for Python (v2, MCPServer) or @modelcontextprotocol/server for TypeScript.
• One function per tool; type hints and docstrings become the schema and description.
• Never print to stdout on a stdio server; log to stderr.
• Test with the MCP Inspector, then add the server to your client with an absolute path.
• Scope every tool narrowly before anyone else installs it.