🔌Build your own MCP server in TypeScript with FastMCP

THE MOMENT: when consuming isn't enough

You've spent weeks with AI wired into tools. You ask it to open a browser and it does. You ask it to read a repo and it reads it. All of that is MCPs other people wrote — standard plugs someone published and you installed. It works because they speak a common language: the Model Context Protocol, the open standard that lets any AI discover and call external tools without coupling to any of them.

The moment arrives when what you need doesn't exist as an MCP. You have an internal endpoint that returns your order status. A spreadsheet only you know how to read. A 40-line script that computes something specific to your domain. Today, every time you want the AI to use it, you do the errand-runner dance: you run it, copy the output, paste it into the chat, wait. It works once. By the tenth time, you're wondering why the AI doesn't just do it itself.

This resource closes an arc. In agent-browser you learned to give your AI an external capability to consume the world — see pages, click, extract. Here you turn the camera around: you learn to publish your own capabilities so other AIs can consume them. From user to author. Same protocol, seen from the other side of the cable.

THE PAIN: the official SDK is powerful but hostile

When you open the official MCP SDK for the first time, it feels like popping the hood of a race car: everything's there, everything's correct, and nothing is obvious. You have to register handlers by hand, map the protocol's requests, serialize responses in the exact format the client expects, manage the connection lifecycle, parse the input parameters and validate them yourself. To expose a single tool that adds two numbers, you write dozens of lines of plumbing before you reach the line that does the addition.

Where does that pain come from? From the fact that the official SDK is low-level on purpose. It's the foundation you build on, not the final ergonomics — just as Node's http module is correct but nobody writes a web server with it directly, they use Express. The SDK gives you full access to the protocol; the price is that you carry all the boilerplate. It's fine for someone building frameworks. It's hostile for someone who just wants to plug in their API.

FastMCP exists to erase exactly that boilerplate. It's a TypeScript framework that wraps the official MCP SDK — it doesn't replace it, it stands on top of it — and gives you a declarative API: you describe the tool, its schema, and its function, and FastMCP handles the rest (registration, serialization, connection lifecycle, validation). The add tool goes from that tangle of plumbing to little more than a dozen lines. And they're the ones that matter: the ones that actually do the addition.

THE HABIT: when to publish an MCP

Publishing an MCP server isn't something you do once and forget. It's a reflex that fires at specific moments. Learn to recognize them and you'll always know when the time it takes to build one is worth it.

Prepping the ground (2 minutes)

FastMCP installs like any npm package. It runs on modern Node with TypeScript. A minimal new project fits in a folder with three files.

# In a new folder for your server
mkdir mi-mcp && cd mi-mcp
npm init -y

# FastMCP + Zod (for input schemas) + tsx (to run TS without compiling)
npm install fastmcp zod
npm install -D tsx typescript

Your first server: the 'add' tool (15 minutes)

We start with the MCP 'hello world': a server with a single tool that adds two numbers. It's deliberately silly — the point isn't the addition, it's seeing the whole cable: define the server, register a tool with its schema, start it, and have Claude call it. Once you have this skeleton, everything else is variations.

// server.ts
import { FastMCP } from "fastmcp";
import { z } from "zod";

const server = new FastMCP({
  name: "Mi Servidor",
  version: "1.0.0",
});

server.addTool({
  name: "add",
  description: "Suma dos números",
  parameters: z.object({
    a: z.number(),
    b: z.number(),
  }),
  execute: async (args) => {
    return String(args.a + args.b);
  },
});

server.start({
  transportType: "stdio",
});

Read it top to bottom, because this pattern repeats in everything you build. new FastMCP creates the server with a name and version — that's what Claude will see in the connection list. addTool registers a tool: a name (that the AI uses to call it), a description (that the AI reads to decide when to use it — write it well, it's marketing aimed at the machine), the parameters as a Zod schema, and execute, the function that actually runs. You return a string and FastMCP wraps it in the protocol's format for you.

Test it before connecting it: the FastMCP CLI

Before plugging it into Claude, test it in isolation. FastMCP ships a CLI that starts your server and lets you talk to it, plus the official MCP Inspector to view it in a visual interface. It's your development loop: you change the code, test it here, and only connect it to the real client when it works.

# Start your server in dev mode (interact with the tools)
npx fastmcp dev server.ts

# Open it in the MCP Inspector (visual interface to inspect tools/resources/prompts)
npx fastmcp inspect server.ts

Connect it to Claude Code (so it actually calls it)

This is where it stops being an exercise and turns real. An MCP client (Claude Desktop, Claude Code) launches your server as a subprocess and talks to it over stdio. It just needs to know how to start it: which command and which arguments. That lives in a config file with the list of MCP servers.

{
  "mcpServers": {
    "mi-servidor": {
      "command": "npx",
      "args": ["tsx", "/ruta/absoluta/a/mi-mcp/server.ts"]
    }
  }
}

command is the executable that launches your server and args its arguments — here we use npx tsx to run the TypeScript directly without compiling. Use an absolute path: the client doesn't know which folder you launch it from. Once saved and the client restarted, your server shows up in the list, and when you ask Claude "add 128 and 45," you'll see it call your add tool instead of computing it in its head. That moment — the first tool of yours the AI calls on its own — is the one that hooks you.

Leveling up: Zod schemas that validate themselves

The add tool used Zod for the bare minimum. But the real power shows up with real tools, where the input has shape and rules. Picture a tool that creates a user: the email must be in email format, the age must be a positive integer, the role can only be one of a list. With Zod, you describe all of that and FastMCP rejects invalid input before it touches your code. You never write an if (!email.includes('@')). The schema is the guard.

server.addTool({
  name: "crear_usuario",
  description: "Crea un usuario en el sistema con validación completa",
  parameters: z.object({
    nombre: z.string().min(2),
    email: z.string().email(),
    edad: z.number().int().positive().optional(),
    rol: z.enum(["admin", "editor", "lector"]),
  }),
  execute: async (args) => {
    // Si llegaste aquí, args YA está validado: email es email, rol es válido.
    const usuario = await miBaseDeDatos.insertar(args);
    return `Usuario ${usuario.id} creado con rol ${args.rol}`;
  },
});

Resources: expose data, not just actions

A tool is a verb — the AI executes it to make something happen. But sometimes you don't want an action, you want to provide context: a log file, a config document, the contents of a README. That's what resources are for. They're data your server exposes that the AI can read when it needs to, identified by a URI. Think of tools as the buttons on a remote, and resources as the screens that display information.

server.addResource({
  uri: "file:///logs/app.log",
  name: "Logs de la Aplicación",
  mimeType: "text/plain",
  async load() {
    const contenido = await fs.readFile("/var/log/app.log", "utf-8");
    return { text: contenido };
  },
});

The uri is the resource's unique identifier — the client uses it to request it. mimeType tells the AI what kind of content it is (plain text, JSON, markdown), so it interprets it correctly. And load is the function that brings the content when someone asks for it — lazy by design: you don't read the file until it's needed. For binary data you return { blob } in base64 instead of { text }. A resource is the clean way to say "AI, here's fresh data whenever you need it," without spending it in the prompt until the exact moment.

Prompts: package your reusable templates

The third ingredient of the protocol is prompts. If you have a template you use all the time — 'generate a commit message from this diff', 'summarize this meeting in this format' — an MCP prompt packages it with a name and some arguments, and any client can call it. You stop copy-pasting the same long instruction: you offer it as one more capability of your server.

server.addPrompt({
  name: "git-commit",
  description: "Genera un mensaje de commit a partir de un diff",
  arguments: [
    {
      name: "changes",
      description: "El diff de git o una descripción de los cambios",
      required: true,
    },
  ],
  load: async (args) => {
    return `Genera un mensaje de commit conciso para estos cambios:\n${args.changes}`;
  },
});

The jump to production: from stdio to HTTP streaming

Everything above ran over stdio: local, yours, a subprocess on your machine. Perfect to start. But when you want others to use your MCP — your team, a client, yourself from several places — you need to expose it over the internet. That's where HTTP streaming transport comes in: instead of a local pipe, your server listens on a port and responds over HTTP with event streaming. Your tools' code doesn't change a single line; you only change how it starts.

server.start({
  transportType: "httpStream",
  httpStream: {
    port: 8080,
    endpoint: "/mcp", // opcional, por defecto es /mcp
  },
});

That's the whole switch. Same tools, same resources, same prompts — now served over HTTP on port 8080, endpoint /mcp. A remote client points at https://tu-dominio/mcp and plugs in. This is where your MCP stops being a personal tool and becomes a service. And where the question that separates a toy from a product shows up: who can call it?

Authentication: the lock + pipe doctrine

An MCP over HTTP without authentication is an open door: anyone who knows the URL calls your tools, touches your database, spends your resources. FastMCP solves this with an authenticate option: a function that runs on every connection, inspects the request (headers, API key, token), and decides whether it passes or not. If it passes, it returns a session object that will be available inside every tool.

const server = new FastMCP({
  name: "Mi Servidor",
  version: "1.0.0",
  authenticate: (request) => {
    const apiKey = request.headers["x-api-key"];
    if (apiKey !== process.env.MCP_API_KEY) {
      throw new Response(null, { status: 401, statusText: "Unauthorized" });
    }
    return { id: 1, role: "user" }; // esto se vuelve la sesión
  },
});

server.addTool({
  name: "sayHello",
  execute: async (args, { session }) => {
    return `Hola, usuario ${session.id}!`; // session viene de authenticate
  },
});

Sessions, progress, and streaming: tools that breathe

Real tools aren't instantaneous. A tool that processes a large file, calls a slow API, or generates content takes seconds. FastMCP gives you, inside execute, a context with tools so that tool can breathe: report progress, emit streaming content, log, and access the authenticated user's session.

server.addTool({
  name: "procesar_lote",
  description: "Procesa un lote reportando progreso en vivo",
  parameters: z.object({ total: z.number() }),
  annotations: { streamingHint: true },
  execute: async (args, { streamContent, reportProgress, log, session }) => {
    log.info(`Iniciando lote para ${session.id}`);
    await streamContent({ type: "text", text: "Empezando..." });
    await reportProgress({ progress: 50, total: 100 });
    // ... trabajo real ...
    return "Completado";
  },
});

reportProgress({ progress, total }) tells the client 'I'm at 50%', and the AI (and the human) see a bar instead of an anxious silence. streamContent emits output in chunks as it's generated, instead of waiting until the end — the difference between watching the text appear and staring at a spinner. log leaves a structured trail for debugging. And session is the user that authenticate validated, so each tool knows who is calling it. With these, your tools stop being black boxes that take time and become observable processes.

THE MASTER PROMPT: bootstrap your MCP server

Here's the one prompt you need to save. Instead of writing the server by hand, you describe it to your AI — which already has all the FastMCP context from this guide in front of it — and it generates the full skeleton, tested, ready to connect. Fill in the brackets with your real case and let it build. One prompt, not five: this one bootstraps the whole project.

Act as a senior MCP engineer. We're going to build an MCP server in TypeScript with FastMCP (the framework that wraps the official MCP SDK, the one Anthropic opened up; install it with `npm install fastmcp zod`).

MY SERVER:
- Name: [name of your server, e.g. "CRM Interno"]
- What it exposes: [describe in 2 lines what tools/data you want the AI to touch]

THE TOOLS I NEED (actions the AI will execute):
1. [nombre_tool] — [what it does] — inputs: [fields and their types/rules]
2. [nombre_tool] — [what it does] — inputs: [fields and their types/rules]

RESOURCES (data the AI will read, if applicable):
- [name] — [what data it exposes, e.g. logs, config]

MODE: [start with "stdio local" for development | then I migrate to "httpStream with API-key authentication" for production]

BUILD:
1. The complete server.ts: `new FastMCP` with name and version, each tool with `addTool` (name, a clear description aimed at helping the AI know when to use it, parameters as a Zod schema that ACTUALLY validates — .email(), .int().positive(), .enum() where they belong, and .optional() on what's optional, typed execute).
2. The resources with `addResource` (uri, name, mimeType, lazy load that returns {text} or {blob}) if I asked for them.
3. The `server.start` with the transport I chose (stdio or httpStream with port/endpoint).
4. If I asked for production: the `authenticate` option that reads the API key from `process.env` (NEVER hardcoded), throws `new Response(null, {status: 401})` if it doesn't match, and returns the session, plus a tool that uses `session`.
5. The `mcpServers` JSON block to connect it to Claude Code, with `npx tsx` and an ABSOLUTE path.
6. The exact commands: install, test with `npx fastmcp dev server.ts`, and inspect with `npx fastmcp inspect server.ts`.

CONSTRAINTS: zero secrets in the code; tool descriptions written SO the AI decides well when to call them; validate all input with Zod, not with hand-rolled ifs. Explain each tool to me in one line before the code.

THE EASIEST PATHS: chat vs. web

Publishing an MCP has two paths depending on where you're standing, and it's worth knowing when to take each one.

The full arc: from consumer to author

Step back and look at the path. You started by consuming MCPs other people wrote — your AI used external tools. With agent-browser you learned to give it a capability to see and touch the world. And here, with FastMCP, you turned the camera around: now you publish your own capabilities so any AI can consume them. An add tool in fifteen minutes became tools with Zod, resources, prompts, authentication, and HTTP. You closed the user→author arc. You're no longer a tenant of the MCP ecosystem: you own a plug.