https://github.com/sagargupta16/mcp-toolkit

Production-ready middleware for MCP servers - authentication, caching, rate limiting, logging, and TypeScript-first design
https://github.com/sagargupta16/mcp-toolkit

ai-tools authentication caching logging mcp middleware model-context-protocol rate-limiting typescript

Last synced: about 2 months ago
JSON representation

Production-ready middleware for MCP servers - authentication, caching, rate limiting, logging, and TypeScript-first design

Host: GitHub
URL: https://github.com/sagargupta16/mcp-toolkit
Owner: Sagargupta16
License: mit
Created: 2026-03-04T01:11:07.000Z (4 months ago)
Default Branch: main
Last Pushed: 2026-04-16T10:19:54.000Z (2 months ago)
Last Synced: 2026-04-16T12:31:14.787Z (2 months ago)
Topics: ai-tools, authentication, caching, logging, mcp, middleware, model-context-protocol, rate-limiting, typescript
Language: TypeScript
Size: 96.7 KB
Stars: 4
Watchers: 0
Forks: 1
Open Issues: 12
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md

Awesome Lists containing this project

README

          # MCP Toolkit

![GitHub stars](https://img.shields.io/github/stars/Sagargupta16/mcp-toolkit?style=flat-square)

![GitHub forks](https://img.shields.io/github/forks/Sagargupta16/mcp-toolkit?style=flat-square)

![License](https://img.shields.io/github/license/Sagargupta16/mcp-toolkit?style=flat-square)

![Last Commit](https://img.shields.io/github/last-commit/Sagargupta16/mcp-toolkit?style=flat-square)

![npm](https://img.shields.io/badge/npm-mcp--toolkit-red?style=flat-square&logo=npm)

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

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

```bash

npm install @mcp-toolkit/auth @mcp-toolkit/cache @mcp-toolkit/rate-limit @mcp-toolkit/logger @mcp-toolkit/cors

```

### Usage with TypeScript SDK

```typescript

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:

```typescript

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

```typescript

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:

```typescript

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:

```typescript

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:

```typescript

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 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](https://github.com/Sagargupta16/claude-cost-optimizer) | Save 30-60% on Claude Code costs - proven strategies and benchmarks |

| [ai-git-hooks](https://github.com/Sagargupta16/ai-git-hooks) | AI-powered git hooks - auto-review diffs, generate commit messages, security scanning |

| [claude-code-recipes](https://github.com/Sagargupta16/claude-code-recipes) | 50+ copy-paste recipes for Claude Code - commands, subagents, hooks, skills |

| [agent-recipes](https://github.com/Sagargupta16/agent-recipes) | AI agent workflows for real-world dev tasks - code review, testing, security |

## License

[MIT](LICENSE)

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/sagargupta16/mcp-toolkit

Awesome Lists containing this project

README