Type Definitions

Core type definitions for FastMCP

FastMCP exports TypeScript type definitions for tools, resources, prompts, and server configuration.

Tool Types

Tool

Tool definition with execute function.

interface Tool<T extends FastMCPSessionAuth, Params extends ToolParameters = ToolParameters> {
  name: string;
  description?: string;
  parameters?: Params;
  execute: (args: StandardSchemaV1.InferOutput<Params>, context: Context<T>) => Promise<string | Content | ContentResult | void>;
  canAccess?: (auth: T) => boolean;
  timeoutMs?: number;
  annotations?: ToolAnnotations;
  _meta?: {
    ui?: {
      resourceUri?: string;
    };
    [key: string]: unknown;
  };
}

ToolAnnotations

Tool behavior hints (MCP Specification 2025-03-26).

interface ToolAnnotations {
  title?: string;              // Human-readable title for UI display
  readOnlyHint?: boolean;      // Tool does not modify environment (default: false)
  destructiveHint?: boolean;   // Tool may perform destructive updates (default: true)
  idempotentHint?: boolean;    // Repeated calls have no additional effect (default: false)
  openWorldHint?: boolean;     // Tool may interact with external entities (default: true)
}

Resource Types

Resource

Static resource definition.

interface Resource<T extends FastMCPSessionAuth> {
  uri: string;
  name: string;
  description?: string;
  mimeType?: string;
  load: (auth?: T) => Promise<ResourceResult | ResourceResult[]>;
  canAccess?: (auth: T) => boolean;
  complete?: (name: string, value: string, auth?: T) => Promise<Completion>;
}

ResourceTemplate

Dynamic resource with URI template.

interface ResourceTemplate<
  T extends FastMCPSessionAuth,
  Arguments extends ResourceTemplateArgument<T>[] = ResourceTemplateArgument<T>[]
> {
  uriTemplate: string;
  name: string;
  description?: string;
  mimeType?: string;
  arguments: Arguments;
  load: (args: ResourceTemplateArgumentsToObject<Arguments>, auth?: T) => Promise<ResourceResult | ResourceResult[]>;
  complete?: (name: string, value: string, auth?: T) => Promise<Completion>;
}

ResourceResult

Resource content result.

type ResourceResult =
  | {
      text: string;
      mimeType?: string;
      uri?: string;
    }
  | {
      blob: string;  // Base64-encoded
      mimeType?: string;
      uri?: string;
    };

ResourceTemplateArgument

Resource template parameter definition.

interface ResourceTemplateArgument<T extends FastMCPSessionAuth = FastMCPSessionAuth> {
  name: string;
  description?: string;
  required?: boolean;
  complete?: ArgumentValueCompleter<T>;
}

Prompt Types

Prompt

Prompt template definition.

interface Prompt<
  T extends FastMCPSessionAuth = FastMCPSessionAuth,
  Arguments extends PromptArgument<T>[] = PromptArgument<T>[],
  Args = PromptArgumentsToObject<Arguments>
> {
  name: string;
  description?: string;
  arguments?: PromptArgument<T>[];
  load: (args: Args, auth?: T) => Promise<PromptResult>;
  complete?: (name: string, value: string, auth?: T) => Promise<Completion>;
}

PromptArgument

Prompt parameter definition.

interface PromptArgument<T extends FastMCPSessionAuth = FastMCPSessionAuth> {
  name: string;
  description?: string;
  required?: boolean;
  enum?: string[];
  complete?: ArgumentValueCompleter<T>;
}

PromptResult

Prompt load result.

type PromptResult = string | {
  messages: Array<{
    role: "user" | "assistant";
    content: {
      type: string;
      text: string;
    };
  }>;
};

Content Types

Content

Union of all content types.

type Content = 
  | TextContent
  | ImageContent
  | AudioContent
  | ResourceContent
  | ResourceLink;

TextContent

Plain text content.

interface TextContent {
  type: "text";
  text: string;
}

ImageContent

Image content with base64 data.

interface ImageContent {
  type: "image";
  data: string;      // Base64-encoded
  mimeType: string;  // e.g., "image/png"
}

AudioContent

Audio content with base64 data.

interface AudioContent {
  type: "audio";
  data: string;      // Base64-encoded
  mimeType: string;  // e.g., "audio/mpeg"
}

ResourceContent

Embedded resource reference.

interface ResourceContent {
  type: "resource";
  resource: {
    uri: string;
    text?: string;
    blob?: string;     // Base64-encoded
    mimeType?: string;
  };
}

ResourceLink

Reference to external resource.

interface ResourceLink {
  type: "resource_link";
  uri: string;
  name: string;
  title?: string;
  description?: string;
  mimeType?: string;
}

ContentResult

Tool execution result with content array.

interface ContentResult {
  content: Content[];
  isError?: boolean;
}

Server Types

FastMCPSessionAuth

Base type for session authentication.

type FastMCPSessionAuth = Record<string, unknown> | undefined;

Context

Execution context passed to tool/resource/prompt functions.

interface Context<T extends FastMCPSessionAuth> {
  session: T | undefined;
  sessionId?: string;
  requestId?: string;
  client: {
    version: string;
  };
  log: {
    debug: (message: string, data?: SerializableValue) => void;
    info: (message: string, data?: SerializableValue) => void;
    warn: (message: string, data?: SerializableValue) => void;
    error: (message: string, data?: SerializableValue) => void;
  };
  reportProgress: (progress: Progress) => Promise<void>;
  streamContent: (content: Content | Content[]) => Promise<void>;
}

Progress

Progress reporting data.

interface Progress {
  progress: number;  // Current progress value
  total?: number;    // Total value if known
}

Logger

Logging interface.

interface Logger {
  debug(...args: unknown[]): void;
  info(...args: unknown[]): void;
  log(...args: unknown[]): void;
  warn(...args: unknown[]): void;
  error(...args: unknown[]): void;
}

FastMCPRequest

Enhanced request object for custom routes.

interface FastMCPRequest<T extends FastMCPSessionAuth = FastMCPSessionAuth> {
  url: string;
  method: string;
  headers: http.IncomingHttpHeaders;
  params: Record<string, string>;
  query: Record<string, string | string[]>;
  body?: unknown;
  auth?: T;
  json(): Promise<unknown>;
  text(): Promise<string>;
}

FastMCPResponse

Enhanced response object for custom routes.

interface FastMCPResponse {
  status(code: number): FastMCPResponse;
  setHeader(name: string, value: string | number | string[]): FastMCPResponse;
  json(data: unknown): void;
  send(data: string | Buffer): void;
  end(data?: string | Buffer): void;
}

HTTPMethod

HTTP methods for custom routes.

type HTTPMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS";

RouteHandler

Route handler function type.

type RouteHandler<T extends FastMCPSessionAuth = FastMCPSessionAuth> = (
  req: FastMCPRequest<T>,
  res: FastMCPResponse,
) => void | Promise<void>;

RouteOptions

Options for custom routes.

interface RouteOptions {
  public?: boolean;  // Bypass authentication (default: false)
}

Completion Types

Completion

Completion result for argument values.

interface Completion {
  values: string[];        // Completion suggestions (max 100)
  total?: number;          // Total available completions
  hasMore?: boolean;       // More completions available
}

ArgumentValueCompleter

Completion function for argument values.

type ArgumentValueCompleter<T extends FastMCPSessionAuth = FastMCPSessionAuth> = (
  value: string,
  auth?: T
) => Promise<Completion>;

Error Types

UserError

Error meant to be surfaced to the user.

class UserError extends Error {
  extras?: Record<string, unknown>;
  
  constructor(message: string, extras?: Record<string, unknown>);
}

UnexpectedStateError

Internal error for unexpected states.

class UnexpectedStateError extends Error {
  extras?: Record<string, unknown>;
  
  constructor(message: string, extras?: Record<string, unknown>);
}

Utility Types

SerializableValue

JSON-serializable value.

type SerializableValue =
  | string
  | number
  | boolean
  | null
  | undefined
  | SerializableValue[]
  | { [key: string]: SerializableValue };

ToolParameters

Tool parameter schema (Standard Schema v1).

type ToolParameters = StandardSchemaV1;