Build an MCP Server in TypeScript: A Guide

The Model Context Protocol, or MCP, is an open standard for connecting AI clients to external tools and data through one consistent interface. Instead of writing a bespoke integration for every assistant, you build one MCP server and any compatible client, Claude Code included, can use it. It is often described as a USB-C port for AI applications.

This guide builds a small server in TypeScript from scratch. We will scaffold the project with the official SDK, expose a typed tool, connect the server to a client, and cover what changes when you move from a local prototype to something others depend on.

What an MCP server is and why build one

An MCP server is a program that exposes capabilities to AI clients over a structured protocol built on JSON-RPC. The client and server exchange messages in a defined shape, so the model can discover what the server offers and call into it without any custom glue on the client side.

You would build one when you want an assistant to reach something it cannot see on its own:

• An internal API or database that lives behind your own authentication.
• A tool that performs a real action, such as filing a ticket or running a report.
• A source of live context, like documentation or configuration, that the model should read on demand.

Scaffold the server

Start a Node project and install two packages: the official MCP SDK for TypeScript and a schema library such as Zod for validating inputs. The SDK gives you a server object and a set of transports; Zod lets you describe each tool's arguments in a way the SDK turns into a schema the client can read.

A minimal server that registers one tool and speaks over standard input and output looks like this:

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: "weather",
  version: "1.0.0",
});

server.tool(
  "get_forecast",
  "Get a short weather forecast for a city",
  { city: z.string().describe("City to look up") },
  async ({ city }) => ({
    content: [
      { type: "text", text: "Forecast for " + city + ": sunny, 27C" },
    ],
  })
);

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

Add a typed tool

A tool is an action the model can choose to call. Each one needs four things, and getting them right is what makes the tool usable rather than a source of confusion.

• A clear, unique name the model uses to refer to the tool.
• A short description that tells the model exactly when the tool should be used.
• An input schema, defined with Zod, so arguments are validated before your handler runs.
• A handler that does the work and returns content the client renders back to the model.

Connect it to a client

With the server built, register it with a client. In Claude Code you add a server with the claude mcp add command, pointing it at the command that launches your server; other clients keep the same information in a configuration file. Once registered, the client starts the server and lists its tools automatically.

Before wiring it into a real assistant, test the server in isolation with the MCP Inspector, a standalone tool that connects to your server and lets you list and call its capabilities by hand. Catching a broken schema in the Inspector is far cheaper than debugging it through a chat interface.

From local prototype to production

A stdio server on your laptop is the start, not the finish. Moving to something shared or remote brings a few decisions that the local version let you ignore.

• Switch from stdio to the Streamable HTTP transport when the server must be reached over a network rather than launched locally.
• Add authentication and authorization, since a remote server is exposed in ways a local child process never was.
• Handle errors and logging deliberately, so a failing tool returns a clear message instead of a silent hang.

Building an MCP server in TypeScript is mostly about three moves: scaffold with the official SDK, describe each tool with a strict input schema, and pick the transport that matches where the server runs. Start local over stdio, validate every input, and you have a reusable bridge any MCP client can plug into.