A robust Fastify plugin that provides seamless integration with the Model Context Protocol (MCP) through streamable HTTP transport. This plugin enables your Fastify applications to act as MCP servers, allowing AI assistants and other clients to interact with your services using the standardized MCP protocol.
- Fastify MCP Server Plugin
The Model Context Protocol (MCP) is an open standard that enables AI assistants to securely connect to external data sources and tools. This plugin provides a streamable HTTP transport implementation for MCP servers built with Fastify, offering:
- High Performance: Built on top of Fastify's high-performance HTTP server
- Session Management: Automatic handling of MCP sessions with proper lifecycle management
- Event-Driven Architecture: Real-time session monitoring and error handling
- Type Safety: Full TypeScript support with comprehensive type definitions
- Production Ready: Robust error handling, graceful shutdown, and monitoring capabilities
- ✅ 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
- ✅ Session Storage: Support for in-memory and custom session stores (Redis included)
- ✅ Request Routing: Intelligent routing for different MCP request types
- ✅ Authentication: Optional Bearer token support for secure access
- ✅ Error Handling: Comprehensive error handling with proper MCP error responses
- ✅ 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
- ✅ Custom Session Stores: Implement your own session storage backend
- ✅ Custom Transport Options: Configure transport behavior with custom session ID generation and callbacks
- ✅ TypeScript Support: Full type safety and IntelliSense support
npm install fastify-mcp-server @modelcontextprotocol/sdkTo quickly see the plugin in action, you can run the demo server:
# Run with in-memory session storage
npm run dev
# Run with Redis session storage
npm run dev:redis
# Start MCP inspector to interact with the server
npm run inspectorThis will start a Fastify server with the MCP plugin enabled, allowing you to interact with it via the MCP inspector or any MCP-compatible client.
import Fastify from 'fastify';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import FastifyMcpServer, { getMcpDecorator } from 'fastify-mcp-server';
const app = Fastify({ logger: true });
// Create MCP server factory function
function createMcpServer () {
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!' }]
}));
return mcp;
}
// Register the plugin
await app.register(FastifyMcpServer, {
createMcpServer,
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 });type FastifyMcpServerOptions = {
createMcpServer: () => McpServer; // MCP Server factory function
endpoint?: string; // Custom endpoint path (default: '/mcp')
authorization?: {
// Authorization configuration
bearerMiddlewareOptions: {
verifier: OAuthTokenVerifier; // Custom verifier for Bearer tokens
requiredScopes?: string[]; // Optional scopes required for access
resourceMetadataUrl?: string; // Optional URL for resource metadata
};
oauth2?: {
// OAuth2 metadata configuration
authorizationServerOAuthMetadata: OAuthMetadata; // OAuth metadata for authorization server
protectedResourceOAuthMetadata: OAuthProtectedResourceMetadata; // OAuth metadata for protected resource
};
};
sessionStore?: SessionStore; // Optional custom session store implementation
transportOptions?: StreamableHTTPServerTransportOptions; // Optional transport configuration options
};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.getSessionManager();
// Create a new MCP server instance (useful for per-session customization)
const newMcpInstance = mcpServer.create();Monitor session lifecycle with event listeners:
const sessionManager = mcpServer.getSessionManager();
// 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);
});The plugin exposes three HTTP endpoints for MCP communication:
- Purpose: Create new sessions or send requests to existing sessions
- Headers:
content-type: application/jsonmcp-session-id: <session-id>(optional, for existing sessions)
- Body: MCP request payload
- Purpose: Retrieve streaming responses
- Headers:
mcp-session-id: <session-id>(required)
- Response: Server-sent events stream
- Purpose: Terminate sessions
- Headers:
mcp-session-id: <session-id>(required)
Sessions are managed through a dedicated SessionManager class that:
- Creates new transport instances with unique session IDs
- Tracks active sessions in memory
- Handles session lifecycle events
- Provides graceful cleanup on shutdown
- Emits events for monitoring and logging
sessionManager.on('transportError', (sessionId, error) => {
console.error(`Transport error: ${error.message}`);
});// Periodic health check
setInterval(() => {
const stats = mcpServer.getStats();
console.log(`Health Check - Active Sessions: ${stats.activeSessions}`);
// Alert if too many sessions
if (stats.activeSessions > 100) {
console.warn('High session count detected');
}
}, 30000);import closeWithGrace from 'close-with-grace';
closeWithGrace({ delay: 500 }, async ({ signal, err }) => {
if (err) {
app.log.error({ err }, 'server closing with error');
} else {
app.log.info(`${signal} received, server closing`);
}
// Fastify close will handle MCP session cleanup automatically
await app.close();
});The plugin provides a flexible session storage system that allows you to choose or implement your own storage backend. By default, sessions are stored in memory, but you can use Redis or create your own custom implementation.
import { InMemorySessionStore } from 'fastify-mcp-server';
await app.register(FastifyMcpServer, {
createMcpServer
// sessionStore option is optional - InMemorySessionStore is used by default
});For production deployments or distributed systems, use the Redis session store:
import { RedisSessionStore } from 'fastify-mcp-server';
const redisStore = new RedisSessionStore(redisClient); // Pass your Redis client instance
await app.register(FastifyMcpServer, {
createMcpServer,
sessionStore: redisStore
});You can implement your own session store by implementing the SessionStore interface:
import type { SessionStore, SessionData } from 'fastify-mcp-server';
class MyCustomSessionStore implements SessionStore {
async load (sessionId: string): Promise<SessionData | undefined> {
// Load session from your storage backend
}
async save (sessionData: SessionData): Promise<void> {
// Save session to your storage backend
}
async delete (sessionId: string): Promise<void> {
// Delete session from your storage backend
}
async getAllSessionIds (): Promise<string[]> {
// Return all session IDs
}
async deleteAll (): Promise<void> {
// Delete all sessions
}
}
// Use your custom store
await app.register(FastifyMcpServer, {
createMcpServer,
sessionStore: new MyCustomSessionStore()
});The session store is responsible for persisting session metadata (session ID and creation time). The plugin manages transports and MCP server connections in memory for performance, while session metadata can be stored in your chosen backend.
- Session Creation: When a client initializes, session metadata is saved to the store
- Session Retrieval: Session data is loaded from the store to validate existing sessions
- Session Cleanup: Sessions are removed from the store when destroyed
- Transport Management: Active transports are maintained in memory for fast access
| Feature | In-Memory | Redis | Custom |
|---|---|---|---|
| Persistence | Lost on restart | Persists across restarts | Depends on implementation |
| Scalability | Single instance | Multiple instances | Depends on implementation |
| Performance | Fastest | Slightly slower (network) | Depends on implementation |
| Use Case | Development, single instance | Production, distributed systems | Specialized requirements |
| Setup | No configuration needed | Requires Redis server | Custom implementation needed |
A docker-compose.yaml is provided for local development with Redis:
docker compose up -d
npm run dev:redisYou can secure your MCP endpoints using Bearer token authentication. The plugin provides a bearerMiddlewareOptions option, which enables validation of Bearer tokens in the Authorization header for all MCP requests.
Pass the authorization.bearerMiddlewareOptions option when registering the plugin. It accepts BearerAuthMiddlewareOptions from the SDK:
import type { BearerAuthMiddlewareOptions } from '@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js';await app.register(FastifyMcpServer, {
createMcpServer,
authorization: {
bearerMiddlewareOptions: {
verifier: myVerifier, // implements verifyAccessToken(token)
requiredScopes: ['mcp:read', 'mcp:write'], // optional
resourceMetadataUrl: 'https://example.com/.well-known/oauth-resource' // optional
}
}
});- verifier: An object with a
verifyAccessToken(token)method that returns the decoded token info or throws on failure. It must implements theOAuthTokenVerifierinterface from the SDK. - requiredScopes: (Optional) Array of scopes required for access.
- resourceMetadataUrl: (Optional) URL included in the
WWW-Authenticateheader for 401 responses.
The plugin uses a Fastify preHandler hook applied in the context of the MCP registered routes (see addBearerPreHandlerHook) to:
- Extract the Bearer token from the
Authorizationheader (Authorization: Bearer TOKEN). - Validate the token using your verifier.
- Check for required scopes and token expiration.
- Attach the decoded auth info to the request object (
req.raw.auth). - Respond with proper OAuth2 error codes and
WWW-Authenticateheaders on failure.
You can access the validated authentication information in your MCP tools via the authInfo parameter:
mcp.tool('example-auth-tool', 'Demo to display the validated access token in authInfo object', ({ authInfo }) => {
return {
content: [
{
type: 'text',
// Just a bad example, do not expose sensitive information in your LLM responses! :-)
text: `Authenticated with token: ${authInfo.token}, scopes: ${authInfo.scopes.join(', ')}, expires at: ${new Date(authInfo.expiresAt).toISOString()}`
}
]
};
});If authentication fails, the response will include a WWW-Authenticate header:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token", error_description="Token has expired"
Content-Type: application/json
{"error":"invalid_token","error_description":"Token has expired"}{
"inputs": [
{
"type": "promptString",
"id": "bearer_token",
"description": "Enter your MCP Bearer Token",
"password": true
}
],
"servers": {
"my-mcp-server": {
"url": "http://localhost:9080/mcp",
"headers": {
"Authorization": "Bearer ${input:bearer_token}"
}
}
}
}The plugin can automatically register standard OAuth 2.0 metadata endpoints under the .well-known path, which are useful for interoperability with OAuth clients and resource servers. You can test metadata discovery with the MCP inspector in the Authentication tab.
To enable these endpoints, provide the authorization.oauth2.authorizationServerOAuthMetadata and/or authorization.oauth2.protectedResourceOAuthMetadata options when registering the plugin:
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import FastifyMcpServer from 'fastify-mcp-server';
function createMcpServer () {
return new McpServer({
name: 'my-mcp-server',
version: '1.0.0'
});
}
const authorizationServerMetadata = {
issuer: 'https://your-domain.com',
authorization_endpoint: 'https://your-domain.com/oauth/authorize',
token_endpoint: 'https://your-domain.com/oauth/token'
// ...other OAuth metadata fields
};
const protectedResourceMetadata = {
resource: 'https://your-domain.com/.well-known/oauth-protected-resource'
// ...other resource metadata fields
};
await app.register(FastifyMcpServer, {
createMcpServer,
authorization: {
oauth2: {
authorizationServerOAuthMetadata: authorizationServerMetadata, // Registers /.well-known/oauth-authorization-server
protectedResourceOAuthMetadata: protectedResourceMetadata // Registers /.well-known/oauth-protected-resource
}
}
});GET /.well-known/oauth-authorization-server— Returns the OAuth authorization server metadata.GET /.well-known/oauth-protected-resource— Returns the OAuth protected resource metadata.
These endpoints are registered only if the corresponding metadata options are provided.
You can customize the behavior of the underlying StreamableHTTPServerTransport by providing transportOptions when registering the plugin. This allows you to configure advanced transport features such as custom session ID generation and transport lifecycle callbacks.
import type { StreamableHTTPServerTransportOptions } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
await app.register(FastifyMcpServer, {
createMcpServer,
transportOptions: {
// Custom session ID generator function
sessionIdGenerator: () => {
// Return your custom session ID
return `custom-${Date.now()}-${Math.random()}`;
},
// Callback invoked when session is initialized
onsessioninitialized: async (sessionId) => {
console.log(`Session ${sessionId} initialized`);
}
// Additional StreamableHTTPServerTransport options...
}
});- Custom Session IDs: Generate session IDs that match your existing ID format or include specific metadata
- Session Initialization Hooks: Perform custom logic when sessions are created (e.g., logging, metrics, notifications)
- Transport Configuration: Fine-tune transport behavior for specific deployment requirements
await app.register(FastifyMcpServer, {
createMcpServer,
transportOptions: {
sessionIdGenerator: () => {
return `mcp-prod-${randomUUID()}`;
}
}
});# Clone the repository
git clone https://github.com/flaviodelgrosso/fastify-mcp-server.git
cd fastify-mcp-server
# Install dependencies
npm install
# Run development server with hot reload
npm run devnpm run dev- Run development server with in-memory session storagenpm run dev:redis- Run development server with Redis session storagenpm run build- Build TypeScript to JavaScriptnpm test- Run test suite with 100% coveragenpm run test:lcov- Generate LCOV coverage reportnpm run inspector- Launch MCP inspector for testing
The project maintains 100% test coverage. Run tests with:
npm testContributions are welcome! Please read our contributing guidelines and ensure:
- Tests pass with 100% coverage
- Code follows the established style (enforced by Biome)
- Commits follow conventional commit format
- Changes are properly documented
ISC © Flavio Del Grosso
- Model Context Protocol - Official MCP specification and servers
- Fastify - Fast and low overhead web framework
- MCP SDK - TypeScript SDK for MCP