FastMCP

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.

import { FastMCP } from "fastmcp"; import { z } from "zod"; // Or any validation library that supports Standard Schema 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) => { return String(args.a + args.b); }, }); server.start({ transportType: "stdio", });

That's it!You have a working MCP server.

You can test the server in terminal with:

git clone https://github.com/punkpeye/fastmcp.git cd fastmcp pnpm install pnpm build # Test the addition server example using CLI: npx fastmcp dev src/examples/addition.ts # Test the addition server example using MCP Inspector: npx fastmcp inspect src/examples/addition.ts

FastMCP supports multiple transport options for remote communication, allowing an MCP hosted on a remote machine to be accessed over the network.

You can run the server with HTTP streaming support:

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

This will start the server and listen for HTTP streaming connections onhttp://localhost:8080/mcp.

Note:You can also customize the endpoint path using thehttpStream.endpointoption (default is/mcp).

Note:To serve HTTP streaming and built-in OAuth routes under an issuer path, sethttpStream.basePath(for example,/issuer1). This exposes authorization server metadata at/.well-known/oauth-authorization-server/issuer1per RFC 8414.

Note:This also starts an SSE server onhttp://localhost:8080/sse.

You can connect to these servers using the appropriate client transport.

import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"; const client = new Client( { name: "example-client", version: "1.0.0", }, { capabilities: {}, }, ); const transport = new StreamableHTTPClientTransport( new URL(http://localhost:8080/mcp), ); await client.connect(transport);

import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js"; const client = new Client( { name: "example-client", version: "1.0.0", }, { capabilities: {}, }, ); const transport = new SSEClientTransport(new URL(http://localhost:8080/sse)); await client.connect(transport);

FastMCP supports HTTPS for secure connections by providing SSL certificate options:

server.start({ transportType: "httpStream", httpStream: { port: 8443, sslCert: "./path/to/cert.pem", sslKey: "./path/to/key.pem", sslCa: "./path/to/ca.pem", // Optional: for client certificate authentication }, });

This will start the server with HTTPS onhttps://localhost:8443/mcp.

- 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:

openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes -subj "/CN=localhost"

For production, obtain certificates from a trusted CA like Let's Encrypt.

By default, FastMCP enables CORS with a standard set of allowed headers. You can customize the CORS behavior by passing acorsoption:

- Hono's HTTP methods:get,post,put,delete,patch,options, and more
- Path parameters (:param) and wildcards ()
- Query string parsing
- JSON, text, form, and other body helpers fromc.req
- Custom status codes and headers
- Middleware and route groups through Hono

const app = server.getApp(); app.use("/api/", async (c, next) => { if (c.req.header("authorization") !== "Bearer secret") { return c.json({ error: "Unauthorized" }, 401); } await next(); });

To deploy FastMCP to Cloudflare Workers, use theEdgeFastMCPclass from the/edgesubpath:

import { EdgeFastMCP } from "fastmcp/edge"; import { z } from "zod"; const server = new EdgeFastMCP({ name: "My Edge Server", version: "1.0.0", description: "MCP server running on Cloudflare Workers", }); // Add tools, resources, prompts as usual server.addTool({ name: "greet", description: "Greet someone", parameters: z.object({ name: z.string(), }), execute: async ({ name }) => { return Hello, ${name}! Served from the edge.; }, }); // Export the server as the default (required for Cloudflare Workers) export default server;

- Stateless by default: Each request is handled independently
- No filesystem access: Use fetch APIs for external data
- V8 Isolates: Fast cold starts and efficient resource usage
- Global deployment: Automatic distribution to edge locations

You can access the underlying Hono app to add custom HTTP routes:

const app = server.getApp(); // Add a landing page app.get("/", (c) => c.html("<h1>Welcome to my MCP server</h1>")); // Add REST API endpoints app.get("/api/status", (c) => c.json({ status: "ok" }));

name = "my-mcp-server" main = "src/index.ts" compatibility_date = "2024-01-01"

FastMCP supports stateless operation for HTTP streaming, where each request is handled independently without maintaining persistent sessions. This is ideal for serverless environments, load-balanced deployments, or when session state isn't required.

- No sessions are tracked on the server
- Each request creates a temporary session that's discarded after the response
- Reduced memory usage and better scalability
- Perfect for stateless deployment environments

You can enable stateless mode by adding thestateless: trueoption:

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

Note:Stateless mode is only available with HTTP streaming transport. Features that depend on persistent sessions (like session-specific state) will not be available in stateless mode.

You can also enable stateless mode using CLI arguments or environment variables:

# Via CLI argument npx fastmcp dev src/server.ts --transport http-stream --port 8080 --stateless true # Via environment variable FASTMCP_STATELESS=true npx fastmcp dev src/server.ts

The/readyhealth check endpoint will indicate when the server is running in stateless mode:

{ "mode": "stateless", "ready": 1, "status": "ready", "total": 1 }

import { z } from "zod"; server.addTool({ name: "fetch-zod", description: "Fetch the content of a url (using Zod)", parameters: z.object({ url: z.string(), }), execute: async (args) => { return await fetchWebpageContent(args.url); }, });

import { type } from "arktype"; server.addTool({ name: "fetch-arktype", description: "Fetch the content of a url (using ArkType)", parameters: type({ url: "string", }), execute: async (args) => { return await fetchWebpageContent(args.url); }, });

Valibot requires the peer dependency @valibot/to-json-schema.

import * as v from "valibot"; server.addTool({ name: "fetch-valibot", description: "Fetch the content of a url (using Valibot)", parameters: v.object({ url: v.string(), }), execute: async (args) => { return await fetchWebpageContent(args.url); }, });

If you already have a JSON Schema — from an OpenAPI document, a config file, or another server —jsonSchemaAdapterwraps it so it can be used directly, with no schema library in between.

It requires the peer dependencyajv, which does the validation, plusajv-formatsif your schema usesformatkeywords such asemailoruri. Both are imported the first time a tool is called, so servers that don't use this pay nothing for it.