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

npm install fastmcp

Quickstart

[!NOTE]

There are many real-world examples of using FastMCP in the wild. See the Showcase for examples.

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

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:

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

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:

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);

For SSE connections:

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);

HTTPS Support

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

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.

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:

server.start({
  transportType: "httpStream",
  httpStream: {
    port: 8080,
    cors: {
      origin: "http://localhost:3000",
      allowedHeaders: [
        "Content-Type",
        "Authorization",
        "Accept",
        "Mcp-Session-Id",
        "Mcp-Protocol-Version",
        "Last-Event-Id",
        "X-Custom-Header",
      ],
      credentials: true,
    },
  },
});

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
- methods - array of allowed HTTP methods
- exposedHeaders - array of headers to expose
- credentials - boolean to allow credentials
- maxAge - preflight cache duration in seconds

The CorsOptions type is exported from fastmcp for convenience.

Custom HTTP Routes

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.

const app = server.getApp();

// Add REST API endpoints with Hono's native API
app.get("/api/users", async (c) => {
  return c.json({ users: [] });
});

// Handle path parameters
app.get("/api/users/:id", async (c) => {
  return c.json({
    userId: c.req.param("id"),
    query: c.req.query(), // Access query parameters
  });
});

// Handle POST requests with body parsing
app.post("/api/users", async (c) => {
  const body = await c.req.json();
  return c.json({ created: body }, 201);
});

// Serve HTML content
app.get("/admin", async (c) => {
  return c.html("<html><body><h1>Admin Panel</h1></body></html>");
});

// Handle webhooks
app.post("/webhook/github", async (c) => {
  const payload = await c.req.json();
  const event = c.req.header("x-github-event");

  // Process webhook...
  return c.json({ received: true });
});

Custom routes use the underlying Hono app returned by server.getApp() and support:

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 from c.req
Custom status codes and headers
Middleware and route groups through Hono

Routes are matched in the order they are registered, allowing you to define specific routes before catch-all patterns.

Public and Protected Routes

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:

import type { IncomingMessage } from "node:http";
import type { Context } from "hono";
import { FastMCP } from "fastmcp";

async function authenticateRequest(request: IncomingMessage) {
  const apiKey = request.headers["x-api-key"];
  return apiKey === "123" ? { userId: "123" } : undefined;
}

const server = new FastMCP({
  name: "My Server",
  version: "1.0.0",
  authenticate: authenticateRequest,
});

const app = server.getApp();

async function requireAuth(c: Context) {
  const auth = await authenticateRequest(c.env.incoming);

  if (!auth) {
    return c.json({ error: "Authentication required" }, 401);
  }

  return auth;
}

// Public route - no authentication required
app.get("/.well-known/openid-configuration", async (c) => {
  return c.json({
    issuer: "https://example.com",
    authorization_endpoint: "https://example.com/auth",
    token_endpoint: "https://example.com/token",
  });
});

// Private route - requires authentication
app.get("/api/users", async (c) => {
  const auth = await requireAuth(c);
  if (auth instanceof Response) {
    return auth;
  }

  return c.json({ users: [] });
});

// Public static files
app.get("/public/*", async (c) => {
  return c.text(`File: ${c.req.path}`);
});

Public routes are perfect for:

OAuth discovery endpoints (.well-known/*)
Health checks and status pages
Static assets and documentation
Webhook endpoints from external services
Public APIs that don't require user authentication

See the custom-routes example for a complete demonstration.

Edge Runtime Support

FastMCP supports edge runtimes like Cloudflare Workers, enabling deployment of MCP servers to the edge with minimal latency worldwide.

Choosing Between FastMCP and EdgeFastMCP

Use Case	Class	Import
Node.js, Express, Bun	`FastMCP`	`import { FastMCP } from "fastmcp"`
Cloudflare Workers, Deno Deploy	`EdgeFastMCP`	`import { EdgeFastMCP } from "fastmcp/edge"`

Feature	FastMCP	EdgeFastMCP
Runtime	Node.js	Edge (V8 isolates)
Start method	`server.start({ port })`	`export default server`
Transport	stdio, httpStream, SSE	HTTP Streamable only
Sessions	Stateful or stateless	Stateless only
File system	Yes	No
OAuth/Authentication	Built-in `authenticate` option	Use Hono middleware (built-in planned)
Custom routes	`server.getApp()`	`server.getApp()`

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.

In the meantime, use Hono middleware:
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();
});

Cloudflare Workers

To deploy FastMCP to Cloudflare Workers, use the EdgeFastMCP class from the /edge subpath:

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;

Edge Runtime Differences

When running on edge runtimes:

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

Custom Routes on Edge

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" }));

Deployment

Configure your wrangler.toml:

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

Deploy with:

wrangler deploy

See the edge-cloudflare-worker example for a complete demonstration.

Stateless Mode

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.

In stateless mode:

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 the stateless: true option:

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 /ready health check endpoint will indicate when the server is running in stateless mode:

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

Core Concepts

Tools

Tools in MCP allow servers to expose executable functions that can be invoked by clients and used by LLMs to perform actions.

FastMCP uses the Standard Schema specification for defining tool parameters. This allows you to use your preferred schema validation library (like Zod, ArkType, or Valibot) as long as it implements the spec.

Zod Example:

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);
  },
});

ArkType Example:

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

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);
  },
});

Plain JSON Schema Example:

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

It requires the peer dependency ajv, which does the validation, plus ajv-formats if your schema uses format keywords such as email or uri. Both are imported the first time a tool is called, so servers that don't use this pay nothing for it.

npm install ajv ajv-formats

import { jsonSchemaAdapter } from "fastmcp";

server.addTool({
  name: "fetch-json-schema",
  description: "Fetch the content of a url (using plain JSON Schema)",
  parameters: jsonSchemaAdapter({
    type: "object",
    properties: {
      url: { type: "string", format: "uri" },
    },
    required: ["url"],
  }),
  execute: async (args) => {
    const { url } = args as { url: string };
    return await fetchWebpageContent(url);
  },
});

Works for outputSchema too. Note that FastMCP advertises every tool schema with additionalProperties: false, whatever your schema said — the same treatment Zod and Valibot schemas get.

Unlike the schema libraries above, a plain JSON Schema carries no TypeScript types, so execute receives unknown arguments. Cast or narrow them yourself.

Tools Without Parameters

When creating tools that don't require parameters, you have two options:

Omit the parameters property entirely:

server.addTool({
  name: "sayHello",
  description: "Say hello",
  // No parameters property
  execute: async () => {
    return "Hello, world!";
  },
});

Explicitly define empty parameters:

import { z } from "zod";

server.addTool({
  name: "sayHello",
  description: "Say hello",
  parameters: z.object({}), // Empty object
  execute: async () => {
    return "Hello, world!";
  },
});

[!NOTE]

Both approaches are fully compatible with all MCP clients, including Cursor. FastMCP automatically generates the proper schema in both cases.

Structured Tool Output

Tools can declare an outputSchema and return structured data. FastMCP exposes that value as MCP structuredContent, while also returning a JSON text fallback for clients that only render text content.

server.addTool({
  name: "get-weather",
  description: "Get weather for a city",
  parameters: z.object({
    city: z.string(),
  }),
  outputSchema: z.object({
    temperature: z.number(),
    humidity: z.number(),
  }),
  execute: async ({ city }) => {
    const weather = await getWeather(city);

    return {
      temperature: weather.temperature,
      humidity: weather.humidity,
    };
  },
});

You can also return explicit text content and structured content together:

server.addTool({
  name: "get-weather",
  description: "Get weather for a city",
  parameters: z.object({
    city: z.string(),
  }),
  outputSchema: z.object({
    temperature: z.number(),
    humidity: z.number(),
  }),
  execute: async ({ city }) => {
    const weather = await getWeather(city);

    return {
      content: [
        {
          type: "text",
          text: `${city}: ${weather.temperature}F`,
        },
      ],
      structuredContent: {
        temperature: weather.temperature,
        humidity: weather.humidity,
      },
    };
  },
});

When outputSchema is provided, FastMCP validates structuredContent before sending the tool result. Invalid structured output is returned to the client as a tool error instead of silently violating the advertised schema.

Tool Authorization

You can control which tools are available to authenticated users by adding an optional canAccess function to a tool's definition. This function receives the authentication context and should return true if the user is allowed to access the tool.

server.addTool({
  name: "admin-tool",
  description: "An admin-only tool",
  canAccess: (auth) => auth?.role === "admin",
  execute: async () => "Welcome, admin!",
});

Returning a string

execute can return a string:

server.addTool({
  name: "download",
  description: "Download a file",
  parameters: z.object({
    url: z.string(),
  }),
  execute: async (args) => {
    return "Hello, world!";
  },
});

The latter is equivalent to:

server.addTool({
  name: "download",
  description: "Download a file",
  parameters: z.object({
    url: z.string(),
  }),
  execute: async (args) => {
    return {
      content: [
        {
          type: "text",
          text: "Hello, world!",
        },
      ],
    };
  },
});

Returning a list

If you want to return a list of messages, you can return an object with a content property:

server.addTool({
  name: "download",
  description: "Download a file",
  parameters: z.object({
    url: z.string(),
  }),
  execute: async (args) => {
    return {
      content: [
        { type: "text", text: "First message" },
        { type: "text", text: "Second message" },
      ],
    };
  },
});

Returning an image

Use the imageContent to create a content object for an image:

import { imageContent } from "fastmcp";

server.addTool({
  name: "download",
  description: "Download a file",
  parameters: z.object({
    url: z.string(),
  }),
  execute: async (args) => {
    return imageContent({
      url: "https://example.com/image.png",
    });

    // or...
    // return imageContent({
    //   path: "/path/to/image.png",
    // });

    // or...
    // return imageContent({
    //   buffer: Buffer.from("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=", "base64"),
    // });

    // or...
    // return {
    //   content: [
    //     await imageContent(...)
    //   ],
    // };
  },
});

The imageContent function takes the following options:

url: The URL of the image.
timeoutMs: Optional timeout for a URL download in milliseconds (defaults to 30 seconds).
path: The path to the image file.
buffer: The image data as a buffer.

Only one of url, path, or buffer must be specified.

The above example is equivalent to:

server.addTool({
  name: "download",
  description: "Download a file",
  parameters: z.object({
    url: z.string(),
  }),
  execute: async (args) => {
    return {
      content: [
        {
          type: "image",
          data: "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
          mimeType: "image/png",
        },
      ],
    };
  },
});

Configurable Ping Behavior

FastMCP includes a configurable ping mechanism to maintain connection health. The ping behavior can be customized through server options:

const server = new FastMCP({
  name: "My Server",
  version: "1.0.0",
  ping: {
    // Explicitly enable or disable pings (defaults vary by transport)
    enabled: true,
    // Configure ping interval in milliseconds (default: 5000ms)
    intervalMs: 10000,
    // Set log level for ping-related messages (default: 'debug')
    logLevel: "debug",
  },
});

By default, ping behavior is optimized for each transport type:

Enabled for SSE and HTTP streaming connections (which benefit from keep-alive)
Disabled for stdio connections (where pings are typically unnecessary)

This configurable approach helps reduce log verbosity and optimize performance for different usage scenarios.

Keeping Long Tool Calls Alive (`streamKeepalive`)

Pings travel on the standalone server-to-client stream, so they never keep an individual tool call's connection open — and in stateless mode that stream does not exist at all. A tool that runs for minutes without producing output leaves its response connection silent, and an idle-connection timeout in front of the server (AWS ALB defaults to 60 seconds) closes it before the result is written.

This applies to both session modes. A stateful deployment keeps its standalone stream warm with pings while the connection carrying the tool call goes idle and is closed anyway; stateless has no standalone stream to begin with.

streamKeepalive writes periodically to the in-flight tool call's own response stream, which is the connection that would otherwise be closed. It is opt-in:

const server = new FastMCP({
  name: "My Server",
  version: "1.0.0",
  streamKeepalive: {
    // Opt in; disabled by default
    enabled: true,
    // Keep comfortably below the shortest idle timeout on the path
    intervalMs: 20000,
  },
});

Each keepalive is a notifications/message (level configurable via logLevel, default debug) tagged with the logger fastmcp-keepalive, related to the tool call being served. Keepalives start when a tool begins executing and stop when the request stops waiting for it — on success, error, timeout, or client cancellation — so idle connections stay quiet. Because the messages are related to the request, this works in stateful and stateless mode alike, and needs no client support beyond the standard logging notification.

Limits worth knowing:

It has no effect with httpStream.enableJsonResponse, which buffers a single JSON reply instead of streaming, so there is no open stream to write to.
It only covers tool calls. Other long-running requests (resources/read, prompts/get) still write nothing until they finish.
On stdio there is no proxy to keep alive, so enabling it there only adds notification traffic.

Cancelling Long Tool Calls (`context.signal`)

Every execute receives an AbortSignal that fires once its result can no longer reach anyone. Forward it to whatever does the real work so the work stops with the call instead of outliving it:

server.addTool({
  name: "fetch_report",
  parameters: z.object({ url: z.string() }),
  timeoutMs: 30000,
  execute: async (args, { signal }) => {
    const response = await fetch(args.url, { signal });
    return await response.text();
  },
});

It aborts on any of three events:

The client cancelled the call — it sent notifications/cancelled, which is what the MCP SDK emits when a caller aborts its own request.
The session ended — the transport closed, or the session was closed explicitly. No cancellation notification is involved here.
timeoutMs elapsed — signal.reason is the same UserError the caller receives, so a tool can tell a timeout apart from a cancellation.

The signal is never aborted after a call completes normally, so attaching cleanup to it is safe.

Limits worth knowing:

Nothing is killed for you. FastMCP stops waiting for the tool, but the promise execute returned keeps running until it settles. A tool that ignores the signal still runs to completion — it just does so with nowhere to report.
An HTTP client that vanishes mid-request is not detected. The MCP SDK only aborts a request's own signal for an explicit notifications/cancelled, and StreamableHTTPServerTransport does not treat an abandoned response stream as a session close. A caller that hangs up without terminating its session (DELETE) leaves the tool running until it finishes or times out. Set timeoutMs on anything expensive rather than relying on disconnect detection.
load does not get one. Resources, resource templates, and prompts receive a smaller context without signal.

Health-check Endpoint

When you run FastMCP with the httpStream transport you can optionally expose a simple HTTP endpoint that returns a plain-text response useful for load-balancer or container orchestration liveness checks.

Enable (or customise) the endpoint via the health key in the server options:

const server = new FastMCP({
  name: "My Server",
  version: "1.0.0",
  health: {
    // Enable / disable (default: true)
    enabled: true,
    // Body returned by the endpoint (default: 'ok')
    message: "healthy",
    // Path that should respond (default: '/health')
    path: "/healthz",
    // HTTP status code to return (default: 200)
    status: 200,
  },
});

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

Now a request to http://localhost:8080/healthz will return:

HTTP/1.1 200 OK
content-type: text/plain

healthy

The endpoint is ignored when the server is started with the stdio transport.

Roots Management

FastMCP supports Roots - Feature that allows clients to provide a set of filesystem-like root locations that can be listed and dynamically updated. The Roots feature can be configured or disabled in server options:

const server = new FastMCP({
  name: "My Server",
  version: "1.0.0",
  roots: {
    // Set to false to explicitly disable roots support
    enabled: false,
    // By default, roots support is enabled (true)
  },
});

This provides the following benefits:

Better compatibility with different clients that may not support Roots
Reduced error logs when connecting to clients that don't implement roots capability
More explicit control over MCP server capabilities
Graceful degradation when roots functionality isn't available

You can listen for root changes in your server:

server.on("connect", (event) => {
  const session = event.session;

  // Access the current roots
  console.log("Initial roots:", session.roots);

  // Listen for changes to the roots
  session.on("rootsChanged", (event) => {
    console.log("Roots changed:", event.roots);
  });
});

When a client doesn't support roots or when roots functionality is explicitly disabled, these operations will gracefully handle the situation without throwing errors.

Returning an audio

Use the audioContent to create a content object for an audio:

import { audioContent } from "fastmcp";

server.addTool({
  name: "download",
  description: "Download a file",
  parameters: z.object({
    url: z.string(),
  }),
  execute: async (args) => {
    return audioContent({
      url: "https://example.com/audio.mp3",
    });

    // or...
    // return audioContent({
    //   path: "/path/to/audio.mp3",
    // });

    // or...
    // return audioContent({
    //   buffer: Buffer.from("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=", "base64"),
    // });

    // or...
    // return {
    //   content: [
    //     await audioContent(...)
    //   ],
    // };
  },
});

The audioContent function takes the following options:

url: The URL of the audio.
timeoutMs: Optional timeout for a URL download in milliseconds (defaults to 30 seconds).
path: The path to the audio file.
buffer: The audio data as a buffer.

Only one of url, path, or buffer must be specified.

The above example is equivalent to:

server.addTool({
  name: "download",
  description: "Download a file",
  parameters: z.object({
    url: z.string(),
  }),
  execute: async (args) => {
    return {
      content: [
        {
          type: "audio",
          data: "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
          mimeType: "audio/mpeg",
        },
      ],
    };
  },
});

Return combination type

You can combine various types in this way and send them back to AI

server.addTool({
  name: "download",
  description: "Download a file",
  parameters: z.object({
    url: z.string(),
  }),
  execute: async (args) => {
    return {
      content: [
        {
          type: "text",
          text: "Hello, world!",
        },
        {
          type: "image",
          data: "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
          mimeType: "image/png",
        },
        {
          type: "audio",
          data: "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
          mimeType: "audio/mpeg",
        },
      ],
    };
  },

  // or...
  // execute: async (args) => {
  //   const imgContent = await imageContent({
  //     url: "https://example.com/image.png",
  //   });
  //   const audContent = await audioContent({
  //     url: "https://example.com/audio.mp3",
  //   });
  //   return {
  //     content: [
  //       {
  //         type: "text",
  //         text: "Hello, world!",
  //       },
  //       imgContent,
  //       audContent,
  //     ],
  //   };
  // },
});

Custom Logger

FastMCP allows you to provide a custom logger implementation to control how the server logs messages. This is useful for integrating with existing logging infrastructure or customizing log formatting.

import { FastMCP, Logger } from "fastmcp";

class CustomLogger implements Logger {
  debug(...args: unknown[]): void {
    console.log("[DEBUG]", new Date().toISOString(), ...args);
  }

  error(...args: unknown[]): void {
    console.error("[ERROR]", new Date().toISOString(), ...args);
  }

  info(...args: unknown[]): void {
    console.info("[INFO]", new Date().toISOString(), ...args);
  }

  log(...args: unknown[]): void {
    console.log("[LOG]", new Date().toISOString(), ...args);
  }

  warn(...args: unknown[]): void {
    console.warn("[WARN]", new Date().toISOString(), ...args);
  }
}

const server = new FastMCP({
  name: "My Server",
  version: "1.0.0",
  logger: new CustomLogger(),
});

See src/examples/custom-logger.ts for examples with Winston, Pino, and file-based logging.

Logging

Tools can log messages to the client using the log object in the context object:

server.addTool({
  name: "download",
  description: "Download a file",
  parameters: z.object({
    url: z.string(),
  }),
  execute: async (args, { log }) => {
    log.info("Downloading file...", {
      url,
    });

    // ...

    log.info("Downloaded file");

    return "done";
  },
});

The log object has the following methods:

debug(message: string, data?: SerializableValue)
error(message: string, data?: SerializableValue)
info(message: string, data?: SerializableValue)
warn(message: string, data?: SerializableValue)

Errors

The errors that are meant to be shown to the user should be thrown as UserError instances:

import { UserError } from "fastmcp";

server.addTool({
  name: "download",
  description: "Download a file",
  parameters: z.object({
    url: z.string(),
  }),
  execute: async (args) => {
    if (args.url.startsWith("https://example.com")) {
      throw new UserError("This URL is not allowed");
    }

    return "done";
  },
});

Progress

Tools can report progress by calling reportProgress in the context object:

server.addTool({
  name: "download",
  description: "Download a file",
  parameters: z.object({
    url: z.string(),
  }),
  execute: async (args, { reportProgress }) => {
    await reportProgress({
      progress: 0,
      total: 100,
    });

    // ...

    await reportProgress({
      progress: 100,
      total: 100,
    });

    return "done";
  },
});

reportProgress accepts an optional human-readable message alongside the numeric fields, which clients can display next to the progress indicator:

await reportProgress({
  progress: 40,
  total: 100,
  message: "Downloading chunk 4 of 10…",
});

Progress notifications are only emitted when the client opts in by supplying a progressToken on the tool call; otherwise reportProgress is a no-op. Because notifications/progress is part of the MCP specification (the message field since revision 2025-03-26), this is the portable way to send incremental updates during a long-running tool call — see Streaming Output below for the difference.

Streaming Output

FastMCP can stream partial results from tools while they're still executing, enabling responsive UIs and real-time feedback. This is particularly useful for:

Long-running operations that generate content incrementally
Progressive generation of text, images, or other media
Operations where users benefit from seeing immediate partial results

[!IMPORTANT] streamContent is a FastMCP extension, not part of the MCP specification. It emits a notifications/tool/streamContent notification, which the MCP specification does not define — as of revision 2025-11-25 there is no standard mechanism for streaming tool output (SEP-2998 is the in-progress proposal to add one).

Clients discard notifications they have no handler registered for, silently and without error. A client only sees streamed content if it registers a handler for the method (or sets a fallbackNotificationHandler), and no client is known to render it as tool output — MCP Inspector, for example, logs it in its notifications pane via a fallback handler, but the tool result itself still shows only what execute returned. Streaming is therefore mainly useful when you also control the client — see Consuming streamed content below. If you need incremental updates that work on any client, use reportProgress with a message instead.

To stream from a tool, use the streamContent method:

server.addTool({
  name: "generateText",
  description: "Generate text incrementally",
  parameters: z.object({
    prompt: z.string(),
  }),
  annotations: {
    streamingHint: true, // Advisory only; see below
    readOnlyHint: true,
  },
  execute: async (args, { streamContent }) => {
    // Send initial content immediately
    await streamContent({ type: "text", text: "Starting generation...\n" });

    // Simulate incremental content generation
    const words = "The quick brown fox jumps over the lazy dog.".split(" ");
    for (const word of words) {
      await streamContent({ type: "text", text: word + " " });
      await new Promise((resolve) => setTimeout(resolve, 300)); // Simulate delay
    }

    // Always return a final result. Returning nothing sends an empty tool
    // result, so clients that ignore the streamed notifications see no output
    // at all.
    return "The quick brown fox jumps over the lazy dog.";
  },
});

[!WARNING] Returning undefined from execute produces a tool result with empty content. If you stream everything and return nothing, the tool call resolves to an empty result with no indication that anything was lost — including on clients that do log the notification. Return the complete result as well, and treat streamed content purely as a progressive-rendering enhancement.

The streamingHint annotation is advisory metadata. It is forwarded verbatim to clients in tools/list, but it does not enable or gate streamContent, and FastMCP itself never reads it. No client is known to act on it today, though SEP-2998 proposes standardizing the same annotation name.

Consuming streamed content

A client sees these notifications only if it registers a handler for the method (or sets a fallbackNotificationHandler):

import { z } from "zod";

const StreamContentNotificationSchema = z.object({
  method: z.literal("notifications/tool/streamContent"),
  params: z.object({
    content: z.array(z.any()),
    toolName: z.string(),
  }),
});

client.setNotificationHandler(
  StreamContentNotificationSchema,
  (notification) => {
    const { content, toolName } = notification.params;
    // Render the partial content however you like.
  },
);

Note that notifications carry only toolName, not a request or progress token, so concurrent calls to the same tool on one session cannot be told apart.

Streaming works with all content types (text, image, audio) and can be combined with progress reporting:

server.addTool({
  name: "processData",
  description: "Process data with streaming updates",
  parameters: z.object({
    datasetSize: z.number(),
  }),
  annotations: {
    streamingHint: true,
  },
  execute: async (args, { streamContent, reportProgress }) => {
    const total = args.datasetSize;

    for (let i = 0; i < total; i++) {
      // Standard progress notification: reaches every spec-compliant client
      await reportProgress({
        progress: i,
        total,
        message: `Processed ${i} of ${total} items`,
      });

      // Richer partial content: only reaches clients that opt in
      if (i % 10 === 0) {
        await streamContent({
          type: "text",
          text: `Processed ${i} of ${total} items...\n`,
        });
      }

      await new Promise((resolve) => setTimeout(resolve, 50));
    }

    return "Processing complete!";
  },
});

Elicitation

Tools can request additional information from the user mid-execution via elicitation, using the elicit method in the context object. The client must advertise the matching elicitation capability mode — elicitation: { form: {} } for form requests (the default) and/or elicitation: { url: {} } for url requests.

server.addTool({
  name: "delete-file",
  description: "Delete a file",
  parameters: z.object({
    path: z.string(),
  }),
  execute: async (args, { elicit }) => {
    const response = await elicit({
      message: `Are you sure you want to delete ${args.path}?`,
      requestedSchema: {
        type: "object",
        properties: {
          confirmed: {
            type: "boolean",
          },
        },
        required: ["confirmed"],
      },
    });

    if (response.action !== "accept" || !response.content?.confirmed) {
      return "Deletion cancelled.";
    }

    // ...

    return `Deleted ${args.path}`;
  },
});

The response action is "accept", "decline", or "cancel"; on accept, content holds the user's answers matching requestedSchema. Elicitation is also available outside of tools via session.requestElicitation.

Tool Annotations

As of the MCP Specification (2025-03-26), tools can include annotations that provide richer context and control by adding metadata about a tool's behavior:

server.addTool({
  name: "fetch-content",
  description: "Fetch content from a URL",
  parameters: z.object({
    url: z.string(),
  }),
  annotations: {
    title: "Web Content Fetcher", // Human-readable title for UI display
    readOnlyHint: true, // Tool doesn't modify its environment
    openWorldHint: true, // Tool interacts with external entities
  },
  execute: async (args) => {
    return await fetchWebpageContent(args.url);
  },
});

The available annotations are:

Annotation	Type	Default	Description
`title`	string	-	A human-readable title for the tool, useful for UI display
`readOnlyHint`	boolean	`false`	If true, indicates the tool does not modify its environment
`destructiveHint`	boolean	`true`	If true, the tool may perform destructive updates (only meaningful when `readOnlyHint` is false)
`idempotentHint`	boolean	`false`	If true, calling the tool repeatedly with the same arguments has no additional effect (only meaningful when `readOnlyHint` is false)
`openWorldHint`	boolean	`true`	If true, the tool may interact with an "open world" of external entities

These annotations help clients and LLMs better understand how to use the tools and what to expect when calling them.

Resources

Resources represent any kind of data that an MCP server wants to make available to clients. This can include:

File contents
Screenshots and images
Log files
And more

Each resource is identified by a unique URI and can contain either text or binary data.

server.addResource({
  uri: "file:///logs/app.log",
  name: "Application Logs",
  mimeType: "text/plain",
  async load() {
    return {
      text: await readLogFile(),
    };
  },
});

[!NOTE]

load can return multiple resources. This could be used, for example, to return a list of files inside a directory when the directory is read.
async load() {
  return [
    {
      text: "First file content",
    },
    {
      text: "Second file content",
    },
  ];
}

You can also return binary contents in load:

async load() {
  return {
    blob: 'base64-encoded-data'
  };
}

load also receives auth (the value returned by your authenticate function, if any) and a context object as its second and third arguments. context mirrors the client, log, session, and sessionId fields available to tool.execute (see Session ID and Request ID Tracking); reportProgress and streamContent are not included since they are tied to a tool call's progress token:

server.addResource({
  uri: "file:///logs/app.log",
  name: "Application Logs",
  mimeType: "text/plain",
  async load(auth, context) {
    context.log.info("loading application logs", { requestedBy: auth?.userId });

    return {
      text: await readLogFile(),
    };
  },
});

Subscribing to resource updates

Clients can subscribe to a resource with the MCP resources/subscribe method to be notified whenever its contents change. FastMCP advertises the subscribe capability automatically for any server that exposes resources, tracks each client's subscriptions, and lets you emit an update with sendResourceUpdated:

server.addResource({
  uri: "file:///logs/app.log",
  name: "Application Logs",
  mimeType: "text/plain",
  async load() {
    return { text: await readLogFile() };
  },
});

// Whenever the underlying data changes, notify subscribed clients:
await server.sendResourceUpdated("file:///logs/app.log");

sendResourceUpdated only notifies clients that have subscribed to the given URI, so it is safe to call whenever your data changes. FastMCP also advertises the listChanged capability for resources and prompts and emits notifications/resources/list_changed / notifications/prompts/list_changed automatically when you add or remove resources, resource templates, or prompts at runtime.

Resource templates

You can also define resource templates:

server.addResourceTemplate({
  uriTemplate: "file:///logs/{name}.log",
  name: "Application Logs",
  mimeType: "text/plain",
  arguments: [
    {
      name: "name",
      description: "Name of the log",
      required: true,
    },
  ],
  async load({ name }) {
    return {
      text: `Example log content for ${name}`,
    };
  },
});

Like plain resources, load also receives auth and context as its second and third arguments (see Resources).

Resource template argument auto-completion

Provide complete functions for resource template arguments to enable automatic completion:

server.addResourceTemplate({
  uriTemplate: "file:///logs/{name}.log",
  name: "Application Logs",
  mimeType: "text/plain",
  arguments: [
    {
      name: "name",
      description: "Name of the log",
      required: true,
      complete: async (value) => {
        if (value === "Example") {
          return {
            values: ["Example Log"],
          };
        }

        return {
          values: [],
        };
      },
    },
  ],
  async load({ name }) {
    return {
      text: `Example log content for ${name}`,
    };
  },
});

Embedded Resources

FastMCP provides a convenient embedded() method that simplifies including resources in tool responses. This feature reduces code duplication and makes it easier to reference resources from within tools.

Basic Usage

server.addTool({
  name: "get_user_data",
  description: "Retrieve user information",
  parameters: z.object({
    userId: z.string(),
  }),
  execute: async (args) => {
    return {
      content: [
        {
          type: "resource",
          resource: await server.embedded(`user://profile/${args.userId}`),
        },
      ],
    };
  },
});

Working with Resource Templates

The embedded() method works seamlessly with resource templates:

// Define a resource template
server.addResourceTemplate({
  uriTemplate: "docs://project/{section}",
  name: "Project Documentation",
  mimeType: "text/markdown",
  arguments: [
    {
      name: "section",
      required: true,
    },
  ],
  async load(args) {
    const docs = {
      "getting-started": "# Getting Started\n\nWelcome to our project!",
      "api-reference": "# API Reference\n\nAuthentication is required.",
    };
    return {
      text: docs[args.section] || "Documentation not found",
    };
  },
});

// Use embedded resources in a tool
server.addTool({
  name: "get_documentation",
  description: "Retrieve project documentation",
  parameters: z.object({
    section: z.enum(["getting-started", "api-reference"]),
  }),
  execute: async (args) => {
    return {
      content: [
        {
          type: "resource",
          resource: await server.embedded(`docs://project/${args.section}`),
        },
      ],
    };
  },
});

Working with Direct Resources

It also works with directly defined resources:

// Define a direct resource
server.addResource({
  uri: "system://status",
  name: "System Status",
  mimeType: "text/plain",
  async load() {
    return {
      text: "System operational",
    };
  },
});

// Use in a tool
server.addTool({
  name: "get_system_status",
  description: "Get current system status",
  parameters: z.object({}),
  execute: async () => {
    return {
      content: [
        {
          type: "resource",
          resource: await server.embedded("system://status"),
        },
      ],
    };
  },
});

Prompts

Prompts enable servers to define reusable prompt templates and workflows that clients can easily surface to users and LLMs. They provide a powerful way to standardize and share common LLM interactions.

server.addPrompt({
  name: "git-commit",
  description: "Generate a Git commit message",
  arguments: [
    {
      name: "changes",
      description: "Git diff or description of changes",
      required: true,
    },
  ],
  load: async (args) => {
    return `Generate a concise but descriptive commit message for these changes:\n\n${args.changes}`;
  },
});

Like resources, load also receives auth and context as its second and third arguments (see Resources):

server.addPrompt({
  name: "git-commit",
  description: "Generate a Git commit message",
  arguments: [
    {
      name: "changes",
      description: "Git diff or description of changes",
      required: true,
    },
  ],
  load: async (args, auth, context) => {
    context.log.debug("generating git commit prompt", { user: auth?.userId });

    return `Generate a concise but descriptive commit message for these changes:\n\n${args.changes}`;
  },
});

Prompt argument auto-completion

Prompts can provide auto-completion for their arguments:

server.addPrompt({
  name: "countryPoem",
  description: "Writes a poem about a country",
  load: async ({ name }) => {
    return `Hello, ${name}!`;
  },
  arguments: [
    {
      name: "name",
      description: "Name of the country",
      required: true,
      complete: async (value) => {
        if (value === "Germ") {
          return {
            values: ["Germany"],
          };
        }

        return {
          values: [],
        };
      },
    },
  ],
});

Prompt argument auto-completion using `enum`

If you provide an enum array for an argument, the server will automatically provide completions for the argument.

server.addPrompt({
  name: "countryPoem",
  description: "Writes a poem about a country",
  load: async ({ name }) => {
    return `Hello, ${name}!`;
  },
  arguments: [
    {
      name: "name",
      description: "Name of the country",
      required: true,
      enum: ["Germany", "France", "Italy"],
    },
  ],
});

Authentication

FastMCP supports OAuth 2.1 authentication with pre-configured providers, allowing you to secure your server with minimal setup.

OAuth with Pre-configured Providers

Use the auth option with a provider to enable OAuth authentication:

import { FastMCP, getAuthSession, GoogleProvider, requireAuth } from "fastmcp";

const server = new FastMCP({
  auth: new GoogleProvider({
    baseUrl: "https://your-server.com",
    clientId: process.env.GOOGLE_CLIENT_ID!,
    clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
  }),
  name: "My Server",
  version: "1.0.0",
});

server.addTool({
  canAccess: requireAuth,
  description: "Get user profile",
  execute: async (_args, { session }) => {
    const { accessToken } = getAuthSession(session);
    const response = await fetch(
      "https://www.googleapis.com/oauth2/v2/userinfo",
      {
        headers: { Authorization: `Bearer ${accessToken}` },
      },
    );
    return JSON.stringify(await response.json());
  },
  name: "get-profile",
});

Available Providers:

Provider	Import	Use Case
`GoogleProvider`	`fastmcp`	Google OAuth
`GitHubProvider`	`fastmcp`	GitHub OAuth
`AzureProvider`	`fastmcp`	Azure/Entra ID
`OAuthProvider`	`fastmcp`	Any OAuth 2.0 provider

Generic OAuth Provider (for SAP, Auth0, Okta, etc.):

import { FastMCP, OAuthProvider } from "fastmcp";

const server = new FastMCP({
  auth: new OAuthProvider({
    authorizationEndpoint: process.env.OAUTH_AUTH_ENDPOINT!,
    baseUrl: "https://your-server.com",
    clientId: process.env.OAUTH_CLIENT_ID!,
    clientSecret: process.env.OAUTH_CLIENT_SECRET!,
    scopes: ["openid", "profile"],
    tokenEndpoint: process.env.OAUTH_TOKEN_ENDPOINT!,
  }),
  name: "My Server",
  version: "1.0.0",
});

Tool Authorization

Control tool access using the canAccess property with built-in helper functions:

import {
  requireAuth,
  requireScopes,
  requireRole,
  requireAll,
  requireAny,
  getAuthSession,
} from "fastmcp";

// Require any authenticated user
server.addTool({
  canAccess: requireAuth,
  name: "user-tool",
  // ...
});

// Require specific OAuth scopes
server.addTool({
  canAccess: requireScopes("read:user", "write:data"),
  name: "scoped-tool",
  // ...
});

// Require specific role
server.addTool({
  canAccess: requireRole("admin"),
  name: "admin-tool",
  // ...
});

// Combine with AND logic
server.addTool({
  canAccess: requireAll(requireAuth, requireRole("admin")),
  name: "admin-only",
  // ...
});

// Combine with OR logic
server.addTool({
  canAccess: requireAny(requireRole("admin"), requireRole("moderator")),
  name: "staff-tool",
  // ...
});

Custom Authorization:

For custom logic, pass a function directly:

server.addTool({
  name: "custom-auth-tool",
  canAccess: (auth) =>
    auth?.role === "admin" && auth?.department === "engineering",
  execute: async () => "Access granted!",
});

Extracting Session Data:

Use getAuthSession for type-safe access to the OAuth session in your tool execute functions:

import { getAuthSession, GoogleSession } from "fastmcp";

server.addTool({
  canAccess: requireAuth,
  name: "get-profile",
  execute: async (_args, { session }) => {
    // Type-safe destructuring (throws if not authenticated)
    const { accessToken } = getAuthSession(session);

    // Or with provider-specific typing:
    // const { accessToken } = getAuthSession<GoogleSession>(session);

    const response = await fetch("https://api.example.com/user", {
      headers: { Authorization: `Bearer ${accessToken}` },
    });
    return JSON.stringify(await response.json());
  },
});

Note: You can also access session.accessToken directly, but you must handle the case where session is undefined. The getAuthSession helper throws a clear error if the session is not authenticated, making it safer when used with canAccess: requireAuth.

Custom Authentication

For non-OAuth scenarios (API keys, custom tokens), use the authenticate option:

const server = new FastMCP({
  name: "My Server",
  version: "1.0.0",
  authenticate: (request) => {
    const apiKey = request.headers["x-api-key"];

    if (apiKey !== "123") {
      throw new Response(null, {
        status: 401,
        statusText: "Unauthorized",
      });
    }

    return { id: 1, role: "user" };
  },
});

server.addTool({
  name: "sayHello",
  execute: async (args, { session }) => {
    return `Hello, ${session.id}!`;
  },
});

OAuth Proxy

The auth option uses FastMCP's built-in OAuth Proxy that acts as a secure intermediary between MCP clients and upstream OAuth providers. The proxy handles the complete OAuth 2.1 authorization flow, including Dynamic Client Registration (DCR), PKCE, consent management, and token management with encryption and token swap patterns enabled by default.

Key Features:

🔐 Secure by Default: Automatic encryption (AES-256-GCM) and token swap pattern
🚀 Zero Configuration: Auto-generates keys and handles OAuth flows automatically
🔌 Pre-configured Providers: Built-in support for Google, GitHub, and Azure
🎯 RFC Compliant: Implements DCR (RFC 7591), PKCE, and OAuth 2.1
🔑 Optional JWKS: Support for RS256/ES256 token verification (via optional jose dependency)

Quick Start:

import { FastMCP, getAuthSession, GoogleProvider, requireAuth } from "fastmcp";

const server = new FastMCP({
  auth: new GoogleProvider({
    baseUrl: "https://your-server.com",
    clientId: process.env.GOOGLE_CLIENT_ID!,
    clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
  }),
  name: "My Server",
  version: "1.0.0",
});

server.addTool({
  canAccess: requireAuth,
  name: "protected-tool",
  execute: async (_args, { session }) => {
    const { accessToken } = getAuthSession(session);
    // Use accessToken to call upstream APIs
    return "Authenticated!";
  },
});

Advanced Configuration:

For more control over OAuth behavior, you can use the oauth option directly:

import { FastMCP } from "fastmcp";
import { GoogleProvider } from "fastmcp/auth";

const authProvider = new GoogleProvider({
  baseUrl: "https://your-server.com",
  clientId: process.env.GOOGLE_CLIENT_ID!,
  clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
  scopes: ["openid", "profile", "email"],
});

const server = new FastMCP({
  name: "My Server",
  oauth: {
    authorizationServer: authProvider
      .getProxy()
      .getAuthorizationServerMetadata(),
    enabled: true,
    proxy: authProvider.getProxy(),
  },
  version: "1.0.0",
});

Documentation:

OAuth Proxy Features - Complete feature list and capabilities
OAuth Proxy Implementation Guide - Setup and configuration
Python vs TypeScript Comparison - Feature comparison

OAuth Discovery Endpoints

FastMCP also supports OAuth discovery endpoints for direct integration with OAuth providers, supporting both MCP Specification 2025-03-26 and MCP Specification 2025-06-18. This provides standard discovery endpoints that comply with RFC 8414 (OAuth 2.0 Authorization Server Metadata) and RFC 9470 (OAuth 2.0 Protected Resource Metadata):

import { FastMCP } from "fastmcp";
import buildGetJwks from "get-jwks";
import fastJwt, { type DecodedJwt } from "fast-jwt";

const server = new FastMCP({
  name: "My Server",
  version: "1.0.0",
  oauth: {
    enabled: true,
    authorizationServer: {
      issuer: "https://auth.example.com",
      authorizationEndpoint: "https://auth.example.com/oauth/authorize",
      tokenEndpoint: "https://auth.example.com/oauth/token",
      jwksUri: "https://auth.example.com/.well-known/jwks.json",
      responseTypesSupported: ["code"],
    },
    protectedResource: {
      resource: "mcp://my-server",
      authorizationServers: ["https://auth.example.com"],
    },
  },
  authenticate: async (request) => {
    const authHeader = request.headers.authorization;

    if (!authHeader?.startsWith("Bearer ")) {
      throw new Response(null, {
        status: 401,
        statusText: "Missing or invalid authorization header",
      });
    }

    const token = authHeader.slice(7); // Remove 'Bearer ' prefix

    // Validate OAuth JWT access token using OpenID Connect discovery
    try {
      // Create JWKS client for token verification
      const getJwks = buildGetJwks();

      // Create JWT verifier
      const verify = fastJwt.createVerifier({
        async key({ header }: DecodedJwt) {
          const publicKey = await getJwks.getPublicKey({
            kid: header.kid,
            alg: header.alg,
            domain: "https://auth.example.com",
          });
          return publicKey;
        },
        algorithms: ["RS256"],
      });

      // Verify the JWT token
      const payload = await verify(token);

      return {
        userId: payload.sub,
        scope: payload.scope,
        email: payload.email,
        // Include other claims as needed
      };
    } catch (error) {
      throw new Response(null, {
        status: 401,
        statusText: "Invalid OAuth token",
      });
    }
  },
});

If your MCP server is published below an issuer path, configure the HTTP stream base path as well:

server.start({
  transportType: "httpStream",
  httpStream: {
    basePath: "/issuer1",
    endpoint: "/mcp",
    port: 8080,
  },
});

With this configuration, FastMCP serves the issuer-path authorization server metadata at /.well-known/oauth-authorization-server/issuer1, while protected resource metadata remains available for the MCP endpoint at /.well-known/oauth-protected-resource/issuer1/mcp.

This configuration automatically exposes OAuth discovery endpoints:

/.well-known/oauth-authorization-server - Authorization server metadata (RFC 8414)
/.well-known/oauth-authorization-server<basePath> - Authorization server metadata when httpStream.basePath is set (RFC 8414 Section 3)
/.well-known/oauth-protected-resource - Protected resource metadata (RFC 9728)
/.well-known/oauth-protected-resource<endpoint> - Protected resource metadata at sub-path (MCP 2025-11-25)

Discovery Mechanism (MCP Specification 2025-11-25):

Clients discover protected resource metadata using the following search order:

WWW-Authenticate header - Primary method (handled automatically by mcp-proxy)
Sub-path well-known - /.well-known/oauth-protected-resource<endpoint> (e.g., /.well-known/oauth-protected-resource/mcp)
Root well-known - /.well-known/oauth-protected-resource (fallback)

Both the sub-path and root endpoints return identical metadata, ensuring compatibility with all MCP client implementations.

For JWT token validation, you can use libraries like get-jwks and fast-jwt for OAuth JWT tokens.

Passing Headers Through Context

If you are exposing your MCP server via HTTP, you may wish to allow clients to supply sensitive keys via headers, which can then be passed along to APIs that your tools interact with, allowing each client to supply their own API keys. This can be done by capturing the HTTP headers in the authenticate section and storing them in the session to be referenced by the tools later.

import { FastMCP } from "fastmcp";
import { IncomingHttpHeaders } from "http";

// Define the session data type
interface SessionData {
  headers: IncomingHttpHeaders;
  [key: string]: unknown; // Add index signature to satisfy Record<string, unknown>
}

// Create a server instance
const server = new FastMCP({
  name: "My Server",
  version: "1.0.0",
  authenticate: async (request: any): Promise<SessionData> => {
    // Authentication logic
    return {
      headers: request.headers,
    };
  },
});

// Tool to display HTTP headers
server.addTool({
  name: "headerTool",
  description: "Reads HTTP headers from the request",
  execute: async (args: any, context: any) => {
    const session = context.session as SessionData;
    const headers = session?.headers ?? {};

    const getHeaderString = (header: string | string[] | undefined) =>
      Array.isArray(header) ? header.join(", ") : (header ?? "N/A");

    const userAgent = getHeaderString(headers["user-agent"]);
    const authorization = getHeaderString(headers["authorization"]);
    return `User-Agent: ${userAgent}\nAuthorization: ${authorization}\nAll Headers: ${JSON.stringify(headers, null, 2)}`;
  },
});

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

A client that would connect to this may look something like this:

import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";

const transport = new StreamableHTTPClientTransport(
  new URL(`http://localhost:8080/mcp`),
  {
    requestInit: {
      headers: {
        Authorization: "Test 123",
      },
    },
  },
);

const client = new Client({
  name: "example-client",
  version: "1.0.0",
});

(async () => {
  await client.connect(transport);

  // Call a tool
  const result = await client.callTool({
    name: "headerTool",
    arguments: {
      arg1: "value",
    },
  });

  console.log("Tool result:", result);
})().catch(console.error);

What would show up in the console after the client runs is something like this:

Tool result: {
  content: [
    {
      type: 'text',
      text: 'User-Agent: node\n' +
        'Authorization: Test 123\n' +
        'All Headers: {\n' +
        '  "host": "localhost:8080",\n' +
        '  "connection": "keep-alive",\n' +
        '  "authorization": "Test 123",\n' +
        '  "content-type": "application/json",\n' +
        '  "accept": "application/json, text/event-stream",\n' +
        '  "accept-language": "*",\n' +
        '  "sec-fetch-mode": "cors",\n' +
        '  "user-agent": "node",\n' +
        '  "accept-encoding": "gzip, deflate",\n' +
        '  "content-length": "163"\n' +
        '}'
    }
  ]
}

Session ID and Request ID Tracking

FastMCP automatically exposes session and request IDs to tool handlers through the context parameter. This enables per-session state management and request tracking.

Session ID (context.sessionId):

Available only for HTTP-based transports (HTTP Stream, SSE)
Extracted from the Mcp-Session-Id header
Remains constant across multiple requests from the same client
Useful for maintaining per-session state, counters, or user-specific data

Request ID (context.requestId):

Available for all transports when provided by the client
Unique for each individual request
Useful for request tracing and debugging

import { FastMCP } from "fastmcp";
import { z } from "zod";

const server = new FastMCP({
  name: "Session Counter Server",
  version: "1.0.0",
});

// Per-session counter storage
const sessionCounters = new Map<string, number>();

server.addTool({
  name: "increment_counter",
  description: "Increment a per-session counter",
  parameters: z.object({}),
  execute: async (args, context) => {
    if (!context.sessionId) {
      return "Session ID not available (requires HTTP transport)";
    }

    const counter = sessionCounters.get(context.sessionId) || 0;
    const newCounter = counter + 1;
    sessionCounters.set(context.sessionId, newCounter);

    return `Counter for session ${context.sessionId}: ${newCounter}`;
  },
});

server.addTool({
  name: "show_ids",
  description: "Display session and request IDs",
  parameters: z.object({}),
  execute: async (args, context) => {
    return `Session ID: ${context.sessionId || "N/A"}
Request ID: ${context.requestId || "N/A"}`;
  },
});

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

Use Cases:

Per-session state management: Maintain counters, caches, or temporary data unique to each client session
User authentication and authorization: Track authenticated users across requests
Session-specific resource management: Allocate and manage resources per session
Multi-tenant implementations: Isolate data and operations by session
Request tracing: Track individual requests for debugging and monitoring

Example:

See src/examples/session-id-counter.ts for a complete example demonstrating session-based counter management.

Notes:

Session IDs are automatically generated by the MCP transport layer
In stateless mode, session IDs are not persisted across requests
For stdio transport, sessionId will be undefined as there's no HTTP session concept

Providing Instructions

You can provide instructions to the server using the instructions option:

const server = new FastMCP({
  name: "My Server",
  version: "1.0.0",
  instructions:
    'Instructions describing how to use the server and its features.\n\nThis can be used by clients to improve the LLM\'s understanding of available tools, resources, etc. It can be thought of like a "hint" to the model. For example, this information MAY be added to the system prompt.',
});

Server icons and metadata

You can advertise icons and related metadata for your server. Clients that support icons can show them in their UI:

const server = new FastMCP({
  name: "My Server",
  version: "1.0.0",
  websiteUrl: "https://example.com",
  icons: [
    {
      src: "https://example.com/icon.png",
      mimeType: "image/png",
      sizes: ["48x48"],
    },
  ],
});

An optional title is also passed through to MCP initialize (serverInfo), for clients that prefer a display name over the server name.

Sessions

The session object is an instance of FastMCPSession and it describes active client sessions.

server.sessions;

We allocate a new server instance for each client connection to enable 1:1 communication between a client and the server.

Typed server events

You can listen to events emitted by the server using the on method:

server.on("connect", (event) => {
  console.log("Client connected:", event.session);
});

server.on("disconnect", (event) => {
  console.log("Client disconnected:", event.session);
});

`FastMCPSession`

FastMCPSession represents a client session and provides methods to interact with the client.

Refer to Sessions for examples of how to obtain a FastMCPSession instance.

`requestElicitation`

requestElicitation creates an elicitation request to collect additional information from the user via the client and returns the response. The client must advertise the matching elicitation capability mode — elicitation: { form: {} } for form requests (the default) and/or elicitation: { url: {} } for url requests.

await session.requestElicitation({
  message: "What is your name?",
  requestedSchema: {
    type: "object",
    properties: {
      name: { type: "string" },
    },
    required: ["name"],
  },
});

Inside a tool, prefer the elicit method from the context object.

`requestSampling`

requestSampling creates a sampling request and returns the response.

await session.requestSampling({
  messages: [
    {
      role: "user",
      content: {
        type: "text",
        text: "What files are in the current directory?",
      },
    },
  ],
  systemPrompt: "You are a helpful file system assistant.",
  includeContext: "thisServer",
  maxTokens: 100,
});

Options

requestSampling accepts an optional second parameter for request options:

await session.requestSampling(
  {
    messages: [
      {
        role: "user",
        content: {
          type: "text",
          text: "What files are in the current directory?",
        },
      },
    ],
    systemPrompt: "You are a helpful file system assistant.",
    includeContext: "thisServer",
    maxTokens: 100,
  },
  {
    // Progress callback - called when progress notifications are received
    onprogress: (progress) => {
      console.log(`Progress: ${progress.progress}/${progress.total}`);
    },

    // Abort signal for cancelling the request
    signal: abortController.signal,

    // Request timeout in milliseconds (default: DEFAULT_REQUEST_TIMEOUT_MSEC)
    timeout: 30000,

    // Whether progress notifications reset the timeout (default: false)
    resetTimeoutOnProgress: true,

    // Maximum total timeout regardless of progress (no default)
    maxTotalTimeout: 60000,
  },
);

Options:

onprogress?: (progress: Progress) => void - Callback for progress notifications from the remote end
signal?: AbortSignal - Abort signal to cancel the request
timeout?: number - Request timeout in milliseconds
resetTimeoutOnProgress?: boolean - Whether progress notifications reset the timeout
maxTotalTimeout?: number - Maximum total timeout regardless of progress notifications

`clientCapabilities`

The clientCapabilities property contains the client capabilities.

session.clientCapabilities;

`loggingLevel`

The loggingLevel property describes the logging level as set by the client.

session.loggingLevel;

`roots`

The roots property contains the roots as set by the client.

session.roots;

`server`

The server property contains an instance of MCP server that is associated with the session.

session.server;

Typed session events

You can listen to events emitted by the session using the on method:

session.on("rootsChanged", (event) => {
  console.log("Roots changed:", event.roots);
});

session.on("error", (event) => {
  console.error("Error:", event.error);
});

Running Your Server

Unit testing with an in-memory transport

server.connect(transport) attaches the server to a transport you construct yourself, instead of letting start() create one. Paired with the SDK's InMemoryTransport, this lets you drive a server in-process — no port to bind, no subprocess to spawn — which is usually what you want for testing a stdio server:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";

async function createTestClient(server: FastMCP) {
  const [clientTransport, serverTransport] =
    InMemoryTransport.createLinkedPair();

  const client = new Client({ name: "test-client", version: "0.0.0" });

  const [session] = await Promise.all([
    server.connect(serverTransport),
    client.connect(clientTransport),
  ]);

  return { client, session };
}

test("adds two numbers", async () => {
  const { client } = await createTestClient(server);

  expect(
    await client.callTool({ arguments: { a: 2, b: 3 }, name: "add" }),
  ).toEqual({
    content: [{ text: "5", type: "text" }],
  });

  await client.close();
});

The session is built from the tools, resources and prompts registered on the instance, exactly as start() builds it, so your tests exercise the same wiring the real server uses — including canAccess filtering and the connect/disconnect events.

Pass session auth as the second argument, equivalent to what your authenticate function would return:

await server.connect(serverTransport, { id: 7, role: "admin" });

connect returns the FastMCPSession, so you can assert on session.clientCapabilities, session.roots, and the rest. The transport's lifecycle belongs to you: stop() does not close transports passed to connect, so close the client (and the session, if you need disconnect to fire) when the test finishes.

Test with `mcp-cli`

The fastest way to test and debug your server is with fastmcp dev:

npx fastmcp dev server.js
npx fastmcp dev server.ts

This will run your server with mcp-cli for testing and debugging your MCP server in the terminal.

To call a tool non-interactively (for example, in scripts or automated tests), pass --tool and optional JSON --args:

npx fastmcp dev server.ts --tool add --args '{"a":1,"b":2}'

This prints the tool result as JSON and exits, instead of opening the interactive inspector. --watch has no effect in this mode, since the server is started for a single call.

Inspect with `MCP Inspector`

Another way is to use the official MCP Inspector to inspect your server with a Web UI:

npx fastmcp inspect server.ts

FAQ

How to use with Claude Desktop?

Follow the guide https://modelcontextprotocol.io/quickstart/user and add the following configuration:

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "npx",
      "args": ["tsx", "/PATH/TO/YOUR_PROJECT/src/index.ts"],
      "env": {
        "YOUR_ENV_VAR": "value"
      }
    }
  }
}

How to run FastMCP behind a proxy?

Refer to this issue for an example of using FastMCP with express and http-proxy-middleware.

Showcase

[!NOTE]

If you've developed a server using FastMCP, please submit a PR to showcase it here!

[!NOTE]

If you are looking for a boilerplate repository to build your own MCP server, check out fastmcp-boilerplate.

apinetwork/piapi-mcp-server - generate media using Midjourney/Flux/Kling/LumaLabs/Udio/Chrip/Trellis
domdomegg/computer-use-mcp - controls your computer
LiterallyBlah/Dradis-MCP – manages projects and vulnerabilities in Dradis
Meeting-Baas/meeting-mcp - create meeting bots, search transcripts, and manage recording data
drumnation/unsplash-smart-mcp-server – enables AI agents to seamlessly search, recommend, and deliver professional stock photos from Unsplash
ssmanji89/halopsa-workflows-mcp - HaloPSA Workflows integration with AI assistants
aiamblichus/mcp-chat-adapter – provides a clean interface for LLMs to use chat completion
eyaltoledano/claude-task-master – advanced AI project/task manager powered by FastMCP
cswkim/discogs-mcp-server - connects to the Discogs API for interacting with your music collection
Panzer-Jack/feuse-mcp - Frontend Useful MCP Tools - Essential utilities for web developers to automate API integration and code generation
sunra-ai/sunra-clients - Sunra.ai is a generative media platform built for developers, providing high-performance AI model inference capabilities.
foxtrottwist/shortcuts-mcp - connects Claude to macOS Shortcuts for system automation, app integration, and interactive workflows

Acknowledgements

FastMCP is inspired by the Python implementation by Jonathan Lowin.
Parts of codebase were adopted from LiteMCP.
Parts of codebase were adopted from Model Context protocolでSSEをやってみる.

This project is tested with BrowserStack.

FastMCP

FastMCP Overview

FastMCP

What is FastMCP about?

How to use FastMCP?

Key Features

Use Cases

FAQ

FastMCP's README

FastMCP

Features

When to use FastMCP over the official SDK?

Installation

Quickstart

Remote Server Options

HTTP Streaming

Custom HTTP Routes

Edge Runtime Support

Stateless Mode

Core Concepts

Tools

Tools Without Parameters

Structured Tool Output

Tool Authorization

Returning a string

Returning a list

Returning an image

Configurable Ping Behavior

Keeping Long Tool Calls Alive (streamKeepalive)

Cancelling Long Tool Calls (context.signal)

Health-check Endpoint

Roots Management

Returning an audio

Return combination type

Custom Logger

Logging

Errors

Progress

Streaming Output

Elicitation

Tool Annotations

Resources

Subscribing to resource updates

Resource templates

Resource template argument auto-completion

Embedded Resources

Basic Usage

Working with Resource Templates

Working with Direct Resources

Prompts

Prompt argument auto-completion

Prompt argument auto-completion using enum

Authentication

OAuth with Pre-configured Providers

Tool Authorization

Custom Authentication

OAuth Proxy

OAuth Discovery Endpoints

Passing Headers Through Context

Session ID and Request ID Tracking

Providing Instructions

Server icons and metadata

Sessions

Typed server events

FastMCPSession

requestElicitation

requestSampling

Options

clientCapabilities

loggingLevel

roots

server

Typed session events

Running Your Server

Unit testing with an in-memory transport

Test with mcp-cli

Inspect with MCP Inspector

FAQ

How to use with Claude Desktop?

How to run FastMCP behind a proxy?

Keeping Long Tool Calls Alive (`streamKeepalive`)

Cancelling Long Tool Calls (`context.signal`)

Prompt argument auto-completion using `enum`

`FastMCPSession`

`requestElicitation`

`requestSampling`

`clientCapabilities`

`loggingLevel`

`roots`

`server`

Test with `mcp-cli`

Inspect with `MCP Inspector`