Build · Step 11 of 14

Build an MCP Server

The Model Context Protocol (MCP) is the standard for handing tools and data to AI clients. Build a server once — Claude, VS Code, Cursor, and every other MCP client can use it.

1. What MCP actually is

MCP is a small protocol with two sides. A client (the AI app — Claude Code, Claude Desktop, VS Code, Cursor) connects to one or more servers. Each server exposes capabilities; the client makes them available to the model.

A server can expose three kinds of things:

  • Tools — functions the model can call (search a DB, send a message, run a calculation). This is the workhorse.
  • Resources — readable data the client can load as context (a file, a record, a config).
  • Prompts — reusable prompt templates the user can invoke.
Most servers are just a bag of tools. Start there; add resources and prompts only when you have a clear need.

2. Transports: stdio vs. HTTP

A server talks to a client over a transport:

  • stdio — the client launches your server as a local subprocess and speaks over stdin/stdout. Simplest to ship; no hosting. This is what we use below.
  • Streamable HTTP — your server runs as a web service clients connect to remotely. Use this when the server must be hosted or shared; it is also where authorization (OAuth) comes in.

The current specification (dated 2026-07-28) made the protocol stateless: every request stands on its own, with no handshake or session to keep alive. That makes hosted servers much easier to run behind a load balancer. If your tools need to remember something between calls, return an ID from one tool and take it as an argument in the next.

3. Set up the project

You need Node.js 20 or later.

mkdir weather-mcp && cd weather-mcp
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.

Older tutorials install @modelcontextprotocol/sdk. That is version 1 of the SDK. New servers use @modelcontextprotocol/server (version 2), which implements the current specification — the imports are different, so don't mix the two.

4. Write the server

A server is: build it, register tools, serve it over a transport. Here is a complete one — src/index.ts:

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

// 1. A factory that builds the server and registers its tools.
function createServer(): McpServer {
  const server = new McpServer({ name: "weather", version: "1.0.0" });

  // 2. Register a tool. The inputSchema (Zod) becomes the JSON Schema
  //    the model sees, and arguments are validated against it for you.
  server.registerTool(
    "get_forecast",
    {
      title: "Get forecast",
      description: "Get a short weather forecast for a city.",
      inputSchema: z.object({
        city: z.string().describe("City name, e.g. 'Austin'"),
      }),
    },
    async ({ city }) => {
      // Real work goes here — call an API, read a DB, etc.
      const forecast = `${city}: 72°F and clear.`;
      return { content: [{ type: "text", text: forecast }] };
    },
  );

  return server;
}

// 3. Serve it over stdio. Log to stderr; stdout is the protocol.
void serveStdio(createServer);
console.error("weather MCP server running on stdio");
On a stdio server, never write logs to stdout — that channel carries protocol messages and stray text corrupts it. Use console.error (stderr) instead.

5. Try it, then connect it

Before involving a model, call the tool yourself with the MCP Inspector — a local web app that launches your server and lets you run its tools by hand:

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

Then register it with a client. Every client needs the same thing — the command that starts your server. For Claude Code, from the project folder:

claude mcp add weather -- npx tsx src/index.ts

For Claude Desktop, add it to claude_desktop_config.json with an absolute path:

{
  "mcpServers": {
    "weather": {
      "command": "npx",
      "args": ["-y", "tsx", "/absolute/path/to/weather-mcp/src/index.ts"]
    }
  }
}

VS Code (.vscode/mcp.json) and Cursor (.cursor/mcp.json) take the same command and arguments in their own config files. Restart the client and ask something that needs your tool — "what's the forecast for Austin?" — and it will call get_forecast.

6. Make it good, not just working

  • Name and describe tools for the model. The description is a prompt — say what the tool does and when to use it, plainly. The model picks tools from the name, description, and schema alone.
  • Let the schema do the validating. Put the rules in the Zod schema; for failures inside your handler, return a readable message with isError: true rather than throwing, so the model can react to it.
  • Keep tools small. One job per tool beats one tool with a mode flag.
  • Return useful text. The model only sees what you put in content — make it readable, and keep it short; every result takes up room in the model's context.
  • Treat a server like a dependency. A tool runs with your credentials and its output is read by a model that acts on it. Install servers you trust, and give yours the narrowest access that does the job.

7. When to host it

A stdio server runs on one person's machine. When a whole team or your customers should use the same tools, serve the same createServer factory over Streamable HTTP instead and deploy it like any web service. Two things change:

  • Authorization. A hosted server must know who is calling. MCP uses OAuth for this; clients handle the sign-in, and your server checks the token on every request.
  • Whose access is it? Each tool should act with the permissions of the signed-in user, not one all-powerful service account.

Build it locally over stdio first. Everything on this page carries over; only the last line of the file changes. And before you connect a server to real data, read Security.

Skip the boilerplate

Once you have built one server by hand, you rarely want to do the setup again. The Scaffolder is an MCP server that generates a complete one for you from a sentence describing the job.