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.
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 srctype=module matters — the SDK ships ES modules only. tsx runs TypeScript directly, so there is no build step.
@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");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.tsThen 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.tsFor 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: truerather 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.