mcp-shield

mcp-shield

El nginx de MCP: middleware de resiliencia plug-and-play para cualquier servidor MCP.

Timeout · Reintentos · Interruptor de circuito · Registro estructurado

---

Por qué

Los servidores MCP tienen cero resiliencia integrada. Una API de GitHub colgada bloquea a tu agente durante 600 segundos. Una interrupción transitoria de red derriba toda la cadena. Un servidor caído sigue recibiendo solicitudes sin parar.

mcp-shield es un proxy stdio transparente que se sitúa entre tu agente y el servidor MCP. Un solo comando, cero cambios de código.

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

Instalación

npm install -g @daino/mcp-shield

O ejecútalo directamente con npx:

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

Inicio rápido

# 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

Añádelo a tu claude_desktop_config.json:

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

Listo. Tu servidor MCP de GitHub ahora tiene protección con timeout, reintentos e interruptor de circuito.

Características

Timeout

Elimina llamadas de herramientas colgadas. No más esperas de 600 segundos.

timeout: 30s  # per-tool override available

Reintentos

Retroceso exponencial + jitter. Los errores deterministas (parámetros inválidos, método no encontrado) nunca se reintentan.

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

Interruptor de circuito

Tras fallos repetidos, falla rápido en lugar de quemar tokens en un servidor caído.

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

Estados: Cerrado (normal) → Abierto (rechazando) → Semiabierto (probando)

Registro estructurado

Cada llamada de herramienta se registra como JSON estructurado en stderr:

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

Archivo de configuración

Para configuraciones con múltiples servidores:

# 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

Uso programático

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

Comparación

	mcp-shield	Sin protección	Librerías generales de reintentos
Nativo de MCP (consciente de JSON-RPC)	✅	—	❌
Configuración por herramienta	✅	—	❌
Cero cambios de código en el agente	✅	—	❌
Interruptor de circuito	✅	❌	✅
Registro MCP estructurado	✅	❌	❌
Soporte plug-and-play para Claude Desktop	✅	—	❌

Hoja de ruta

• Timeout + Reintentos + Interruptor de circuito + Registro
• Validación de respuestas (verificación de esquema)
• Filtrado de herramientas (exponer solo herramientas específicas)
• Limitación de velocidad (límites de llamadas por herramienta)
• Exportación de métricas (compatible con Prometheus)
• Composición de múltiples servidores
• Configuración con recarga en caliente
• Interfaz de panel

Contribuciones

¡Las contribuciones son bienvenidas! Por favor, abre un issue primero para discutir lo que te gustaría cambiar.

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

Licencia

MIT