@punkpeye/fastmcp - JSR

A TypeScript framework for building MCP (Model Context Protocol) servers.
A TypeScript framework for building MCP servers capable of handling client sessions.
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.
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:
FastMCP eliminates this complexity by providing an opinionated framework that:
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.
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.
FastMCP supports multiple transport options for remote communication, allowing an MCP hosted on a remote machine to be accessed over the network.
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:
FastMCP supports HTTPS for secure connections by providing SSL certificate options:
This will start the server with HTTPS on https://localhost:8443/mcp.
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.
By default, FastMCP enables CORS with a standard set of allowed headers.
A server bound to a loopback address, which is the default (localhost), answers browser requests from loopback origins only, such as http://localhost:6274. A page served from any other origin cannot open a session or send a message: those requests are refused with a 403. A local server is out of the network's reach but not out of a browser's: without this, any web page you visit could call its tools. Requests without an Origin header, which is every client that is not a web page, are not affected, and a server bound to another address answers every origin.
To answer pages served from elsewhere, name their origins in cors.origin. That list replaces the loopback default, so include a local page's origin too if you use one. Credentials (credentials: true) are only granted to origins named there.
The cors option accepts:
The CorsOptions type is exported from fastmcp for convenience.
FastMCP allows you to add custom HTTP routes alongside MCP endpoints, enabling you to build comprehensive HTTP services that include REST APIs, webhooks, admin interfaces, and more - all within the same server process.
Custom routes use the underlying Hono app returned by server.getApp() and support:
Routes are matched in the order they are registered, allowing you to define specific routes before catch-all patterns.
Custom Hono routes are public unless you add your own route middleware or authentication checks. For protected custom routes, put your auth logic in a reusable helper and call it from both FastMCP's authenticate option and your Hono route handlers:
Public routes are perfect for:
See the custom-routes example for a complete demonstration.
FastMCP supports edge runtimes like Cloudflare Workers, enabling deployment of MCP servers to the edge with minimal latency worldwide.
Note: Built-in authentication for EdgeFastMCP is planned for a future release. Both FastMCP and EdgeFastMCP use Hono internally, so there's no technical barrier—EdgeFastMCP was simply written before OAuth was added to FastMCP. PRs are welcome to add an authenticate option that accepts web Request instead of Node.js http.IncomingMessage.