Skip to content

Build your first MCP server in TypeScript or Python

Level 4: Build. About 15 min. Checked on 19 November 2026 against MCP spec 2026-07-28, @modelcontextprotocol/server 2.4.0, Python mcp 2.3.0.
Stage 4 of 4: Build

In this lesson you'll build a one-tool MCP server in TypeScript or Python, test it with the MCP Inspector and use it from Claude.

Say your team keeps answering the same question from the same internal data: "what's the status of order 4417?", "who owns this service?". You could paste the answer into Claude every time. Or you could write a tiny program that Claude can ask directly. That program is an MCP server, and the first one takes about fifteen minutes.

We'll build the smallest useful server: one tool, count_words, that counts the words in some text. It's deliberately boring, so you can see the shape of a server without any business logic in the way. Swap in your own logic afterwards.

Buildan MCP SDKTestMCP InspectorSecurethe checklistPublishMCP Registry
From code to a server people can find. Build a server with an MCP SDK, test it with the MCP Inspector, check it against the security list, then publish its metadata to the MCP Registry.

We ran both versions below on 19 November 2026 and listed and called the tool with the MCP Inspector. What we used: Node.js 24.21 with @modelcontextprotocol/server 2.4.0, zod 4.6.7 and TypeScript 7.0.2; Python 3.11.1 with mcp 2.3.0 and uv 0.13.0; MCP Inspector 2.13.0. The official guide asks for Node.js 20 or later, or Python 3.10 or later with Python SDK 2.0.0 or later.

TypeScript

  1. Create the project and install the SDK:
    mkdir word-tools && cd word-tools
    npm init -y
    npm install @modelcontextprotocol/server zod
    npm install -D @types/node typescript
    npm pkg set type=module scripts.build=tsc
    mkdir src
  2. Add tsconfig.json:
    {
      "compilerOptions": {
        "target": "ES2022",
        "module": "Node16",
        "moduleResolution": "Node16",
        "types": ["node"],
        "outDir": "./build",
        "rootDir": "./src",
        "strict": true,
        "esModuleInterop": true,
        "skipLibCheck": true
      },
      "include": ["src/**/*"]
    }
  3. Write src/index.ts (below), then build it with npm run build.
#!/usr/bin/env node
import { McpServer } from "@modelcontextprotocol/server";
import { serveStdio } from "@modelcontextprotocol/server/stdio";
import { z } from "zod";

// serveStdio calls this whenever it needs a server, so return a new one each time.
function createServer() {
  const server = new McpServer({ name: "word-tools", version: "1.0.0" });

  server.registerTool(
    "count_words",
    {
      description: "Count the words in a piece of text",
      inputSchema: z.object({
        text: z.string().describe("The text to count"),
      }),
      annotations: { readOnlyHint: true },
    },
    async ({ text }) => {
      const words = text.trim() ? text.trim().split(/\s+/).length : 0;
      return { content: [{ type: "text", text: `${words} words` }] };
    },
  );

  return server;
}

serveStdio(createServer, {
  onerror: (error) => console.error("word-tools error:", error),
});
// Log to stderr: stdout carries the protocol messages.
console.error("word-tools running on stdio");

Three lines in there matter more than they look:

  • The description and each .describe() are what the model reads to decide when and how to call your tool. Write them for the model, the way you'd brief a colleague.
  • readOnlyHint: true tells apps the tool changes nothing. ChatGPT, for example, asks the user to confirm every tool that lacks it.
  • The guide uses serveStdio because it answers both clients on the 2026-07-28 protocol and older ones. A server wired by hand with server.connect(new StdioServerTransport()) only serves the older ones.

Python

Python is shorter, because the SDK reads your function's name, type hints and docstring to describe the tool:

uv init word-tools && cd word-tools
uv add "mcp[cli]"

Save this as word_tools.py:

import logging

from mcp.server import MCPServer

# Log to stderr: in a stdio server, stdout carries the protocol messages.
logging.basicConfig(level=logging.INFO)

mcp = MCPServer("word-tools")


@mcp.tool()
def count_words(text: str) -> str:
    """Count the words in a piece of text.

    Args:
        text: The text to count
    """
    return f"{len(text.split())} words"


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

Keep the docstring accurate: it becomes the tool's description.

Test it before any app sees it

The MCP Inspector starts your server and talks to it the way an app would. List the tools:

npx @modelcontextprotocol/inspector --cli node build/index.js --protocol-era modern --method tools/list

Then call one:

npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/call --tool-name count_words --tool-arg 'text=hello there world'

For Python, replace node build/index.js with uv run word_tools.py. You should get back 3 words. The Inspector defaults to the older (legacy) protocol era, so run tools/list once with --protocol-era modern and once without to check both.

Use it from Claude

In Claude Code, one command, with the full path to your build:

claude mcp add word-tools -- node /ABSOLUTE/PATH/TO/word-tools/build/index.js

In Claude Desktop, add this to claude_desktop_config.json and restart the app:

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

Claude Desktop may need the full path to uv or node; find it with which uv (macOS, Linux) or where uv (Windows). The Claude Desktop lesson covers checking and logs.

In short

  • A server is a list of tools: a name, a description written for the model, an input schema and a function.
  • Local servers talk over stdio: log to stderr, never stdout.
  • Test with the MCP Inspector first, then add it to a real app.

What to try next

Share this lesson

Lesson 1 of 6 in this path

Words used in this lesson

Sources

Official documentation, checked on 19 November 2026. Products change: if a step differs, the source has the current version.

Get the next lesson

New Academy lessons are announced in the weekly AI-Powered email.