FastMCP TypeScript MCP Server Framework

Overview

FastMCP is a TypeScript framework for building Model Context Protocol (MCP) server applications. It provides a small, type-safe foundation for defining model endpoints, request/response shapes, middleware and lifecycle hooks so you can develop inference services and experimentation endpoints with predictable types and minimal boilerplate.

The framework focuses on developer ergonomics: first-class TypeScript types for request/response contracts, a lightweight runtime that favors predictable performance, and a set of builtin developer tools (local dev server, scaffolding, type generators) to accelerate iteration. FastMCP is useful whether you’re exposing a local research model for evaluation, building a production inference endpoint, or creating internal tools that rely on model responses and metadata.

Features

• Type-safe request and response typing with TypeScript-first APIs
• Small, focused runtime optimized for minimal overhead
• Simple handler/middleware model for request processing and validation
• Built-in dev server with fast restart / hot-reload experiences
• CLI scaffolding to bootstrap projects and generate type stubs
• Config-based server setup with environment-aware options
• Optional request validation and structured logging hooks
• Companion tooling for generating TypeScript types and minimal docs

Installation / Configuration

Install the package from npm and add basic scripts:

# install the library
npm install fastmcp

# recommended dev tools (optional)
npm install -D typescript ts-node nodemon

Example package.json scripts:

{
  "scripts": {
    "dev": "fastmcp dev",
    "start": "fastmcp start",
    "build": "fastmcp build"
  }
}

Basic TypeScript server example (src/server.ts):

import { createMCPServer, createHandler } from "fastmcp";

// Create a server instance
const server = createMCPServer({
  port: process.env.PORT ? Number(process.env.PORT) : 8080,
  logLevel: process.env.NODE_ENV === "production" ? "info" : "debug"
});

// Define a typed handler for an inference route
type PredictRequest = { prompt: string; maxTokens?: number };
type PredictResponse = { output: string; tokensUsed: number };

server.route(
  "predict",
  createHandler<PredictRequest, PredictResponse>(async (ctx, input) => {
    // input is typed; do model inference here
    const output = `Echo: ${input.prompt}`;
    return { output, tokensUsed: output.length };
  })
);

// Start the server
server.start().then(() => {
  console.log("FastMCP server listening on port", server.port);
});

Example fastmcp.config.ts (optional):

import type { FastMCPConfig } from "fastmcp";

const config: FastMCPConfig = {
  port: 8080,
  devServer: { enableHotReload: true },
  logging: { level: "debug", structured: true }
};

export default config;

Available Tools

FastMCP ships with CLI helpers and developer utilities to reduce friction during development:

• fastmcp init — create a project scaffold with recommended files and tsconfig
• fastmcp dev — run a local development server with faster restart / hot-reload
• fastmcp start — run the production server (build + start)
• fastmcp build — compile TypeScript artifacts and produce a production bundle
• fastmcp gen-types — generate TypeScript request/response stubs or OpenAPI-like metadata for documentation

Recommended development scripts (package.json):

{
  "scripts": {
    "mcp:init": "fastmcp init",
    "mcp:dev": "fastmcp dev",
    "mcp:build": "fastmcp build",
    "mcp:types": "fastmcp gen-types"
  }
}

Command reference (quick):

Use Cases

• Local research/experimentation server

  • Expose a research model with typed request/response shapes to collaborators.
  • Use built-in hot-reload to iterate quickly on prompt handling and output formatting.

• Production inference endpoints

  • Implement stable typed endpoints for downstream services to consume model outputs.
  • Add middleware to enforce rate limiting, authentication and structured logging.

• Multi-model orchestration

  • Create routes that dispatch to multiple model backends and return consolidated MCP responses.
  • Use typed contracts so orchestration logic and clients agree on payload formats.

• Tooling and integrations

  • Build auxiliary developer tools (playground UIs, CLI agents) that call your FastMCP server and rely on its generated type metadata.
  • Generate type stubs for SDKs or client libraries with the gen-types command.

• Testing and CI

  • Run deterministic handlers in CI for end-to-end tests against known inputs/outputs.
  • Use lightweight test harnesses to mock model internals while validating request/response contracts.

Getting Started Tips

• Keep request/response types small and explicit to take full advantage of TypeScript inference.
• Use the built-in dev server for iterative work; run production workloads with the build + start flow.
• Place reusable middleware (auth, validation, telemetry) into separate modules to keep handler files focused on business logic.
• Generate and check types into source control when shipping public endpoints or SDKs so consumers have a stable contract.

For the latest code, examples and issue tracking, visit the repository: https://github.com/punkpeye/fastmcp.