FastMCP

A TypeScript framework for building MCP servers capable of handling client sessions.
> [!IMPORTANT]
>
> 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 — no initialize handshake and no Mcp-Session-Id. For a framework targeting the current spec, use ViteMCP.
Features
- Simple Tool, Resource, Prompt definition
- OpenAPI to MCP conversion
- Authentication
- Passing headers through context
- Session ID and Request ID tracking
- Sessions
- Image content
- Audio content
- Embedded
- Logging
- Error handling
- HTTP Streaming (with SSE compatibility)
- HTTPS Support for secure connections
- Custom HTTP routes for REST APIs, webhooks, and admin interfaces
- Edge Runtime Support for Cloudflare Workers, Deno Deploy, and more
- Stateless mode for serverless deployments
- CORS (enabled by default)
- Progress notifications
- Streaming output
- Typed server events
- Prompt argument auto-completion
- Sampling
- Elicitation
- Configurable ping behavior
- Health-check endpoint
- Roots
- In-memory transport for unit testing without binding a port
- CLI for testing and debugging
When to use FastMCP over the official SDK?
FastMCP is built on top of the official SDK.
The official SDK provides foundational blocks for building MCPs, but leaves many implementation details to you:
- Initiating and configuring all the server components
- Handling of connections
- Handling of tools
- Handling of responses
- Handling of resources
- Adding prompts, resources, resource templates
- Embedding resources, image and audio content blocks
FastMCP eliminates this complexity by providing an opinionated framework that:
- Handles all the boilerplate automatically
- Provides simple, intuitive APIs for common tasks
- Includes built-in best practices and error handling
- Lets you focus on your MCP's core functionality
**When to choose FastMCP:** You want to build MCP servers quickly without dealing with low-level implementation details.
**When to use the official SDK:** You need maximum control or have specific architectural requirements. In this case, we encourage referencing FastMCP's implementation to avoid common pitfalls.
Installation
Quickstart
> [!NOTE]
>
> There are many real-world examples of using FastMCP in the wild. See the Showcase for examples.
_That's it!_ You have a working MCP server.
You can test the server in terminal with:
If you are looking for a boilerplate repository to build your own MCP server, check out fastmcp-boilerplate.
Remote Server Options
FastMCP supports multiple transport options for remote communication, allowing an MCP hosted on a remote machine to be accessed over the network.
HTTP Streaming
HTTP streaming provides a more efficient alternative to SSE in environments that support it, with potentially better performance for larger payloads.
You can run the server with HTTP streaming support:
This will start the server and listen for HTTP streaming connections on http://localhost:8080/mcp.
> **Note:** You can also customize the endpoint path using the httpStream.endpoint option (default is /mcp).
> **Note:** To serve HTTP streaming and built-in OAuth routes under an issuer path, set httpStream.basePath (for example, /issuer1). This exposes authorization server metadata at /.well-known/oauth-authorization-server/issuer1 per RFC 8414.
> **Note:** This also starts an SSE server on http://localhost:8080/sse.
You can connect to these servers using the appropriate client transport.
For HTTP streaming connections:
For SSE connections:
HTTPS Support
FastMCP supports HTTPS for secure connections by providing SSL certificate options:
This will start the server with HTTPS on https://localhost:8443/mcp.
**SSL Options:**
- sslCert - Path to SSL certificate file
- sslKey - Path to SSL private key file
- sslCa - (Optional) Path to CA certificate for mutual TLS authentication
**For testing**, you can generate self-signed certificates:
**For production**, obtain certificates from a trusted CA like Let's Encrypt.
See the https-server example for a complete demonstration.
CORS Configuration
By default, FastMCP enables CORS with a standard set of allowed headers. You can customize the CORS behavior by passing a cors option:
The cors option accepts:
- true (default) - enable CORS with default settings
- false - disable CORS entirely
- An object with these fields:
- origin - a string, array of strings, or a function (origin: string) => boolean
- allowedHeaders - a string or array of strings