How to Build an MCP Server (TypeScript, End to End)

To build an MCP server you need four things: a Node project with @modelcontextprotocol/server and zod installed, an McpServer instance, one or more tools registered with registerTool, and a transport connected at the end of main(). That is the whole shape. Everything below is detail on getting each piece right — and on two mistakes the protocol docs single out for their own warnings: logging to stdout, and exposing too many tools.

What an MCP server actually is

The Model Context Protocol is an open standard for connecting AI applications to external systems — the official docs describe it as "a USB-C port for AI applications." A server exposes three kinds of capability: tools (functions the model can call), resources (file-like data the client can read), and prompts (reusable templates). Most servers people actually ship are tools-only, and that is what I'll build here.

The part that surprises people coming from plugin-style integrations: there is nothing model-specific in your code. You are writing a JSON-RPC service. The client — Claude Code, Cursor, VS Code, ChatGPT — handles the model side. Your job is to describe capabilities precisely and return text.

I've spent a lot of time on the client side of this problem. ContextZero, the VS Code extension I maintain, exists because every agent stores its rules, memory and skills somewhere different — Claude Code, Cursor, Kiro, Antigravity, the AGENTS.md standard. MCP is the opposite lesson: one protocol, and the fragmentation disappears. Worth internalising before you write a line of code.

Set up the project

mkdir weather-mcp && cd weather-mcp
npm init -y
npm install @modelcontextprotocol/server zod
npm install -D @types/node typescript
mkdir src && touch src/index.ts

Two things in package.json matter. "type": "module" — the SDK is ESM. And a bin entry, because stdio servers are launched as executables by the client:

{
  "type": "module",
  "bin": { "weather": "./build/index.js" },
  "scripts": { "build": "tsc && chmod 755 build/index.js" },
  "files": ["build"]
}

Target Node 20 or higher, and compile to ES2022 with Node16 module resolution. If you skip the build step and point a client at your TypeScript source, it will fail to start with an error that has nothing to do with MCP.

Register a tool

registerTool takes three arguments: the tool name, a config object with a description and a Zod inputSchema, and an async handler that returns a content array.

import { McpServer } from "@modelcontextprotocol/server";
import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
import { z } from "zod";
 
const NWS_API_BASE = "https://api.weather.gov";
 
const server = new McpServer({
  name: "weather",
  version: "1.0.0",
});
 
server.registerTool(
  "get_alerts",
  {
    description: "Get active weather alerts for a US state",
    inputSchema: z.object({
      state: z
        .string()
        .length(2)
        .describe("Two-letter state code (e.g. CA, NY)"),
    }),
  },
  async ({ state }) => {
    const code = state.toUpperCase();
    // /alerts returns the full archive for the area; /alerts/active is the
    // subset that is in force right now — which is what the tool promises.
    const res = await fetch(`${NWS_API_BASE}/alerts/active?area=${code}`, {
      headers: { "User-Agent": "weather-app/1.0", Accept: "application/geo+json" },
    });
 
    if (!res.ok) {
      return {
        content: [{ type: "text", text: `Alert lookup failed: HTTP ${res.status}` }],
      };
    }
 
    const data = await res.json();
    const features = data.features ?? [];
 
    if (features.length === 0) {
      return { content: [{ type: "text", text: `No active alerts for ${code}` }] };
    }
 
    return {
      content: [
        {
          type: "text",
          text: features
            .map((f) => `${f.properties.event}: ${f.properties.headline}`)
            .join("\n"),
        },
      ],
    };
  },
);

Write descriptions for the model, not for humans

This is the part engineers under-invest in. The description string and every .describe() on a schema field are the only things the model sees when deciding whether your tool is relevant. "Get active weather alerts for a US state" gets called correctly. "Weather utility" does not.

Be concrete about when to call the tool, not just what it does. If a tool only works for US locations, say so in the description — otherwise the model will call it for Lahore and you will burn a round trip on an error.

The corollary is that the description has to keep matching the implementation. /alerts and /alerts/active differ by one path segment and, for Wyoming on the day I checked, by 119 results versus 7 — the first is every alert the NWS has on file for the area, the second is the ones in force. A tool that promises "active" and calls /alerts isn't a documentation nit; the model has no way to know it was lied to, so it reports expired warnings as current with full confidence. Descriptions drift silently, because nothing type-checks them.

Return errors as content, not exceptions

Notice that the HTTP failure above returns a normal content block rather than throwing. A thrown error is an opaque protocol failure; a text block saying "HTTP 503" is something the model can reason about and retry or route around. Same instinct as returning a useful HTTP error body instead of a bare 500.

Connect the transport

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("Weather MCP Server running on stdio");
}
 
main().catch((error) => {
  console.error("Fatal error in main():", error);
  process.exit(1);
});

That console.error is not a typo, and it is the single most important line in this post.

Never write to stdout

On a stdio server, stdout is the JSON-RPC channel. console.log() writes to stdout by default, so a single stray log line injects non-JSON into the message stream and breaks the connection. The MCP docs are blunt about it: "Writing to stdout will corrupt the JSON-RPC messages and break your server."

Use console.error(), which writes to stderr, or a logging library configured to write to stderr or a file. This bites people hardest when a transitive dependency logs a deprecation warning to stdout at import time — the server dies before it serves a single request, with no obvious cause. If a server mysteriously refuses to connect, grep your dependency tree for console.log before you touch anything else.

HTTP-based servers don't have this problem; stdout logging there is fine.

Register it with your client

Build first — npm run build — then register the compiled entry point.

Claude Code uses the CLI. The -- separator matters: everything after it is passed to your server untouched, so Claude Code doesn't try to parse your server's flags as its own.

# stdio, local
claude mcp add --transport stdio weather -- node /abs/path/to/weather-mcp/build/index.js
 
# with an env var, and shared with the team via .mcp.json
claude mcp add --env NWS_TOKEN=abc --transport stdio --scope project weather \
  -- node /abs/path/to/weather-mcp/build/index.js
 
# remote HTTP server
claude mcp add --transport http notion https://mcp.notion.com/mcp

Then claude mcp list shows a health status per server — ✔ Connected, ! Needs authentication, or ✘ Failed to connect.

Cursor uses a JSON file: .cursor/mcp.json in the project for project-scoped tools, or ~/.cursor/mcp.json for tools available everywhere.

Scope and transport, side by side

The --scope local label trips people up, because "local" reads like "on my machine, everywhere." It is the opposite: local scope is the default, it stores the entry in ~/.claude.json keyed by the current project's path, and the server appears in that one project only. --scope user is the "all my projects" option. Same file, different reach.

One gotcha worth knowing if you hand-write JSON for Claude Code: an entry with a url but no type is a configuration error, because Claude Code reads a typeless entry as a stdio server and skips it. The type field accepts streamable-http as an alias for http, so configs copied straight from a server's docs work unmodified.

Keep the tool surface small

The instinct after your first working server is to expose everything. Resist it.

Every tool's name, description and input schema are loaded into the model's context on every request in that session. Twenty tools is a standing tax on every single turn, and it makes tool selection harder — the model has more near-synonyms to choose between. Claude Code also warns when MCP tool output exceeds 10,000 tokens and caps output at 25,000 by default, so a chatty tool that dumps a full API response is actively working against you.

Three rules I apply:

• One tool per user intent, not per API endpoint. find_overdue_invoices beats list_invoices plus filter_invoices plus get_invoice.
• Return the answer, not the payload. Format results as terse text. The model does not need your API's envelope, pagination cursors, or null-heavy fields.
• Delete tools nobody calls. If you can't remember the last time a tool fired, it is costing context for nothing.

This is the same discipline I write about in Claude Code vs Cursor: how each one decides what your agent knows — context is a budget, and MCP tool schemas spend from it whether you use them or not.

A checklist before you ship

• npm run build runs clean and build/index.js is executable.
• No console.log anywhere in the server or its runtime dependencies.
• Every tool has a description that says when to call it, and every schema field has .describe().
• Failure paths return text content, not thrown errors.
• Secrets come from environment variables passed at registration, never hardcoded.
• You've reviewed what the server can reach. An MCP server that fetches external content is a prompt-injection surface — Claude Code's docs carry an explicit warning about this, and it applies to servers you write as much as ones you install.