🛡️ mcp-shield

Inbound security proxy for MCP servers. Detects prompt injection, SQL/command injection, enforces input schemas, validates auth, and prevents abuse. Powered by vurb.ts — The Express.js for MCP Servers.

Why mcp-shield?

MCP tool calls arrive from the LLM as unvetted JSON-RPC. Without protection, your server is exposed to:

• Prompt Injection — LLMs coerced into overriding system instructions
• SQL Injection — malicious query strings targeting your database
• Command Injection — shell metacharacters in user-controlled inputs
• Path Traversal — relative path sequences escaping safe directories
• Abuse — rapid-fire calls, oversized payloads
• Prototype Pollution — __proto__ and constructor key injection

Client (LLM) ──stdin──▶ mcp-shield ──stdin──▶ MCP Server
              ◀──stdout──            ◀──stdout──
                          │
                   ┌──────┴──────┐
                   │ Shield Engine│ ← shield.yaml
                   │  7 Guards   │
                   │  Audit Log  │
                   └─────────────┘

Quick Start

npm install @mcp-server-shield/guard

# Generate default shield.yaml
npx @mcp-server-shield/guard --init

# Run as proxy
npx @mcp-server-shield/guard -- node dist/server.js

7 Security Guards

1. 💉 Injection Detection

Fast regex detection (~30 patterns) for prompt injection, SQL injection, command injection, and path traversal. Multilingual: EN, PT, ES, FR.

2. 📐 Schema Validation

Validates input structure: string length limits, object nesting depth, array bounds, and prototype pollution prevention (__proto__, constructor).

3. 🔑 Authentication

API key, bearer token, or custom validator support via environment variables.

4. 🚦 Abuse Prevention

Per-tool rate limiting (sliding window), burst detection (5s window), and request payload size enforcement.

5. 📋 Tool Allowlist/Denylist

Control which tools the LLM is allowed to call.

6. 🧹 Input Sanitization

HTML stripping, control character removal, Unicode normalization (NFC), and field length truncation. Unlike other guards, this modifies inputs before forwarding.

7. 🔍 Request Fingerprinting

SHA-256 hash-based duplicate detection and replay attack prevention within a configurable time window.

Policy Configuration

# shield.yaml
guards:
  injection:
    enabled: true
    action: block
    detect:
      promptInjection: true
      sqlInjection: true
      commandInjection: true
      pathTraversal: true

  schema:
    enabled: true
    action: block
    maxStringLength: 10000
    maxDepth: 10
    maxArrayItems: 100
    disallowedKeys: [__proto__, constructor, prototype]

  auth:
    enabled: false
    mode: api_key
    envVar: MCP_API_KEY

  abuse:
    enabled: true
    action: block
    maxCallsPerMinute: 60
    maxPayloadBytes: 102400
    burstLimit: 10

  allowlist:
    enabled: false
    allow: []
    deny: [system.exec, shell.run]

  sanitize:
    enabled: true
    action: sanitize
    stripHtml: true
    stripControlChars: true
    normalizeUnicode: true
    maxFieldLength: 5000

  fingerprint:
    enabled: false
    action: log
    detectDuplicates: true
    windowSeconds: 60

audit:
  enabled: true
  outputPath: ./shield-audit.jsonl

Ecosystem

Shield is the inbound complement to Firewall's outbound protection:

| Package | npm | Direction | Role | |---|---|---|---| | mcp-doctor | ✅ | — | 🔴 Diagnoses server problems | | @mcp-proxy/intercept | ✅ | Both | 🟡 Observes JSON-RPC traffic | | @mcp-firewall/enforce | ✅ | Outbound | 🟢 Protects data going to client | | @mcp-server-shield/guard | ✅ | Inbound | 🛡️ Protects server from attacks | | @mcp-server-utils/core | ✅ | — | 🧰 Developer utilities |

For native, zero-bypass security, use vurb.ts which includes InputFirewall (LLM-as-Judge) and EgressGuard as middleware.

Programmatic API

import { createShieldEngine, loadPolicy, checkInjection } from '@mcp-server-shield/guard';

// Use individual guards
const result = checkInjection(params, config);

// Full engine
const policy = loadPolicy('./shield.yaml');
const engine = createShieldEngine(policy);
const verdict = engine.evaluate(jsonRpcMessage);

Contributing

See CONTRIBUTING.md for guidelines.

Security

See SECURITY.md for vulnerability reporting.

License

Apache-2.0