FastMCP is a TypeScript framework for building MCP servers that can handle client sessions. It is built on top of the official SDK and eliminates the complexity of building MCP by providing an opinionated framework: it automatically handles all boilerplate code, provides simple and intuitive APIs for common tasks, and has built-in best practices and error handling, letting developers focus on the core functionality of MCP.
Purpose and Positioning FastMCP is aimed at developers who want to quickly build MCP servers without dealing with low-level implementation details. The official SDK provides the foundational modules for building MCP, but leaves many implementation details to developers, including initializing and configuring all server components, handling connections, handling tools, handling responses, handling resources, adding prompts, resources, and resource templates, embedding resources and image and audio content blocks, and more. When maximum control or specific architectural requirements are needed, the official SDK should be used, and FastMCP's implementation can be referenced to avoid common pitfalls.
Protocol Version Note FastMCP implements the older, handshake-based MCP revision (2025-11-25 and earlier). It does not support the current specification 2026-07-28, which makes the protocol stateless—there is no initialize handshake and no Mcp-Session-Id. If a framework targeting the current specification is needed, ViteMCP should be used.
Main Capabilities
- Simple definition of tools, resources, and prompts;
- OpenAPI to MCP;
- Passing headers through context;
- Session ID and request ID tracking;
- HTTP streaming (SSE-compatible);
- HTTPS support for secure connections;
- Custom HTTP routes for REST APIs, webhooks, and admin interfaces;
- Edge runtime support, such as Cloudflare Workers, Deno Deploy, etc.;
- Stateless mode for serverless deployments;
- CORS enabled by default;
- Progress notifications;
- Streaming output;
- Typed server events;
- Prompt argument autocompletion;
- Configurable ping behavior;
- Health check endpoint;
- In-memory transport for unit testing without binding a port;
- CLI for testing and debugging.
Usage For basic usage, developers can define a working MCP server and test it using terminal commands. If a boilerplate repository for building your own MCP server is needed, you can use fastmcp-boilerplate. On the remote server side, FastMCP supports multiple transport options, making MCP hosted on remote machines accessible over the network. HTTP streaming is more efficient than SSE in environments that support it and may have better performance for large payloads. The server can listen for HTTP streaming connections, with the default endpoint being /mcp, customizable via httpStream.endpoint; it also starts an SSE server. To serve HTTP streaming and built-in OAuth routes under the issuer path, you can set httpStream.basePath. For HTTPS, secure connections are provided via sslCert, sslKey, and optionally sslCa (for mutual TLS authentication). During testing, self-signed certificates can be generated; in production, certificates should be obtained from a trusted CA (such as Let's Encrypt). CORS is enabled by default and can be customized via the cors option: true, false, or an object containing origin, allowedHeaders, methods, exposedHeaders, credentials, maxAge.
Custom Routes and Edge Runtime FastMCP allows adding custom HTTP routes beyond the MCP endpoint, using the underlying Hono app returned by server.getApp(), supporting Hono's HTTP methods, path parameters, wildcards, query string parsing, request body helper methods, custom status codes and response headers, middleware, and route groups. Custom Hono routes are public by default unless you add your own route middleware or authentication checks; protected custom routes should place authentication logic in reusable helper functions and call them in both FastMCP's authenticate option and the Hono route handlers. Public routes are suitable for OAuth discovery endpoints, health checks and status pages, static assets and documentation, webhook endpoints for external services, and public APIs that do not require user authentication. Regarding edge runtime, FastMCP supports Cloudflare Workers, etc., allowing MCP servers to be deployed to the edge. Note that EdgeFastMCP's built-in authentication is planned for a future version; currently, Hono middleware can be used; deploy via the EdgeFastMCP class through the /edge subpath to Cloudflare Workers. In an edge runtime, it is stateless by default, has no file system access, uses V8 Isolates for fast cold starts, and is globally deployed.
Stateless Mode and Tool Definitions FastMCP supports stateless operation over HTTP streaming, where each request is handled independently without maintaining a persistent session, making it suitable for serverless environments, load-balanced deployments, or scenarios that do not require session state. In stateless mode the server does not track sessions; each request creates a temporary session and discards it after responding, resulting in lower memory usage and better scalability. It can be enabled via the stateless: true option, a CLI argument, or an environment variable; note that this mode applies only to HTTP streaming, and features that depend on persistent sessions will be unavailable. The /ready health check endpoint indicates whether the server is running in stateless mode. Regarding tool definitions, FastMCP uses the Standard Schema specification to define tool parameters, allowing the use of libraries that implement this specification such as Zod, ArkType, and Valibot; Valibot requires the peer dependency @valibot/to-json-schema. You can also directly use an existing JSON Schema by wrapping it with jsonSchemaAdapter, which requires the peer dependency ajv for validation; if the schema uses the format keyword, ajv-formats is also needed, and both are imported on the first tool call. JSON Schema does not carry TypeScript types, so execute receives unknown parameters and you must assert or narrow them yourself. Tools with no parameters can omit the parameters property or explicitly define empty parameters; both are compatible with all MCP clients, including Cursor. Tools can declare an outputSchema and return structured data; FastMCP exposes it as MCP structuredContent while also returning a JSON text fallback; when an outputSchema is provided, structured output is validated, and if invalid it is returned as a tool error. A canAccess function can be used to control which tools are available to an authenticated user. execute can return a string, an object with a content property, list messages, image content, etc.; imageContent supports url, path, or buffer (only one of the three may be specified), and url supports timeoutMs.
Connection Health and Streaming Keepalive FastMCP includes a configurable ping mechanism to maintain connection health, optimized by default for different transport types: enabled for SSE and HTTP streaming connections, and disabled for stdio connections. Ping uses a separate server-to-client stream, so it does not keep the connection of a single tool call open; in stateless mode this stream does not exist. If a tool runs for a long time without output, its response connection may be closed due to an idle timeout (e.g., the AWS ALB default of 60 seconds). streamKeepalive periodically writes to the response stream of the in-progress tool call itself and must be explicitly enabled: each keepalive is a notifications/message, its level is configurable via logLevel (default debug), it is marked with the fastmcp-keepalive logger, and it is associated with the tool call being served; keepalive starts when the tool begins executing and stops when the request stops waiting. This option has no effect on httpStream.enableJsonResponse, because it buffers a single JSON reply; and it only covers tool calls, while other long-running requests (resources/read, prompts/get) still write no content before completing.
