FastMCP: a TypeScript wrapper over the MCP SDK, pinned to the legacy handshake spec
A TypeScript framework for building MCP servers.
At a glance
- What is it?
- FastMCP is a TypeScript framework that removes the boilerplate of building MCP servers on top of the official SDK. Its README states plainly that it implements the legacy handshake-based revisions and not the current stateless specification, which is the single fact that should decide whether you adopt it.
- Who is it for?
- Adopt FastMCP if you are building a TypeScript MCP server against the 2025-11-25 or earlier revisions and want tool, resource, and prompt registration, HTTP streaming, sessions, and auth without writing the connection and response plumbing yourself. Do not adopt it if you need the current 2026-07-28 specification, since the README states it does not support it and points to ViteMCP instead.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The boilerplate FastMCP removes, and the revision it locks you to
Building an MCP server on the official SDK means wiring the server components, connection handling, tool dispatch, response shaping, resource and resource-template registration, and the embedding of resource, image, and audio content blocks. The README lists these as the things the SDK leaves to you, with links into specific line ranges of FastMCP.ts. FastMCP's claim is that it handles that boilerplate and exposes an opinionated API for the common cases, while still being built on top of the official SDK rather than replacing it.
The audience is narrow and specific: TypeScript developers who want an MCP server running without reading the protocol plumbing. The README's own framing is that you choose FastMCP when you want to build quickly, and you choose the raw SDK when you need maximum control or have architectural requirements the framework does not anticipate. That is a fair description of a wrapper library, and it also tells you the escape hatch: the SDK is still underneath, and the README encourages reading FastMCP's implementation to avoid common pitfalls if you go that route.
The constraint that matters more than any feature is stated at the top of the README in a callout. FastMCP implements the legacy, handshake-based MCP revisions, 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. Everything else in this article sits underneath that sentence.
How a tool becomes a response: the registration and dispatch path
The quickstart shows the whole shape. You construct a FastMCP instance with a name and version, call addTool with a name, a description, a parameters schema, and an execute function, then call start with a transport type. The parameters schema in the example is a Zod object, and the README notes that any validation library supporting Standard Schema works. The execute function receives the parsed arguments and returns a string, which the framework turns into the tool response.
That is the core data flow: schema in, validated arguments to your function, return value out as MCP content. The README's feature list extends the return side beyond plain strings to embedded resources, image content, and audio content, and it mentions streaming output and progress notifications for longer-running work. Error handling and logging are listed as built-in concerns rather than something you assemble.
Around the tool call itself, FastMCP manages the session. The README advertises session ID and request ID tracking, sessions as a feature, and typed server events. Headers can be passed through into context, which is the mechanism you would use to carry an auth token or a tenant identifier from the HTTP request down into a tool's execute function. Prompt argument auto-completion, sampling, elicitation, and roots management are also listed, which means the framework is tracking a fairly wide slice of the protocol surface rather than only tools.
There is also a stateless mode listed for serverless deployments. That is worth noticing given the top-of-README callout: the framework can run without session continuity, but the protocol revision it implements is still the handshake-based one. Stateless mode here is a deployment posture, not conformance with the stateless 2026-07-28 specification.
Transports, ports, and the config keys you actually set
Installation is a single command: npm install fastmcp. The quickstart server starts with transportType set to stdio, which is the local case where a client launches your process and talks over standard input and output.
For remote access the README documents HTTP streaming. You call start with transportType set to httpStream and an httpStream object containing a port. The example uses port 8080, and the README states the server then listens on http://localhost:8080/mcp. Two further keys are documented: httpStream.endpoint changes the path from its default of /mcp, and httpStream.basePath serves HTTP streaming plus the built-in OAuth routes under an issuer path, for example /issuer1, exposing authorization server metadata at /.well-known/oauth-authorization-server/issuer1 per RFC 8414. The README also notes that starting an HTTP streaming server additionally starts an SSE server on http://localhost:8080/sse, so the two coexist on the same port.
On the client side the README shows the matching transport from the official SDK, StreamableHTTPClientTransport, constructed with a URL pointing at the /mcp endpoint. That is a useful detail: FastMCP does not ship its own client story for this case, it expects you to use the SDK's client transport against its server.
For local testing and debugging the README provides a CLI. From a clone of the repository you run pnpm install and pnpm build, then npx fastmcp dev src/examples/addition.ts to exercise the example addition server, or npx fastmcp inspect src/examples/addition.ts to open it in MCP Inspector. There is also an in-memory transport listed for unit testing without binding a port, which is the option to reach for in a test suite where a real socket would slow things down or collide with parallel runs.
Other operational keys and features named in the README include a health-check endpoint, configurable ping behavior, CORS enabled by default, and HTTPS support. The README does not spell out the exact option names for those in the excerpt available here, so check the source or the fuller documentation before assuming a key name.
The spec gap is a real failure mode, not a footnote
The most consequential limitation is not a bug or a missing feature; it is a version boundary. If a client in your environment negotiates the 2026-07-28 specification, a FastMCP server built on the legacy revisions is the wrong tool, and no amount of configuration changes that. The README says so directly and redirects to ViteMCP. Treat the callout as the first thing you check against your client matrix, before you evaluate anything else on the feature list.
The second limitation is the one the README itself volunteers: the framework is opinionated, and the SDK is the answer when you need maximum control or have specific architectural requirements. An opinionated wrapper is a liability exactly when your requirement falls outside what it anticipated. The README's suggested mitigation is to read FastMCP's implementation as a reference, which is reasonable but also an admission that you may end up maintaining SDK-level code alongside the framework.
A third consideration is release cadence. The recent releases listed are v4.20.9, v4.20.8, and v4.20.7, all published on the same day, which indicates patch releases arriving quickly. Frequent patches are normal for an actively developed project, but they also mean you should pin a version and read the diff between the one you run and the one you upgrade to, particularly for anything touching transport or session handling.
Finally, be careful about what stateless mode does and does not buy you. It is listed as a feature for serverless deployments, and it is genuinely useful there, but it does not close the gap to the current specification. If your reason for wanting statelessness is spec conformance, you want a different framework.
FastMCP against the official SDK, and when ViteMCP is the answer
The README frames the comparison itself: FastMCP is built on top of the official SDK, and the SDK is the lower-level option. The practical difference is where the work sits. With the SDK you initiate and configure the server components, handle connections, dispatch tools, shape responses, and register resources and prompts yourself; the README links to the specific line ranges in FastMCP.ts where each of those is implemented. With FastMCP you write an addTool call and an execute function. The cost of the second path is that the framework owns the connection and session lifecycle, so debugging a transport problem means reading framework code rather than your own.
ViteMCP is the alternative the README names for the current specification. The difference in approach is not stylistic: FastMCP implements the handshake-based revisions, while the 2026-07-28 specification removed the initialize handshake and the Mcp-Session-Id header, making the protocol stateless. A framework targeting that spec does not carry session state as a first-class concept the way FastMCP's session and session-ID tracking features imply. If you are starting a new server today and your clients are on the current spec, ViteMCP is the direction the README itself points, and choosing FastMCP would mean building against a revision the project has declared out of scope.
If your clients are on 2025-11-25 or earlier, the comparison flips. FastMCP's OpenAPI-to-MCP conversion, authentication, header pass-through, custom HTTP routes for REST APIs, webhooks and admin interfaces, edge runtime support for Cloudflare Workers and Deno Deploy, and the CLI for dev and inspect are all things you would otherwise assemble from SDK primitives. That is the trade: less control, less code.
Licence, maintenance, and what an upgrade actually costs
FastMCP is MIT licensed, which permits commercial use, modification, and redistribution provided the copyright notice and permission notice are preserved. That is the most permissive common option and imposes no copyleft obligation on your server code. This is a description of the licence text, not legal advice; if licence compatibility matters to your organisation, have counsel review it rather than relying on a summary.
The maintenance picture visible here is a project under active development: the repository is not archived, the last push and the newest release are the same day, and three patch releases landed within roughly an hour of each other. The homepage points at glama.ai/mcp/servers, and the README references a fastmcp-boilerplate repository for starting a new server.
The upgrade cost is the part to plan for. Because the framework sits between your code and the protocol, a change in transport handling or session semantics can affect you without any change on your side. Practically: pin the version in package.json, read the release notes between your pinned version and the target, and keep a test that exercises your server over the same transport you deploy with. The in-memory transport is the cheap way to cover tool behaviour in unit tests, but it will not catch a transport or session regression, so at least one test should go through stdio or httpStream. The other upgrade risk is the spec boundary itself: if the project eventually moves to 2026-07-28, that is not a patch upgrade, and the README's current position is that this framework is not the one for that specification.
Editorial conclusion
Adopt FastMCP if you are building a TypeScript MCP server against the 2025-11-25 or earlier revisions and want tool, resource, and prompt registration, HTTP streaming, sessions, and auth without writing the connection and response plumbing yourself. Do not adopt it if you need the current 2026-07-28 specification, since the README states it does not support it and points to ViteMCP instead. Before committing, verify which MCP revision your target clients negotiate, and check whether stateless mode or the in-memory transport covers your deployment and test setup.
Community notes