# Build your first MCP server in TypeScript or Python

Level 4: Build · 15 min · Updated 19 November 2026 · Path: Build MCP servers

By the end 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](https://ai-powered.com/academy/glossary/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.

*Diagram: 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.

**The one rule for local servers**

A local (stdio) server talks to the app over standard output. Print anything else there and you break the conversation. Never use `console.log()` in TypeScript or `print()` in Python; log to standard error instead (`console.error()`, or Python's `logging`, which writes to stderr by default).

## TypeScript

**Steps**

1. Create the project and install the SDK:
   ```shell
   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`:
   ```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`.

```typescript
#!/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:

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

Save this as `word_tools.py`:

```python
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:

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

Then call one:

```shell
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:

```shell
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:

```json
{
  "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](https://ai-powered.com/academy/connect-mcp-servers/claude-desktop) covers checking and logs.

**Try it**

Ask Claude "How many words are in this sentence?" and approve the [tool call](https://ai-powered.com/academy/glossary/tool-call). Then change the description in your code to something vague, rebuild, and ask again: you'll see how much the model leans on those words.

## Key takeaways

- 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

- Replace `count_words` with one real task your team asks about, backed by an API you already have.
- [Publish it to the MCP Registry](https://ai-powered.com/academy/build-mcp-servers/publish-to-mcp-registry) so apps and directories can find it.
- Read the [security checklist](https://ai-powered.com/academy/build-mcp-servers/mcp-server-security-checklist) before you share it with anyone.

## Sources

Official documentation, checked on 19 November 2026:

- [Build an MCP server (modelcontextprotocol.io)](https://modelcontextprotocol.io/docs/develop/build-server)
- [MCP architecture overview (modelcontextprotocol.io)](https://modelcontextprotocol.io/docs/learn/architecture)
- [Connect to local MCP servers (modelcontextprotocol.io)](https://modelcontextprotocol.io/docs/develop/connect-local-servers)

Next lesson: [Migrate your MCP server to the 2026-07-28 spec](https://ai-powered.com/academy/build-mcp-servers/migrate-to-2026-07-28)
