Mcp Toolkit

MCP Toolkit

> TypeScript middleware toolkit for MCP servers - authentication, caching, rate limiting, CORS, logging (beta).

Stop reimplementing auth, caching, rate limiting, CORS, and logging for every MCP server. MCP Toolkit provides drop-in packages that work with the TypeScript SDK.

Packages

| Package | Description | Status | |---------|-------------|--------| | [@mcp-toolkit/auth](packages/auth/) | API key and JWT authentication | Beta | | [@mcp-toolkit/cache](packages/cache/) | Response caching with TTL and LRU | Beta | | [@mcp-toolkit/rate-limit](packages/rate-limit/) | Rate limiting with token bucket | Beta | | [@mcp-toolkit/logger](packages/logger/) | Structured logging with JSON output and log levels | Beta | | [@mcp-toolkit/cors](packages/cors/) | Origin validation middleware | Beta |

Quick Start

Install

The @mcp-toolkit/* packages are not yet published to npm. Until then, clone and build from source:

git clone https://github.com/Sagargupta16/mcp-toolkit.git
cd mcp-toolkit
npm install
npm run build

Usage with TypeScript SDK

import { 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);

Package Details

Auth

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) });

Cache

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)}`,
});

Rate Limit

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 }),
});

Logger

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" }],
});

CORS

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 methods

Architecture

MCP 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)    |
+-------------------------+

Examples

See the [examples/](examples/) directory:

• [Basic server with auth](examples/basic-auth-server.ts)
• [Full middleware stack](examples/full-middleware-stack.ts)
• [Full production setup](examples/production-server.ts)

Contributing

Contributions welcome - new middleware, bug fixes, or docs improvements.

1. Fork this repo
2. Create a feature branch (git checkout -b feat/my-middleware)
3. Add your code with tests
4. Submit a PR

See [CONTRIBUTING.md](CONTRIBUTING.md) for full guidelines.

More AI Developer Tools

| 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 |

License

[MIT](LICENSE)

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Sagargupta16
• Source: Sagargupta16/mcp-toolkit
• License: MIT

Install and usage instructions live in the source repository linked above.