fastify-mcp-server weekly downloads statistics

Fastify MCP Server Plugin

A Fastify plugin for building Model Context Protocol (MCP) servers aligned with the 2026-07-28 specification over Streamable HTTP or native stdio.

The plugin provides a thin Fastify-native integration around the MCP TypeScript SDK v2. The Streamable HTTP transport is request-stateless: MCP requests are processed independently, with no initialize handshake, no Mcp-Session-Id, no protocol session store, and no transport affinity between requests. The stdio transport delegates the connection to the SDK's native serveStdio entry.

Table of Contents

• Fastify MCP Server Plugin
  • Table of Contents
  • Overview
  • Features
    • Core Functionality
    • Advanced Features
  • Installation
  • Quick Demo
  • Quick Start
    • Streamable HTTP and stdio
  • API Reference
    • Plugin Options
    • MCP Decorator
  • Transports
    • Transport Selection
    • Lifecycle
    • Logging and stdout Safety
    • HTTP and stdio Differences
  • HTTP Protocol
    • Stateless Request Model
    • Protocol Discovery
    • Routing Headers
    • Streaming and Cancellation
  • Advanced Usage
    • Request-Scoped Context
    • Application State
    • Multi-Round-Trip Requests
    • Subscriptions and Notifications
    • Horizontal Scaling
  • Authentication: Bearer Token Support
    • Enabling Bearer Token Authentication
    • How It Works
    • Accessing Authentication Information
    • Example Error Response
    • Example using PAT in Visual Studio Code
  • Well-Known OAuth Metadata Routes
    • Registering Well-Known Routes
    • Endpoints
  • Protocol Compatibility
  • Development
    • Setup
    • Scripts
    • Testing
  • Contributing
  • License
  • Related Projects

Overview

The Model Context Protocol (MCP) is an open standard that enables AI applications to connect to tools, resources, and external systems through a common protocol.

fastify-mcp-server integrates MCP with Fastify while keeping the HTTP transport layer stateless by construction. Each HTTP request is processed from its own request envelope and can be handled by any healthy Fastify instance.

This means the plugin does not require:

• protocol sessions;
• Mcp-Session-Id headers;
• sticky load balancing;
• shared protocol state in Redis or another session store;
• an initialize / initialized handshake before normal MCP operations.

Application state is still fully supported, but it belongs to your application and should be represented by explicit domain identifiers, authenticated principals, databases, caches, or other application-owned dependencies.

Features

Core Functionality

• ✅ MCP 2026-07-28: Built for the modern MCP protocol revision
• ✅ Stateless HTTP: Every request is independently processable
• ✅ SDK v2 Integration: Built around @modelcontextprotocol/server
• ✅ Transport Selection: Streamable HTTP or native stdio through the SDK's serveStdio
• ✅ Fastify Integration: Works with normal Fastify hooks, plugins, logging, and lifecycle management
• ✅ Tools, Resources, and Prompts: Use the standard MCP SDK v2 server APIs
• ✅ Protocol Discovery: Supports the modern server/discover flow
• ✅ Modern Routing Headers: Supports MCP protocol, method, name, and parameter headers
• ✅ Authentication: Optional Bearer token validation on every request
• ✅ Type Safety: Full TypeScript support

Advanced Features

• ✅ Horizontal Scaling: No sticky sessions or shared MCP protocol store required
• ✅ Request-Scoped Metadata: Client capabilities, protocol metadata, auth, and tracing are evaluated per request
• ✅ Multi-Round-Trip Requests: Supports the 2026 input_required model
• ✅ Request-State Continuations: Explicit continuation state can be carried through requestState
• ✅ Streaming Responses: Uses modern per-request HTTP/SSE behavior when required
• ✅ Request Cancellation: Client disconnects cancel the corresponding request stream
• ✅ Configurable Endpoint: Mount MCP on a custom Fastify route
• ✅ OAuth Metadata: Optional Protected Resource and Authorization Server metadata endpoints

Installation

npm install fastify-mcp-server @modelcontextprotocol/server

The MCP TypeScript SDK v2 is the supported SDK line for this major version.…