How to build a first MCP server with the TypeScript SDK

An MCP server is a program that exposes tools a model can call. The v2 TypeScript SDK first-server guide builds one of those programs and calls its one tool, a US weather-alert lookup, from a client. This walkthrough follows that page: a Node project, one Zod input schema, stdio as the protocol channel, and the MCP Inspector. It is not a host configuration guide.

Set up the project

You need Node.js 20 or later and nothing else. Create the project and install the SDK:

mkdir weather && cd weather
npm init -y
npm pkg set type=module
npm install @modelcontextprotocol/server zod tsx
mkdir src

type=module matters — the SDK ships ES modules only. tsx runs TypeScript directly, so there is no build step.

Register one tool

Create src/index.ts: a createServer factory that builds an McpServer and registers one tool, a function the connected model can call. Copy the factory as the guide shows it:

import { McpServer } from '@modelcontextprotocol/server';
import { serveStdio } from '@modelcontextprotocol/server/stdio';
import * as z from 'zod/v4';

const NWS_API = 'https://api.weather.gov';

interface AlertsResponse {
    features: { properties: { event?: string; headline?: string } }[];
}

function createServer(): McpServer {
    const server = new McpServer({ name: 'weather', version: '1.0.0' });

    server.registerTool(
        'get-alerts',
        {
            description: 'Get the active weather alerts for a US state',
            inputSchema: z.object({
                state: z.string().length(2).describe('Two-letter US state code, e.g. CA')
            })
        },
        async ({ state }) => {
            const code = state.toUpperCase();
            const url = `${NWS_API}/alerts/active?area=${code}`;
            const res = await fetch(url, { headers: { 'User-Agent': 'mcp-weather-tutorial/1.0' } });
            if (!res.ok) {
                return { content: [{ type: 'text', text: `NWS API error: HTTP ${res.status}` }], isError: true };
            }
            const { features } = (await res.json()) as AlertsResponse;
            if (features.length === 0) {
                return { content: [{ type: 'text', text: `No active alerts for ${code}.` }] };
            }
            const lines = features.map(f => f.properties.headline ?? f.properties.event ?? 'Unnamed alert');
            return { content: [{ type: 'text', text: lines.join('\n') }] };
        }
    );

    return server;
}

registerTool takes a name, a config, and an async handler. In that call the tool name is get-alerts. The server constructor in the same factory sets the server name to weather and the version to 1.0.0.

inputSchema is a Zod schema — the only schema you write. It is the object in the config above: one string field named state, limited to two characters, described as a two-letter US state code such as CA. From that one schema the SDK derives the JSON Schema the model sees, validates arguments before your handler runs, and infers the handler's argument types. Copy the import in the factory as written. The page does not explain that import path.

The handler returns content, a list of typed blocks — one text block here. It uppercases the state argument, builds the request URL from the weather.gov constant exactly as the snippet shows, and sends the User-Agent header written in that same fetch call.

Three results are written out:

• If the response is not OK, the text block reports the HTTP status and isError: true marks a failed result the model can read and react to.
• If the features list is empty, the text says there are no active alerts for that code.
• Otherwise each feature contributes its headline, or its event, or the fallback string in the map, and those lines are joined into the text block.

The weather body is typed with the AlertsResponse interface in the factory. That interface describes features as objects whose properties may include event and headline strings. It is not a second Zod schema. Argument checking is the tool schema; this tutorial does not run the weather payload through Zod.

Bad arguments stop before the handler

Call get-alerts with { "state": "California" } and the SDK rejects it before your handler runs. The result is the failure the model sees:

Input validation error: Invalid arguments for tool get-alerts: state: Too big: expected string to have <=2 characters

The length check is the schema, not a hand-written guard. For that input the handler does not run.

Serve it over stdio

At the end of the file, hand the factory to serveStdio:

void serveStdio(createServer);
console.error('weather MCP server running on stdio');

serveStdio owns the stdio transport: it reads requests on stdin, writes responses to stdout, and calls createServer to build the instance that serves the connection.

Stdout is the protocol channel. Log with console.error — one console.log corrupts the JSON-RPC stream. The banner uses the error stream so protocol bytes stay alone on stdout.

Run it

Start the server from the project root:

npx tsx src/index.ts

The banner lands on stderr, leaving stdout for the protocol:

weather MCP server running on stdio

Nothing else happens: an stdio server waits on stdin for a client to start the conversation. Stop it with Ctrl+C.

Call the tool

The MCP Inspector is a local web app for calling a server's tools directly. It launches the command you give it and connects over stdio:

npx @modelcontextprotocol/inspector npx tsx src/index.ts

In the browser tab it opens, click Connect, open the Tools tab, select get-alerts, enter a two-letter state code such as TX, and run it. The text block in the result lists each active alert headline for that state — the same content a model receives when it calls your tool.

The page does not document Inspector flags, a port, or a URL to open by hand. Use the command as written and the tab it opens. A state string longer than two characters, such as California, is the documented way to see validation fail instead of a weather result.

The same factory, another transport

This server speaks stdio because a host launches it as a local process and owns its lifetime. To host one endpoint that many clients connect to, serve the same createServer factory over HTTP instead. This page does not include those HTTP steps, so there is no listen command to copy from here.

The page's recap is the checklist for what you just built:

• registerTool(name, config, handler) registers a tool; inputSchema is the one Zod schema you write.
• The SDK validates every call against that schema and rejects bad arguments before your handler runs.
• serveStdio(createServer) builds the server from your factory and serves it on stdin/stdout.
• stdout carries the protocol; log to stderr.
• Pointing the Inspector at the command that starts your server exercises any stdio server without a host. For this project, that is the Inspector line above, which launches npx tsx src/index.ts.

What to run next

From the weather project root, run the Inspector command, click Connect, open Tools, and run get-alerts with a two-letter code such as TX. If you want the rejection path, use { "state": "California" } and confirm the handler never starts.

When the text block comes back, the next page on this path is Plug into a real host, which registers this server in VS Code, Claude Code, and Cursor. The Tools page goes deeper on what a tool can return. If a command in this walkthrough and the v2 first-server page disagree, follow the page.

Sources

• Build your first server (MCP TypeScript SDK v2)