Type Safety: Full TypeScript support with comprehensive type definitions

Production Ready: Robust error handling, graceful shutdown, and monitoring capabilities

Features

Core Functionality

✅ MCP Server Integration: Seamless integration with @modelcontextprotocol/sdk
✅ Streamable HTTP Transport: Full support for MCP's streamable HTTP protocol
✅ Session Management: Automatic session creation, tracking, and cleanup
✅ Request Routing: Intelligent routing for different MCP request types
✅ Error Handling: Comprehensive error handling with proper MCP error responses

Advanced Features

✅ Event System: Listen to session lifecycle events (creation, destruction, errors)
✅ Session Statistics: Real-time monitoring of active sessions
✅ Graceful Shutdown: Proper cleanup of all sessions during server shutdown
✅ Configurable Endpoints: Customizable MCP endpoint paths
✅ TypeScript Support: Full type safety and IntelliSense support

Installation

npm install fastify-mcp-streamable-http @modelcontextprotocol/sdk

Quick Start

import Fastify from 'fastify';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import FastifyMcpStreamableHttp, { getMcpDecorator } from 'fastify-mcp-streamable-http';

const app = Fastify({ logger: true });

// Create MCP server instance
const mcp = new McpServer({
  name: 'my-mcp-server',
  version: '1.0.0',
});

// Define MCP tools
mcp.tool('hello-world', () => ({
  content: [{ type: 'text', text: 'Hello from MCP!' }]
}));

// Register the plugin
await app.register(FastifyMcpStreamableHttp, {
  server: mcp.server,
  endpoint: '/mcp', // optional, defaults to '/mcp'
});

// Get MCP decorator for advanced features
const mcpServer = getMcpDecorator(app);

// Start the server
await app.listen({ host: '127.0.0.1', port: 3000 });

API Reference

Plugin Options

type FastifyMcpStreamableHttpOptions = {
  server: Server;      // MCP Server instance from @modelcontextprotocol/sdk
  endpoint?: string;   // Custom endpoint path (default: '/mcp')
}

MCP Decorator

The plugin decorates your Fastify instance with an MCP server that provides several useful methods:

const mcpServer = getMCPDecorator(app);

// Get session statistics
const stats = mcpServer.getStats();
console.log(`Active sessions: ${stats.activeSessions}`);

// Access session manager for event handling
const sessionManager = mcpServer.sessionManager;

// Graceful shutdown
await mcpServer.shutdown();

Session Events

Monitor session lifecycle with event listeners:

const sessionManager = mcpServer.sessionManager;

// Session created
sessionManager.on('sessionCreated', (sessionId: string) => {
  console.log(`New MCP session: ${sessionId}`);
});

// Session destroyed
sessionManager.on('sessionDestroyed', (sessionId: string) => {
  console.log(`MCP session ended: ${sessionId}`);
});

// Transport errors
sessionManager.on('transportError', (sessionId: string, error: Error) => {
  console.error(`Error in session ${sessionId}:`, error);
});

HTTP Protocol

The plugin exposes three HTTP endpoints for MCP communication:

POST `/mcp`

Purpose: Create new sessions or send requests to existing sessions
Headers:
- content-type: application/json
- mcp-session-id: <session-id> (optional, for existing sessions)

Categories

Current Category: fastify

fastify-mcp-streamable-http

ts-template-mcp