Labsco
DainoJung logo

mcp-shield

★ 1

from DainoJung

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

🔥🔥🔥✓ VerifiedFreeQuick setup
#git

downloads

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.

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

Features

Timeout

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

timeout: 30s  # per-tool override available

Retry

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

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.

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:

{
  "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:

# 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

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

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