FastMCP

Main FastMCP class for creating MCP servers

The FastMCP class is the core of FastMCP for Node.js environments. It provides a fluent API for building Model Context Protocol servers with tools, resources, prompts, and OAuth support.

Constructor

Create a new FastMCP server instance.

import { FastMCP } from "fastmcp";

const server = new FastMCP({
  name: "my-server",
  version: "1.0.0",
});

name · string · required

Server name identifier

version · string · required

Semantic version string (e.g., “1.0.0”)

instructions · string

Server-level instructions or description

logger · Logger

Custom logger instance (defaults to console)

auth · AuthProvider

Authentication provider for OAuth flows. When provided, automatically configures authentication and OAuth endpoints.

import { FastMCP, GitHubProvider } from "fastmcp";

const server = new FastMCP({
  name: "my-server",
  version: "1.0.0",
  auth: new GitHubProvider({
    baseUrl: "http://localhost:8000",
    clientId: process.env.GITHUB_CLIENT_ID!,
    clientSecret: process.env.GITHUB_CLIENT_SECRET!,
  }),
});

authenticate · (request: IncomingMessage) => Promise<T>

Custom authentication function. Takes precedence over auth provider if both are specified.

health · object

Health check endpoint configuration (HTTP Stream transport only)

Show properties

enabled · boolean · default: "true"

Enable or disable health check endpoint

path · string · default: "/health"

HTTP path for health check

message · string · default: "ok"

Plain-text response message

status · number · default: "200"

HTTP status code to return

oauth · object

OAuth discovery endpoint configuration (HTTP-based transports only)

Show properties

enabled · boolean · required

Enable OAuth discovery endpoints

authorizationServer · object

OAuth Authorization Server metadata (RFC 8414)

Show properties

issuer · string · required

Authorization server identifier URL

authorizationEndpoint · string · required

Authorization endpoint URL

tokenEndpoint · string · required

Token endpoint URL

responseTypesSupported · string[] · required

Supported OAuth response types

scopesSupported · string[]

Supported OAuth scopes

codeChallengeMethodsSupported · string[]

Supported PKCE challenge methods

protectedResource · object

OAuth Protected Resource metadata (RFC 9728)

Show properties

resource · string · required

Canonical resource identifier (typically the base URL)

authorizationServers · string[] · required

List of authorization server issuer identifiers

scopesSupported · string[]

Supported OAuth scopes for this resource

proxy · OAuthProxy

OAuthProxy instance for automatic OAuth flow handling

ping · object

Server ping configuration

Show properties

enabled · boolean

Enable ping (auto-enabled for SSE/HTTP Stream)

intervalMs · number · default: "5000"

Ping interval in milliseconds

logLevel · LoggingLevel · default: "debug"

Logging level for ping messages (“debug” | “info” | “warning” | “error”)

roots · object

Roots capability configuration

Show properties

enabled · boolean · default: "true"

Enable or disable roots support

Methods

addTool()

Register a tool that can be called by the MCP client.

server.addTool({
  name: "get_weather",
  description: "Get current weather for a location",
  parameters: z.object({
    location: z.string(),
  }),
  execute: async ({ location }) => {
    return `Weather in ${location}: Sunny, 72°F`;
  },
});

tool · Tool · required

Tool configuration object

Show properties

name · string · required

Unique tool identifier

description · string

Human-readable tool description

parameters · StandardSchemaV1

Parameter schema (Zod, ArkType, Valibot, etc.)

execute · (args, context) => Promise<string | Content | ContentResult> · required

Tool execution function. Returns text, Content, or ContentResult.

canAccess · (auth) => boolean

Authorization check function

timeoutMs · number

Tool execution timeout in milliseconds

annotations · ToolAnnotations

Tool behavior hints (readOnlyHint, destructiveHint, etc.)

addResource()

Register a static resource that can be read by the MCP client.

server.addResource({
  uri: "file:///config.json",
  name: "Configuration",
  description: "Server configuration",
  mimeType: "application/json",
  load: async () => ({
    text: JSON.stringify({ version: "1.0.0" }),
  }),
});

resource · Resource · required

Resource configuration object

Show properties

uri · string · required

Unique resource identifier (URI)

name · string · required

Resource display name

description · string

Human-readable resource description

mimeType · string

MIME type of the resource content

load · (auth?) => Promise<ResourceResult | ResourceResult[]> · required

Function that loads and returns resource content

canAccess · (auth) => boolean

Authorization check function

addResourceTemplate()

Register a dynamic resource template with URI parameters.

server.addResourceTemplate({
  uriTemplate: "file:///{path}",
  name: "File",
  description: "Read a file",
  mimeType: "text/plain",
  arguments: [
    { name: "path", description: "File path", required: true },
  ],
  load: async ({ path }) => ({
    text: await readFile(path, "utf-8"),
  }),
});

template · ResourceTemplate · required

Resource template configuration

Show properties

uriTemplate · string · required

URI template with parameters (RFC 6570)

name · string · required

Template display name

description · string

Human-readable template description

mimeType · string

MIME type of the resource content

arguments · ResourceTemplateArgument[] · required

Template parameter definitions

load · (args, auth?) => Promise<ResourceResult | ResourceResult[]> · required

Function that loads resource with resolved parameters

addPrompt()

Register a prompt template.

server.addPrompt({
  name: "code_review",
  description: "Review code for best practices",
  arguments: [
    { name: "language", description: "Programming language", required: true },
  ],
  load: async ({ language }) => ({
    messages: [
      {
        role: "user",
        content: { type: "text", text: `Review this ${language} code...` },
      },
    ],
  }),
});

prompt · Prompt · required

Prompt configuration object

Show properties

name · string · required

Unique prompt identifier

description · string

Human-readable prompt description

arguments · PromptArgument[]

Prompt argument definitions

load · (args, auth?) => Promise<PromptResult> · required

Function that generates prompt messages

addRoute()

Register a custom HTTP route (HTTP Stream transport only).

server.addRoute("GET", "/api/status", async (req, res) => {
  res.json({ status: "running", uptime: process.uptime() });
});

method · HTTPMethod · required

HTTP method: “GET”, “POST”, “PUT”, “PATCH”, “DELETE”, “OPTIONS”

path · string · required

URL path for the route

handler · RouteHandler · required

Request handler function

(req: FastMCPRequest, res: FastMCPResponse) => Promise<void> | void

options · RouteOptions

Route configuration options

Show properties

public · boolean · default: "false"

Bypass authentication for this route

start()

Start the MCP server with the specified transport.

// stdio transport (default)
await server.start();

// HTTP Stream transport
await server.start({
  transportType: "httpStream",
  port: 8000,
});

options · object

Transport configuration

Show properties

transportType · 'stdio' | 'httpStream' · default: "stdio"

Transport protocol to use

port · number · default: "8000"

Port number (httpStream only)

host · string · default: "0.0.0.0"

Host address (httpStream only)

server · SSEServer

Server instance with close() method (httpStream only)

embedded()

Create an embedded MCP server instance for programmatic use.

const embedded = await server.embedded({
  sessionAuth: { userId: "123", role: "admin" },
});

const result = await embedded.callTool("get_weather", {
  location: "San Francisco",
});

options · object

Show properties

sessionAuth · T

Authentication context for the session

session · FastMCPSession

Embedded session instance with direct API access

Context Object

The context object is passed to tool execute functions and provides access to session information and client capabilities.

execute: async (args, context) => {
  context.log.info("Tool called", { args });
  await context.reportProgress({ progress: 50, total: 100 });
  await context.streamContent({ type: "text", text: "Processing..." });
  return "Done";
}

session · T | undefined

Authentication session data (if authenticated)

sessionId · string | undefined

Session ID from Mcp-Session-Id header (HTTP transports only)

requestId · string | undefined

Request ID from current MCP request

client · object

Client information

Show properties

version · string

Client version string

log · object

Logging functions

Show methods

debug · (message: string, data?: SerializableValue) => void

Log debug message

info · (message: string, data?: SerializableValue) => void

Log info message

warn · (message: string, data?: SerializableValue) => void

Log warning message

error · (message: string, data?: SerializableValue) => void

Log error message

reportProgress · (progress: Progress) => Promise<void>

Report tool execution progress

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

streamContent · (content: Content | Content[]) => Promise<void>

Stream content to the client (for streaming tools)

await context.streamContent({
  type: "text",
  text: "Partial result...",
});