Fastify MCP Server
π High-performance MCP (Model Context Protocol) server built with Fastify, TypeScript, and functional programming. Production-ready with authentication, metrics, and auto-discovery capabilities for AI agents and LLM applications.
Installation
npx fastify-mcp-serverAsk AI about Fastify MCP Server
Powered by Claude Β· Grounded in docs
I know everything about Fastify MCP Server. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
π Fastify MCP Server
High-performance MCP (Model Context Protocol) server built with Fastify, TypeScript, and functional programming principles. Production-ready with authentication, metrics, and auto-discovery capabilities.
π― About This Project
Fastify MCP Server is a production-grade implementation of the Model Context Protocol (MCP) specification, designed for AI agents and LLM applications. Built with modern TypeScript and functional programming paradigms, it provides a robust foundation for AI-powered applications requiring secure, scalable MCP server capabilities.
π Key Benefits
- β‘ Lightning Fast: Built on Fastify - the fastest Node.js web framework
- π Enterprise Security: Bearer token authentication and secure session management
- π Production Ready: Kubernetes health checks, metrics endpoints, and monitoring
- π§© Auto-Discovery: Automatic registration of tools, resources, and prompts
- π‘οΈ Type Safe: Full TypeScript support with Zod validation
- π― Functional: Purely functional programming approach for reliability
π Table of Contents
- π― About This Project
- β¨ Features
- π Use Cases
- π Why Choose This Server?
- ποΈ Architecture
- π Security
- π MCP Capabilities
- π Quick Start
- π MCP Client Integration
- π οΈ Development
- π¦ Tech Stack
- π€ Contributing
- π Resources
- π License
β¨ Features
- ποΈ Fastify-powered - Lightning-fast HTTP server with TypeScript support
- π§ MCP Protocol - Full Model Context Protocol implementation with tools, resources, and prompts
- π‘οΈ Secure Authentication - Bearer token middleware for MCP server connections
- π Production Ready - Kubernetes health endpoints and metrics routes
- π§© Modular Architecture - Auto-registration system for MCP capabilities
- π Type Safety - Zod validation with
@modelcontextprotocol/sdk - π― Functional Programming - Strictly functional paradigms throughout
π Use Cases
Perfect for building:
- AI Agent Platforms - Secure MCP servers for AI applications
- LLM Integration - Connect language models with external tools and data
- Enterprise AI - Production-ready MCP infrastructure for organizations
- Developer Tools - Custom MCP servers for development workflows
- API Gateways - High-performance API endpoints with MCP capabilities
- Microservices - Scalable MCP services in distributed architectures
π Why Choose This Server?
| Feature | Fastify MCP Server | Other Solutions |
|---|---|---|
| Performance | β‘ Fastify-based | β Express/Slower |
| Type Safety | β Full TypeScript | β JavaScript only |
| Security | π Bearer tokens | β Basic auth |
| Production | π Metrics & Health | β Development only |
| Architecture | π§© Auto-discovery | β Manual setup |
| Standards | β MCP 1.0 compliant | β Custom protocols |
β‘ Production Readiness
- β Kubernetes - Health checks and readiness probes
- β Monitoring - Built-in metrics and logging
- β Security - Bearer token authentication
- β Scalability - Horizontal scaling support
- β Reliability - Per-session MCP isolation, automatic stale session cleanup
ποΈ Architecture
Core Components
- Fastify Server - High-performance HTTP server with custom MCP plugin
- MCP Transport - Injected as a Fastify plugin for seamless integration
- Session Management - Handles MCP client connections and state
- Auto-registration - Automatically discovers and registers MCP capabilities
Endpoints
GET /health- Kubernetes liveness probe (no auth)GET /metrics- Application metrics (no auth)POST /mcp- MCP StreamableHTTP transport (bearer auth required)
Session Management
The MCP SDK requires one Server/Protocol instance per transport, so the session manager instantiates a fresh McpServer per connection (see src/mcp/sessions.ts). Sessions are tracked by ID and reaped after 30 minutes of inactivity.
- Per-session isolation - Each MCP client gets its own server instance
- Activity-based timeouts - Sessions stay alive while actively used
- Automatic cleanup - Stale sessions (30 min idle) removed every 5 min
- Graceful shutdown - All sessions closed on server stop
Session lifecycle: create (new UUID) β reuse on subsequent requests with same mcp-session-id header β cleanup when stale.
π Security
The server includes authentication middleware (src/middleware/auth.ts) that verifies MCP connections using a bearer token. The token is configured via the MCP_SERVER_TOKEN environment variable, ensuring secure access to the MCP server capabilities.
π MCP Capabilities
The server automatically registers tools, resources, and prompts from their respective folders when you update the index.ts file in each directory:
π οΈ Tools
Active, callable functions that perform operations and return structured outputs. Perfect for:
- State changes and side effects
- External API calls and computations
- Agentic workflows where the LLM chooses which tool to invoke
π Resources
Read-only, structured data surfaces exposed via URI. Ideal for:
- Contextual knowledge and documentation
- Shared context across sessions
- Binary content and large artifacts
π Prompts
Parameterized instruction templates for reusable AI workflows. Great for:
- Standardized tasks (summarization, translation, etc.)
- Separating prompt engineering from application logic
- Multi-step orchestrated workflows
π‘ Each capability type has detailed documentation in its respective
README.mdfile.
π Quick Start
Prerequisites
- Node.js >= 22 (recommended: 24.x LTS, see
.nvmrc) - pnpm (the project ships a
pnpm-lock.yaml) - Git
π‘ With nvm:
nvm usewill pick up the version pinned in.nvmrcautomatically.
Installation
git clone https://github.com/your-username/fastify-mcp-server.git
cd fastify-mcp-server
pnpm install
pnpm build
Development
pnpm dev # HTTP server with hot reload (tsx watch)
pnpm mcp # Run as stdio MCP server (for Claude Desktop direct integration)
pnpm start # Production server (after pnpm build)
Configuration
cp .env.example .env
MCP_SERVER_PORT=9080
MCP_SERVER_HOST=localhost
MCP_SERVER_TOKEN=super-secret-token # change for non-local use
LOG_LEVEL=debug
π MCP Client Integration
Two integration paths β stdio (simplest, no server needed) or HTTP (test the production transport, auth, sessions).
Claude Desktop β stdio (recommended for local dev)
Build first: pnpm build. Then add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"fastify-mcp-local": {
"command": "node",
"args": ["/absolute/path/to/fastify-mcp-server/dist/mcp-stdio.js"]
}
}
}
βΉοΈ The logger writes to stderr by default in stdio mode, so no extra config is needed.
Claude Desktop β HTTP via mcp-remote bridge
Claude Desktop only spawns stdio processes locally. To consume the HTTP transport, bridge it with mcp-remote:
{
"mcpServers": {
"fastify-mcp-local": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"http://localhost:9080/mcp",
"--header",
"Authorization: Bearer super-secret-token"
]
}
}
}
Run pnpm dev first; then quit + reopen Claude Desktop. Logs at ~/Library/Logs/Claude/mcp-server-*.log.
β οΈ
npxresolvesnodefrom PATH. If you have multiple Node versions installed via nvm, ensure your default (nvm alias default) is Node β₯ 18, ormcp-remotewill crash onundici.
cURL / Postman
curl -X POST http://localhost:9080/mcp \
-H "Authorization: Bearer super-secret-token" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'
In Postman: POST http://localhost:9080/mcp, Auth β Bearer Token = your MCP_SERVER_TOKEN.
π οΈ Development
Adding New Capabilities
- Tools: Add your tool in
src/tools/and export it fromsrc/tools/index.ts - Resources: Add your resource in
src/resources/and export it fromsrc/resources/index.ts - Prompts: Add your prompt in
src/prompts/and export it fromsrc/prompts/index.ts
The server will automatically register them on restart.
Scripts
pnpm dev # HTTP server with hot reload (tsx watch)
pnpm build # Compile TypeScript β dist/
pnpm start # Run compiled server (node dist/index.js)
pnpm mcp # Run as stdio MCP server (after build)
pnpm check # Type check without emit
pnpm lint # ESLint --fix
pnpm lint:check # ESLint, no fixes
pnpm format # Prettier --write
pnpm format:check # Prettier --check
pnpm clean # Remove dist/
π¦ Tech Stack
Core Technologies
- Fastify - Fast and low overhead web framework
- @modelcontextprotocol/sdk - Official MCP TypeScript SDK
- Zod - TypeScript-first schema validation
- Pino - Super fast, all natural JSON logger
- TypeScript - Type safety and modern JavaScript features
Development Tools
- ESLint - Code linting
- Prettier - Code formatting
- tsx - TypeScript execution and watch mode
- pnpm - Package manager
Keywords & Tags
mcp-server fastify typescript ai-agents llm-integration model-context-protocol nodejs api-server production-ready authentication metrics kubernetes functional-programming type-safety enterprise microservices ai-platform developer-tools
π€ Contributing
We welcome contributions! Please see our Contributing Guidelines for details.
Development Workflow
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Code Quality
- β TypeScript - Full type safety
- β ESLint - Code quality and consistency
- β Prettier - Code formatting
- β Tests - Comprehensive test coverage
- β Documentation - Clear and up-to-date docs
π Resources
Documentation
- MCP Specification - Official MCP documentation
- Fastify Documentation - Fastify framework guide
- TypeScript Handbook - TypeScript reference
Community
- GitHub Discussions - Community discussions
- Issues - Bug reports and feature requests
- Discord - Real-time community chat
Related Projects
- Model Context Protocol - Official MCP organization
- Fastify Ecosystem - Fastify plugins and tools
- TypeScript MCP SDK - Official TypeScript SDK
π License
Copyright Β© 2025β2026 Mustafa ONAL
This project is licensed under the MIT License - see the LICENSE file for details.
Built with β€οΈ using functional programming principles and modern TypeScript
π Star This Repository
If you find this project helpful, please give it a star β on GitHub!
