---
title: "How to Build an MCP Server in TypeScript or Python"
url: "https://mcpshelf.co/guides/build-an-mcp-server"
description: "Build a working MCP server in TypeScript or Python with the official SDKs, test it with MCP Inspector, and add it to Claude, Cursor or VS Code. Tested code."
updated: "2026-11-10"
site: "MCP Shelf"
---

# How to build your own MCP server

By Sophie Filer · Updated 10 Nov 2026

An MCP server is a small program that tells an AI app which tools it offers, then runs them when asked. With the official SDKs, a working server with two tools is about 40 lines of TypeScript or Python. This guide builds one, tests it, and plugs it into your app.

- **TypeScript:** `@modelcontextprotocol/server`, Node.js 20+
- **Python:** `mcp` 2.x, Python 3.10+
- **Size:** About 40 lines for two tools
- **Test with:** MCP Inspector

**At a glance:**

1. **Set up.** Install the SDK for your language.
2. **Register tools.** A name, a description, inputs and a function.
3. **Test it.** List and call tools with MCP Inspector.
4. **Add it.** Point your app at the command.

## What you will build

A to-do list server with two tools: `add_todo` and `list_todos`. It is small on purpose, so the parts that matter stay visible: a tool name, a description the model reads, an input schema, and the function that does the work. Swap the function body for a call to your own API or database and you have a real server.

Your app (Claude, Cursor, VS Code) → stdin and stdout → Your server (add_todo, list_todos) → runs the function → Your code (An API, a database, a file)

_The app starts your server, reads its tool list, and calls a tool when your request needs it._

|  | TypeScript | Python |
| --- | --- | --- |
| Package | `@modelcontextprotocol/server` 2.x, with zod | `mcp` 2.x, installed as `mcp[cli]` |
| You need | Node.js 20 or newer | Python 3.10 or newer, and uv |
| Inputs come from | A zod schema | Type hints and the docstring |

> **Watch out:** Following an older tutorial? The SDKs moved on in 2026. In Python, `FastMCP` is now `MCPServer` and `from mcp.server.fastmcp import FastMCP` fails on `mcp` 2.x. In TypeScript, new servers use `@modelcontextprotocol/server` and `serveStdio` instead of `@modelcontextprotocol/sdk` with `StdioServerTransport`.

## TypeScript: set up the project

Terminal:

```
mkdir todos && cd todos
npm init -y
npm install @modelcontextprotocol/server zod
npm install -D typescript @types/node
mkdir src
```

In package.json, add `"type": "module"` and a build script, `"build": "tsc"`. Then create tsconfig.json:

tsconfig.json:

```
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./build",
    "rootDir": "./src",
    "strict": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*"]
}
```

## TypeScript: write the server

src/index.ts:

```
import { McpServer } from "@modelcontextprotocol/server";
import { serveStdio } from "@modelcontextprotocol/server/stdio";
import { z } from "zod";

// Kept in memory, so the list empties when the app restarts the server.
const todos: string[] = [];

function createServer() {
  const server = new McpServer({ name: "todos", version: "1.0.0" });

  server.registerTool(
    "add_todo",
    {
      description: "Add an item to the user's to-do list",
      inputSchema: z.object({
        text: z.string().min(1).describe("What needs doing"),
      }),
    },
    async ({ text }) => {
      todos.push(text);
      return { content: [{ type: "text", text: `Added. ${todos.length} item(s) on the list.` }] };
    },
  );

  server.registerTool(
    "list_todos",
    {
      description: "List every item on the user's to-do list",
      inputSchema: z.object({}),
    },
    async () => {
      const text = todos.length ? todos.map((t, i) => `${i + 1}. ${t}`).join("\n") : "The list is empty.";
      return { content: [{ type: "text", text }] };
    },
  );

  return server;
}

serveStdio(createServer);
console.error("todos server running on stdio");
```

- `registerTool` takes the tool’s name, its description and input schema, and the function to run. The description is what the model reads to decide when to call it, so write it for the model.
- `.describe()` on each input field becomes that field’s help text.
- `serveStdio` takes a function that builds the server, not a server. It may call it more than once, so build a fresh `McpServer` inside it each time. It also answers both current apps and ones still on the 2025 version of the protocol.
- A tool returns a list of content parts. Text is the usual one.

Build it with `npm run build`. The server is now `build/index.js`.

## Python: the same server

Terminal:

```
uv init todos && cd todos
uv add "mcp[cli]"
```

todos.py:

```
from mcp.server import MCPServer

mcp = MCPServer("todos")

# Kept in memory, so the list empties when the app restarts the server.
todos: list[str] = []

@mcp.tool()
def add_todo(text: str) -> str:
    """Add an item to the user's to-do list.

    Args:
        text: What needs doing
    """
    todos.append(text)
    return f"Added. {len(todos)} item(s) on the list."

@mcp.tool()
def list_todos() -> str:
    """List every item on the user's to-do list."""
    if not todos:
        return "The list is empty."
    return "\n".join(f"{i}. {t}" for i, t in enumerate(todos, 1))

if __name__ == "__main__":
    mcp.run(transport="stdio")
```

The Python SDK builds each tool’s schema from the function’s type hints and its docstring, so `text: str` becomes a required string input and the docstring becomes the description. `mcp.run(transport="stdio")` starts the server; `uv run todos.py` runs it.

## The one rule: nothing on stdout

A local server talks to the app through standard output. Anything else you print there lands in the middle of the protocol messages and breaks the connection, usually with a confusing JSON error in the app.

|  | Breaks the server | Safe |
| --- | --- | --- |
| TypeScript | console.log("started") | console.error("started") |
| Python | print("started") | logging.getLogger(__name__).info("started") |

Both write to standard error instead, which apps show in their MCP logs. A server that speaks HTTP instead of stdio can print freely.

## Test it with MCP Inspector

Before adding it to an app, check that it starts and that the tools look right. [MCP Inspector](https://mcpshelf.co/servers/mcp-inspector) has a command-line mode that lists tools and calls one, with no browser needed:

List the tools, then call one:

```
# TypeScript
npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list
npx @modelcontextprotocol/inspector --cli node build/index.js \
  --method tools/call --tool-name add_todo --tool-arg text="Buy peas"

# Python
npx @modelcontextprotocol/inspector --cli uv run todos.py --method tools/list
```

You should see both tools with their descriptions and input schemas, and the call should answer "Added. 1 item(s) on the list." Add `--protocol-era modern` to test the 2026 handshake as well as the older one. Run it without `--cli` to click through the same checks in a browser; [Testing an MCP server](https://mcpshelf.co/guides/test-an-mcp-server) walks through that.

## Add it to your app

Your server is a local command, so it goes in your app like any other. Use absolute paths, because the app does not start in your project folder.

Claude Desktop, Cursor and other "mcpServers" apps:

```
{
  "mcpServers": {
    "todos": {
      "command": "node",
      "args": ["/absolute/path/to/todos/build/index.js"]
    }
  }
}
```

The Python version:

```
{
  "mcpServers": {
    "todos": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/todos", "run", "todos.py"]
    }
  }
}
```

Claude Code, in one command:

```
claude mcp add todos -- node /absolute/path/to/todos/build/index.js
```

Then restart the app and ask "add buy peas to my to-do list". The app guides show where the file goes: [Claude Desktop](https://mcpshelf.co/guides/claude-desktop), [Cursor](https://mcpshelf.co/guides/cursor), [VS Code](https://mcpshelf.co/guides/vs-code) (which uses "servers" instead of "mcpServers"), [Codex](https://mcpshelf.co/guides/codex) (TOML) and [JetBrains](https://mcpshelf.co/guides/jetbrains). If the app cannot find `node` or `uv`, use the full path from `which node` or `which uv`.

## Make it a good server

- Write descriptions for the model, not for people. Say what the tool does, when to use it, and what each input means, with an example value. A model picks tools by reading these.
- Keep tools few and specific. Five clear tools beat thirty overlapping ones; every tool you add takes room in the model’s context.
- Return errors as text the model can act on, such as "No project called X. Call list_projects to see the names." A thrown exception tells it far less.
- Read keys from environment variables, never from the code. Users then set them in the "env" block of their config.
- Make tools that change things obvious from their names, such as `delete_todo`, so people know what they are approving.

## Next steps

- Share it: publish to npm or PyPI and anyone can run it with `npx -y your-package` or `uvx your-package`, with nothing to clone or build.
- Run it remotely: both SDKs can serve over Streamable HTTP instead of stdio, so apps like [Claude on the web](https://mcpshelf.co/guides/claude-connectors) and [ChatGPT](https://mcpshelf.co/guides/chatgpt) can reach it by URL. Add sign-in before you put real data behind it.
- Package it: a Dockerfile lets people run it [in Docker](https://mcpshelf.co/guides/docker-mcp-servers) without installing Node.js or Python.
- Get it listed: once it has a public repository and a README with install steps, you can [suggest it for MCP Shelf](https://mcpshelf.co/submit).

## Questions

### Which language should I build an MCP server in?

The one you already know. TypeScript and Python have the most examples, and both official SDKs are shown here. There are official SDKs for Java, Kotlin, C#, Go, Ruby and Rust too.

### Do I need an AI model or API key to build an MCP server?

No. The server never calls a model. The app you connect it to brings the model; the server only describes its tools and runs them when asked.

### Why does my app say my server failed or closed?

Usually something was printed to standard output, the path in the config is relative, or the app cannot find `node` or `uv`. Run the exact command from your config in a terminal, and see [Fixing MCP server errors](https://mcpshelf.co/guides/mcp-server-errors).

### Should my server use stdio or HTTP?

Stdio for something that runs on the user’s own computer and touches their files or apps. HTTP for a service you host for others, which apps reach by URL. [Remote or local](https://mcpshelf.co/guides/remote-vs-local-mcp-servers) compares the two.

---

From [MCP Shelf](https://mcpshelf.co/): A short shelf of MCP servers that are worth installing. Index for agents: https://mcpshelf.co/llms.txt

