trackmcp
Back to directory
DainoJung

mcp-shield

View on GitHub

Production-grade resilience middleware for MCP servers — timeout, retry, circuit breaker, structured logging.

1 stars TypeScriptOthers Updated Apr 10, 2026
ai-agentcircuit-breakerclaudemcpmiddlewaremodel-context-protocolproxyresilienceretrytimeouttypescript

Documentation

mcp-shield

The nginx of MCP — drop-in resilience middleware for any MCP server.

Timeout · Retry · Circuit Breaker · Structured Logging

Why

MCP servers have zero built-in resilience. A hung GitHub API blocks your agent for 600 seconds. A transient network blip crashes the entire chain. A dead server keeps getting hammered with requests.

mcp-shield is a transparent stdio proxy that sits between your agent and MCP server. One command, zero code changes.

code
Agent ←stdio→ mcp-shield ←stdio→ MCP Server

Install

bash
npm install -g @daino/mcp-shield

Or run directly with `npx`:

bash
npx @daino/mcp-shield wrap -- npx @modelcontextprotocol/server-github

Quick Start

bash
# Wrap any MCP server with sensible defaults (30s timeout, 2 retries)
mcp-shield wrap -- npx @modelcontextprotocol/server-github

# Custom timeout and retries
mcp-shield wrap --timeout 60s --retries 5 -- npx server-github

# Using a config file
mcp-shield wrap --config mcp-shield.yaml --server github

Claude Desktop

Add to your `claude_desktop_config.json`:

json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "@daino/mcp-shield", "wrap",
        "--timeout", "30s", "--retries", "3",
        "--",
        "npx", "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_TOKEN": "your-token-here"
      }
    }
  }
}

Done. Your GitHub MCP server now has timeout, retry, and circuit breaker protection.

Features

Timeout

Kill hung tool calls. No more 600-second waits.

yaml
timeout: 30s  # per-tool override available

Retry

Exponential backoff + jitter. Deterministic errors (invalid params, method not found) are never retried.

yaml
retries:
  max: 3
  backoff: exponential  # 1s → 2s → 4s
  jitter: true

Circuit Breaker

After repeated failures, fail fast instead of burning tokens on a dead server.

yaml
circuit_breaker:
  threshold: 5      # open after 5 consecutive failures
  reset_after: 60s  # try again after 60 seconds

States: Closed (normal) → Open (rejecting) → Half-Open (testing)

Structured Logging

Every tool call logged as structured JSON to stderr:

json
{
  "level": "info",
  "msg": "tool_call_end",
  "server": "github",
  "tool": "get_file_contents",
  "duration_ms": 245,
  "status": "success",
  "attempt": 1
}

Config File

For multi-server setups:

yaml
# mcp-shield.yaml
defaults:
  timeout: 30s
  retries:
    max: 3
    backoff: exponential
    jitter: true
  circuit_breaker:
    threshold: 5
    reset_after: 60s

servers:
  github:
    command: "npx @modelcontextprotocol/server-github"
    env:
      GITHUB_TOKEN: "${GITHUB_TOKEN}"
    tools:
      get_file_contents:
        timeout: 60s          # slow tool gets more time
      search_repositories:
        retries:
          max: 5              # flaky tool gets more retries

  filesystem:
    command: "npx @modelcontextprotocol/server-filesystem /home/user"
    timeout: 10s
    retries:
      max: 1

Programmatic Usage

typescript
import { shield } from '@daino/mcp-shield';

const proxy = shield({
  command: 'npx',
  args: ['@modelcontextprotocol/server-github'],
  timeout: 30_000,
  retries: { max: 3, backoff: 'exponential', jitter: true },
  circuitBreaker: { threshold: 5, resetAfter: 60_000 },
});

proxy.start();

Comparison

mcp-shieldNo protectionGeneral retry libs
MCP-native (JSON-RPC aware)✅—❌
Per-tool config✅—❌
Zero agent code changes✅—❌
Circuit breaker✅❌✅
Structured MCP logging✅❌❌
Drop-in Claude Desktop support✅—❌

Roadmap

  • [x] Timeout + Retry + Circuit Breaker + Logging
  • [x] Response Validation (schema check)
  • [x] Tool Filtering (expose only specific tools)
  • [x] Rate Limiting (per-tool call caps)
  • [x] Metrics Export (Prometheus-compatible)
  • [x] Multi-server Composition
  • [ ] Hot-reload config
  • [ ] Dashboard UI

Contributing

Contributions welcome! Please open an issue first to discuss what you'd like to change.

bash
git clone https://github.com/DainoJung/mcp-shield.git
cd mcp-shield
npm install
npm test

License

MIT

Frequently asked questions

What is mcp-shield?

mcp-shield is Production-grade resilience middleware for MCP servers — timeout, retry, circuit breaker, structured logging.

How do I install mcp-shield?

Open the GitHub repository and follow its README. Most MCP servers are added to your client's MCP config, then called by your agent.

Is mcp-shield open source?

Yes — it is hosted on GitHub at https://github.com/DainoJung/mcp-shield and has 1 stars.

Related MCP tools

KnockOutEZwigolo

The go-to web for your AI coding agent — local-first search, fetch, crawl & research over MCP. No API keys, no cloud, $0/query. Public beta.

4,906 TypeScript
mcpagentai+17
jamubcgemini-mcp-tool

MCP server that enables AI assistants to interact with Google Gemini CLI, leveraging Gemini's massive token window for large file analysis and codebase understanding

2,278 TypeScript
aiclaudecli+7
AI-QLtuui

A desktop MCP client designed as a tool unitary utility integration, accelerating AI adoption through the Model Context Protocol (MCP) and enabling cross-vendor LLM API orchestration.

1,153 TypeScript
agentagentic-aiai+17
SylphxAIpdf-reader-mcp

Give your AI agent eyes for PDFs — structured text, tables, OCR, visual evidence, and page-level citations via MCP. Native Rust, local-first.

915 TypeScript
ai-agentllm-toolmcp+16
AVIDS2memorix

Open-source cross-agent memory layer for coding agents via MCP. Compatible with Claude Code, Codex, Cursor, Windsurf, Gemini CLI, Antigravity, OpenClaw, Hermes Agent, Oh-my-Pi, Pi, Copilot, Kiro, OpenCode, and Trae.

721 TypeScript
ai-codingclaude-codecopilot+17
OpenOSINTOpenOSINT

AI-powered OSINT agent with interactive REPL, MCP server, and CLI. 19 tools. Works with Claude, GPT-4, or local models. For authorized security research only.

1,523 Python
ai-agentanthropicclaude+16

Run your own MCP server? See who uses it and what to fix.

Measure it with TrackMCP