MCP Guardrails — ExtMcp Sidecar Architecture

MCP Guardrails — ExtMcp Sidecar Architecture An architecture diagram generated by Archify. MCP Agent · LLM client · Architecture component MCP Agent LLM client agentgateway · ExtMcp processor, failClosed · Architecture component · control plane agentgateway ExtMcp processor, failClosed control plane Upstream MCP server · tools + resources · Architecture component Upstream MCP server tools + resources ExtMcp servicer · gRPC h2c :9001 · mcp-guardrails sidecar (plaintext h2c :9001) ExtMcp servicer gRPC h2c :9001 GuardrailEngine · extract + scan windows · mcp-guardrails sidecar (plaintext h2c :9001) GuardrailEngine extract + scan windows RegexScanner · Unicode / PII / secrets · mcp-guardrails sidecar (plaintext h2c :9001) › first-stage scanners RegexScanner Unicode / PII / secrets PromptGuard-2 ONNX · injection classifier · mcp-guardrails sidecar (plaintext h2c :9001) › first-stage scanners PromptGuard-2 ONNX injection classifier Invariant Engine · toxic flow / loop / rate · mcp-guardrails sidecar (plaintext h2c :9001) › first-stage scanners Invariant Engine toxic flow / loop / rate DecisionAggregator · fail-closed verdict · mcp-guardrails sidecar (plaintext h2c :9001) DecisionAggregator fail-closed verdict Redaction · secret / PII masking · mcp-guardrails sidecar (plaintext h2c :9001) Redaction secret / PII masking AgentAlignment LLM · opt-in second stage · Architecture component AgentAlignment LLM opt-in second stage Audit & Telemetry · JSONL hash chain + OTLP · Architecture component Audit & Telemetry JSONL hash chain + OTLP tools/call (JSON-RPC) CheckRequest / CheckResponse check_request / check_response scan windows ScanResult mask allowed payloads pass | mutated | error forward after pass HUMAN_REVIEW only every decision mcp-guardrails sidecar (plaintext h2c :9001) first-stage scanners Legend Backend Database Security External

Double gate

  • • CheckRequest scans params as the TOOL role before forwarding
  • • CheckResponse scans tool output as the ASSISTANT role
  • • Deny surfaces to the agent as JSON-RPC error -32001

Fail-closed by default

  • • Scanner errors and timeouts deny under failClosed mode
  • • Unreachable sidecar makes agentgateway deny the exchange
  • • Regex-only fallback keeps guarding when ML deps are absent

Honest evidence

  • • One JSONL audit line per decision with a tamper-evident hash chain
  • • OTel spans and counters when an OTLP endpoint is configured
  • • Coverage gaps are bounded by knobs and flagged in the audit record