Skip to content
MCP Shelf

Build and run your own

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. 1. Set up

    Install the SDK for your language.

  2. 2. Register tools

    A name, a description, inputs and a function.

  3. 3. Test it

    List and call tools with MCP Inspector.

  4. 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 appClaude, Cursor, VS Code
stdin and stdout
Your serveradd_todo, list_todos
runs the function
Your codeAn API, a database, a file
The app starts your server, reads its tool list, and calls a tool when your request needs it.
TypeScriptPython
Package@modelcontextprotocol/server 2.x, with zodmcp 2.x, installed as mcp[cli]
You needNode.js 20 or newerPython 3.10 or newer, and uv
Inputs come fromA zod schemaType hints and the docstring

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 serverSafe
TypeScriptconsole.log("started")console.error("started")
Pythonprint("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 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 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, Cursor, VS Code (which uses "servers" instead of "mcpServers"), Codex (TOML) and 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 and 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 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.

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.

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 compares the two.

Plant Your First Pea

Every server on the shelf has a tab with the exact config for your app.

Browse servers

For bots & AI agents

Machine-readable versions of this guide and MCP Shelf. Fetch these instead of parsing this page.

This guide (.md)llms.txtllms-full.txtai.txtFull catalog (.md)API specMCP serverMCP manifestDeveloper docs