How to Build Your First MCP Server

The official MCP SDK ships in TypeScript and Python — both are supported and well-maintained. Pick whichever language you reach for first when scripting. The example below uses TypeScript via npx; for Python, swap to `uv add mcp` and the same shape applies with idiomatic Python decorators.

# TypeScript / Node
mkdir my-first-mcp && cd my-first-mcp
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript tsx @types/node
npx tsc --init

# Python
uv init my-first-mcp && cd my-first-mcp
uv add mcp

Resist the urge to expose ten tools on day one. Start with a single, well-described tool that does one thing — agents work better with clear, narrow tools than with sprawling APIs. The example below exposes a single `echo` tool that returns whatever string the agent passes in.

// src/index.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "my-first-mcp",
  version: "0.1.0",
});

server.tool(
  "echo",
  "Returns whatever string you send it.",
  { message: z.string() },
  async ({ message }) => ({
    content: [{ type: "text", text: `Echo: ${message}` }],
  })
);

const transport = new StdioServerTransport();
await server.connect(transport);

The MCP Inspector is a browser-based UI that connects to your server over stdio, lists its tools, and lets you call them with arbitrary inputs. Run it before touching Claude Desktop — if the Inspector cannot see the tool, no client will either.

# In one terminal:
npx tsx src/index.ts

# In another:
npx @modelcontextprotocol/inspector npx tsx src/index.ts
# Open the printed URL, click "List Tools", call "echo" with any input.

Once the Inspector confirms the tool works, register the server in claude_desktop_config.json. Use the absolute path to your built server so Claude can launch it from any working directory. Fully restart Claude — the new tool appears in the hammer icon.

// claude_desktop_config.json
{
  "mcpServers": {
    "my-first-mcp": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/my-first-mcp/src/index.ts"]
    }
  }
}

Ask Claude: "Use the echo tool to say hello." Claude should call your tool with `{message: "hello"}` and return the response. If it does not call the tool, the manifest is wrong; if it calls the tool but fails, your handler is throwing — check the MCP logs in Settings → Developer.

Tool descriptions are how the model decides when to call you — write them like API docs, not like changelogs. Add a second tool only after the first feels reliable. When you are ready, package the server (npm publish or pip publish) so others can install it with one snippet.