A collection of utility tools for the Model Context Protocol (MCP) that provide caching, retry logic, batch operations, and rate limiting capabilities to enhance any MCP-based workflow.
Features
- 🔄 Retry with Exponential Backoff - Automatically retry failed operations with configurable delays
- 💾 TTL-based Caching - Cache expensive operations with automatic expiration
- 🚀 Batch Operations - Process multiple operations in parallel with concurrency control
- 🚦 Rate Limiting - Prevent API abuse with sliding window rate limiting
- 🔍 Full TypeScript Support - Type-safe with comprehensive TypeScript definitions
Installation
npm install mcp-utility-tools
# or with yarn
yarn add mcp-utility-tools
# or with bun
bun add mcp-utility-tools
Quick Start
1. Add to Claude Desktop
Add the utility tools to your Claude Desktop configuration:
{
"mcpServers": {
"utility-tools": {
"command": "npx",
"args": ["mcp-utility-tools"]
}
}
}
2. Use with Claude
Once configured, Claude can use these tools to enhance any workflow:
# Check cache before expensive operation
cache_result = mcp_cache_get(key="api-response", namespace="github")
if not cache_result["found"]:
# Fetch data with retry
response = fetch_with_retry("https://api.github.com/user/repos")
# Cache for 5 minutes
mcp_cache_put(
key="api-response",
value=response,
ttl_seconds=300,
namespace="github"
)
🔄 retry_operation
Retry operations with exponential backoff and jitter.
{
"tool": "retry_operation",
"arguments": {
"operation_id": "unique-operation-id",
"operation_type": "http_request",
"operation_data": {
"url": "https://api.example.com/data",
"method": "GET"
},
"max_retries": 3,
"initial_delay_ms": 1000
}
}
Features:
- Tracks retry attempts across multiple calls
- Exponential backoff with configurable delays
- Optional jitter to prevent thundering herd
- Prevents duplicate retries for successful operations
💾 Cache Operations
cache_get
Retrieve values from cache with TTL support.
{
"tool": "cache_get",
"arguments": {
"key": "user-data-123",
"namespace": "users"
}
}
cache_put
Store values with automatic expiration.
{
"tool": "cache_put",
"arguments": {
"key": "user-data-123",
"value": { "name": "John", "role": "admin" },
"ttl_seconds": 300,
"namespace": "users"
}
}
Features:
- Namespace support to prevent key collisions
- Automatic cleanup of expired entries
- Configurable TTL (1 second to 24 hours)
- Memory-efficient storage
🚀 batch_operation
Process multiple operations with controlled concurrency.
{
"tool": "batch_operation",
"arguments": {
"operations": [
{ "id": "op1", "type": "fetch", "data": { "url": "/api/1" } },
{ "id": "op2", "type": "fetch", "data": { "url": "/api/2" } },
{ "id": "op3", "type": "fetch", "data": { "url": "/api/3" } }
],
"concurrency": 2,
"timeout_ms": 5000,
"continue_on_error": true,
"use_cache": true
}
}
Features:
- Configurable concurrency (1-20 operations)
- Per-operation timeout
- Continue or fail-fast on errors
- Optional result caching
- Maintains order of results
🚦 rate_limit_check
Implement sliding window rate limiting.
{
"tool": "rate_limit_check",
"arguments": {
"resource": "api.github.com",
"max_requests": 60,
"window_seconds": 60,
"increment": true
}
}
Features:
- Per-resource tracking
- Sliding window algorithm
- Automatic reset after time window
- Check without incrementing option
Integration Examples
With GitHub MCP Server
// Cache GitHub API responses
async function getRepositoryWithCache(owner: string, repo: string) {
const cacheKey = `github:${owner}/${repo}`;
// Check cache first
const cached = await mcp_cache_get({
key: cacheKey,
namespace: "github"
});
if (cached.found) {
return cached.value;
}
// Fetch with retry
const data = await retryableGitHubCall(owner, repo);
// Cache for 10 minutes
await mcp_cache_put({
key: cacheKey,
value: data,
ttl_seconds: 600,
namespace: "github"
});
return data;
}
With Slack MCP Server
// Rate-limited Slack notifications
async function sendSlackNotifications(messages: string[], channel: string) {
for (const message of messages) {
// Check rate limit
const canSend = await mcp_rate_limit_check({
resource: `slack:${channel}`,
max_requests: 10,
window_seconds: 60,
increment: true
});
if (!canSend.allowed) {
console.log(`Rate limited. Retry in ${canSend.reset_in_seconds}s`);
await sleep(canSend.reset_in_seconds * 1000);
}
await mcp_slack_post_message({
channel_id: channel,
text: message
});
}
}
Architecture
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ │ │ │ │ │
│ Claude/Client │────▶│ MCP Utility Tools│────▶│ Cache Storage │
│ │ │ │ │ (In-Memory) │
└─────────────────┘ └──────────────────┘ └─────────────────┘
│ │
│ │
▼ ▼
┌─────────────────┐ ┌──────────────────┐
│ Other MCP │ │ Retry/Rate │
│ Servers │ │ Limit Tracking │
└─────────────────┘ └──────────────────┘
Development
# Clone the repository
git clone https://github.com/haasonsaas/mcp-utility-tools.git
cd mcp-utility-tools
# Install dependencies
npm install
# Build the project
npm run build
# Run tests
npm test
# Run in development mode
npm run dev
Testing
Run the comprehensive test suite:
# Unit tests
npm test
# Integration tests with test harness
npm run test:integration
# Test with MCP Inspector
npx @modelcontextprotocol/inspector build/index-v2.js
Contributing
We welcome contributions! Please see our Contributing Guide for details.
Areas for Contribution
- 🔌 Storage Backends: Add Redis, SQLite support
- 🔧 New Tools: Circuit breakers, request deduplication
- 📊 Metrics: Add performance tracking and analytics
- 🌐 Examples: More integration examples with other MCP servers
License
MIT © Jonathan Haas
Acknowledgments
Built on top of the Model Context Protocol SDK by Anthropic.