FastMCP: building MCP servers in TypeScript with a handshake-based protocol

What problem FastMCP solves, and who it is actually for

The official MCP SDK gives you the protocol primitives and stops there. The FastMCP README is explicit about the gap it fills: you would otherwise be responsible for initiating and configuring server components, handling connections, dispatching tools, shaping responses, and wiring resources, resource templates, prompts, and embedded image and audio content blocks. Each of those is a link into the source file in the README, which is a fair summary of how much surface area the official SDK leaves open.

FastMCP is an opinionated layer over that SDK. You declare a tool with a name, a description, a parameter schema and an execute function, and the framework takes care of registration, schema conversion and response formatting. The intended audience is a TypeScript developer who has a function or an internal API worth exposing to an MCP client and does not want to hand-roll session bookkeeping to do it. The README frames the trade-off plainly: pick FastMCP when you want to build quickly without low-level details, and pick the official SDK when you need maximum control or have specific architectural requirements. That is an unusually honest positioning statement, and it should be read as the project telling you it is a convenience layer, not a reimplementation of the protocol.

How the framework is put together: tools, schema validation and transports

A FastMCP server is an object created with a name and a version. Tools are added to it with addTool, and the parameter schema is any validation library that supports Standard Schema, with zod shown in the README example. That schema is what the framework converts into the tool's advertised input shape, so the validation library you already use in your project is the one you describe your tool with. There is no separate schema dialect to learn.

Starting the server selects a transport. The stdio transport is the default in the quickstart and is what a local client spawns. The httpStream transport starts an HTTP streaming endpoint, and the README notes that the same start call also brings up an SSE server alongside it, so a single process serves both a streaming endpoint on /mcp and an SSE endpoint on /sse. The endpoint path is configurable through httpStream.endpoint, and httpStream.basePath moves both the streaming routes and the built-in OAuth routes under an issuer prefix, exposing authorization server metadata at the RFC 8414 well-known location.

Around that core the framework adds session and request ID tracking, header pass-through into context, progress notifications, streaming output, typed server events, sampling, elicitation, roots management, a health-check endpoint, CORS on by default, and an in-memory transport for unit tests that avoids binding a port. There is also a CLI binary exposed as fastmcp, plus an OpenAPI conversion path that turns an existing OpenAPI document into MCP tools. The package publishes separate entry points for the core, auth, edge and openapi modules, so an edge deployment does not pull in the Node-only pieces.

Installing FastMCP and running a first server

The README gives a single install command. It is an npm package, and the package name is fastmcp.

npm install fastmcp

The quickstart then defines a server with one tool and starts it over stdio. Copy this into a TypeScript file, keeping the import names as written.

import { FastMCP } from "fastmcp";
import { z } from "zod";

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

server.addTool({
  name: "add",
  description: "Add two numbers",
  parameters: z.object({ a: z.number(), b: z.number() }),
  execute: async (args) => String(args.a + args.b),
});

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

Running that file with a TypeScript runner gives you a working MCP server that exposes one tool called add. To check it without wiring up a client, the README points at the project's own CLI. The commands below clone the repository, build it, and then exercise the bundled addition example, first through the CLI and then through MCP Inspector.

git clone https://github.com/punkpeye/fastmcp.git
cd fastmcp

pnpm install
pnpm build

npx fastmcp dev src/examples/addition.ts
npx fastmcp inspect src/examples/addition.ts

For a remote server, switch the transport and give it a port. The README states this listens for HTTP streaming connections on http://localhost:8080/mcp and also starts an SSE server on http://localhost:8080/sse.

server.start({
  transportType: "httpStream",
  httpStream: { port: 8080 },
});

If you want a starting point rather than a blank file, the README points to a separate boilerplate repository, fastmcp-boilerplate.

The protocol revision caveat at the top of the README

This is the constraint that decides whether the project fits, and the README puts it above everything else in a callout. FastMCP implements the legacy, handshake-based MCP revisions, meaning 2025-11-25 and earlier. It does not support the current specification, 2026-07-28, which made the protocol stateless by removing the initialize handshake and the Mcp-Session-Id header. The README names ViteMCP as the framework to use if you are targeting the current spec.

That has practical consequences. The framework's session tracking, session ID handling and request ID tracking are features of the handshake-based design. If your clients have moved to the stateless revision, those mechanisms are not the shape of the conversation they expect, and no amount of configuration on the FastMCP side changes that. The README's own framing makes this a compatibility boundary rather than a bug: the project is deliberately staying on the older revisions for now. Before you commit to it, establish which revision your MCP clients negotiate. If the answer is 2026-07-28, this is the wrong tool and the README says so itself.

A second, smaller failure mode is worth naming. The package name collides with a well-known Python project of the same name. Nothing in the README discusses the Python project, and the install command here is npm, not pip. If you arrived looking for a Python framework, you are in the wrong repository.

FastMCP against the official MCP SDK, and against writing it yourself

The README's own comparison is FastMCP versus the official SDK, and the difference is one of altitude rather than capability. The official SDK is the substrate. FastMCP is built on top of it and re-exports a curated experience: you get addTool, addResource, addPrompt and a start call, and the connection lifecycle, response shaping and content-block embedding happen underneath. The README's recommendation for people who need maximum control is to use the official SDK directly and read FastMCP's implementation to avoid the pitfalls it already solved. That is a reasonable division: the framework is a reference implementation as much as a dependency.

The alternative outside that pair is a server in another language. A Python MCP server is the more common starting point for people searching for this project, and it is a genuinely different approach: different runtime, different packaging, different deployment story. What FastMCP offers in exchange is that your tool implementations live in the same TypeScript codebase as the rest of your application, share its types, and deploy as one artifact. For a team already running Node services, that is the argument. For a team whose data layer is Python, it is not, and no feature list changes that.

The OpenAPI conversion path is the third option worth weighing. If you already maintain an OpenAPI document, generating MCP tools from it avoids writing tool definitions by hand, at the cost of inheriting whatever shape the document has. The repository ships a benchmark and live test for that path behind an OPENAPI_NETWORK=1 environment variable, which suggests the maintainers treat it as a component with its own risk surface.

Maintenance, versioning and what the MIT licence means here

The repository is not archived. The last push was on 2026-09-09, and three patch releases landed that day: v4.20.9, v4.20.8 and v4.20.7. Whatever else is true, this is a project that ships frequently, and the patch cadence suggests fixes rather than long release trains. The version string inside package.json reads 1.0.0, which does not match the v4.x release tags, so do not read the manifest as the shipping version; the tags are the release record.

The licence is MIT, which permits commercial and closed-source use with the usual requirement to preserve the copyright and permission notice. That is a permissive choice and it is the same licence the surrounding TypeScript ecosystem generally uses. It says nothing about the MCP specification itself, and nothing here should be read as legal advice; if you are redistributing a built server, have someone check the notice requirements against your own packaging.

Upgrade cost is the part worth budgeting for. The project depends on @modelcontextprotocol/sdk at ^1.24.3, and the protocol revision question above means an SDK bump could be a breaking change for this framework rather than a routine one. The lint script runs jsr publish --dry-run alongside prettier, eslint and tsc --noEmit, so the project does hold itself to a publishability check, but that is a quality gate on their side, not a compatibility guarantee for yours. Pin the version you validate against.

Editorial conclusion

Choose FastMCP if you are writing an MCP server in TypeScript and want tools, resources, prompts, sessions and HTTP streaming handled for you instead of assembled by hand on top of the official SDK. Do not choose it if you need the current stateless MCP specification, since the README states it implements the legacy handshake-based revisions only, and it is not a Python library despite the name overlap. Before adopting it, read the protocol compatibility note at the top of the README and confirm which MCP revision your clients speak.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. punkpeye/fastmcp on GitHub
4. README
5. Releases