Reusable utilities and middleware for building production-ready MCP servers.
Stop reimplementing auth, caching, rate limiting, and logging for every MCP server. MCP Toolkit provides drop-in packages that work with the TypeScript SDK.
| Package | Description | Status |
|---|---|---|
@mcp-toolkit/auth |
API key and JWT authentication | Beta |
@mcp-toolkit/cache |
Response caching with TTL and LRU | Beta |
@mcp-toolkit/rate-limit |
Rate limiting with token bucket | Beta |
@mcp-toolkit/logger |
Structured logging with JSON output and log levels | Beta |
@mcp-toolkit/cors |
Origin validation middleware | Beta |
npm install @mcp-toolkit/auth @mcp-toolkit/cache @mcp-toolkit/rate-limit @mcp-toolkit/logger @mcp-toolkit/corsimport { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { withAuth } from "@mcp-toolkit/auth";
import { withCache } from "@mcp-toolkit/cache";
import { withRateLimit } from "@mcp-toolkit/rate-limit";
import { createLogger } from "@mcp-toolkit/logger";
const logger = createLogger({ level: "info", format: "json" });
const server = new McpServer({
name: "my-server",
version: "1.0.0",
});
// Add middleware
withAuth(server, {
type: "api-key",
keys: [process.env.MCP_API_KEY],
});
withRateLimit(server, {
strategy: "token-bucket",
maxTokens: 100,
refillRate: 10,
});
withCache(server, {
ttl: 300,
maxSize: 1000,
strategy: "lru",
});
// Define tools - middleware applies automatically
server.tool("get-data", "Fetch data with auth + cache + rate limiting", {
query: { type: "string", description: "Search query" },
}, async ({ query }) => {
logger.info("Fetching data", { query });
const result = await fetchData(query);
return { content: [{ type: "text", text: JSON.stringify(result) }] };
});
const transport = new StdioServerTransport();
await server.connect(transport);Multiple authentication strategies:
// API Key
withAuth(server, { type: "api-key", header: "X-API-Key", keys: ["key1", "key2"] });
// JWT
withAuth(server, { type: "jwt", secret: process.env.JWT_SECRET, algorithms: ["HS256"] });
// Custom
withAuth(server, { type: "custom", verify: async (token) => isValid(token) });Response caching with multiple strategies:
withCache(server, {
strategy: "lru", // lru | ttl
ttl: 300, // seconds
maxSize: 1000, // max entries
keyGenerator: (toolName, args) => `${toolName}:${JSON.stringify(args)}`,
});Protect your server from abuse:
withRateLimit(server, {
strategy: "token-bucket",
maxTokens: 100,
refillRate: 10, // per second
onLimited: (req) => logger.warn("Rate limited", { tool: req.toolName }),
});Structured logging built for MCP servers:
const logger = createLogger({
level: "info", // debug | info | warn | error
format: "json", // json | text
transports: ["stdout", { type: "file", path: "./mcp-server.log" }],
});Validate request origins when using HTTP or SSE transport:
import { withCors } from "@mcp-toolkit/cors";
withCors(server, {
allowedOrigins: ["https://myapp.com"],
allowedMethods: ["GET", "POST"]
});
// Optionally restrict HTTP methodsMCP Client (Claude, Cursor, etc.)
|
v
+-------------------------+
| MCP Transport |
| (stdio / Streamable HTTP)|
+-------------------------+
| @mcp-toolkit/cors | <-- Origin validation
+-------------------------+
| @mcp-toolkit/auth | <-- Authentication layer
+-------------------------+
| @mcp-toolkit/rate-limit | <-- Rate limiting layer
+-------------------------+
| @mcp-toolkit/cache | <-- Caching layer
+-------------------------+
| @mcp-toolkit/logger | <-- Logging (all layers)
+-------------------------+
| Your MCP Server |
| (tools, resources) |
+-------------------------+
See the examples/ directory:
Contributions welcome - new middleware, bug fixes, or docs improvements.
- Fork this repo
- Create a feature branch (
git checkout -b feat/my-middleware) - Add your code with tests
- Submit a PR
See CONTRIBUTING.md for full guidelines.
| Project | Description |
|---|---|
| claude-cost-optimizer | Save 30-60% on Claude Code costs - proven strategies and benchmarks |
| ai-git-hooks | AI-powered git hooks - auto-review diffs, generate commit messages, security scanning |
| claude-code-recipes | 50+ copy-paste recipes for Claude Code - commands, subagents, hooks, skills |
| agent-recipes | AI agent workflows for real-world dev tasks - code review, testing, security |