Enterprise·
advanced
·12 min read·Sep 24, 2026·Updated Nov 12, 2026
·Lead AI Systems Architect·Verification Charter

Hierarchical Zero-Trust MCP Gateways Guide

Deploy hierarchical zero-trust MCP gateways with Envoy and mTLS. Enforce RBAC, DLP redaction, and schema filters for Claude and Codex. Verified working.

MCPEnvoyZero-TrustGatewaySecurityProxyClaudeCodex
Interactive Tool
1-Click Export

Generate & Validate Multi-Client MCP Config

One-click export with environment variables & path locators for Claude Desktop, Cursor, Windsurf, and OpenAI Codex CLI.

Open in Generator

Hierarchical Zero-Trust MCP Gateways Guide

Direct, unmediated connections between autonomous AI agents and enterprise production infrastructure introduce severe operational vulnerabilities. When developer clients like Claude Desktop, Cursor, or OpenAI Codex CLI connect directly to raw database drivers or internal cloud APIs through Model Context Protocol (MCP) servers, perimeter security collapses. A misconfigured model prompt, prompt injection payload, or runaway multi-agent loop can execute destructive database operations, leak sensitive customer records across LLM context windows, or flood internal microservices with unthrottled requests.

Hierarchical Zero-Trust MCP Gateways solve this architectural flaw. Rather than permitting desktop workstations or background agents to establish point-to-point connections with backend servers, the gateway functions as an intelligent Layer 7 reverse proxy. The gateway intercepts every JSON-RPC 2.0 message across standard input/output (stdio) bridges and Server-Sent Events (SSE) network streams, authenticates agent cryptographic identities, validates tool schemas against strict Role-Based Access Control (RBAC) policies, sanitizes input parameters, and strips personally identifiable information (PII) before returning payloads to client context windows.


Problem Statement and Architecture

In a standard MCP deployment, client hosts spawn server processes locally using stdio pipes or initiate remote HTTP/SSE streaming connections. In both modes, the client possesses direct access to every tool, resource, and prompt exposed by the server. In enterprise settings with strict compliance mandates (such as SOC 2 Type II, HIPAA, and ISO 27001), granting raw tool access directly to generative models violates the core principle of least privilege.

The Hierarchical Zero-Trust MCP Gateway introduces a centralized, multi-tier inspection pipeline between the client ecosystem and upstream services:

code
+-----------------------------------------------------------------------+
|                           AI AGENT CLIENTS                            |
|        Claude Desktop  *  Cursor IDE  *  OpenAI Codex CLI             |
+-----------------------------------+-+---------------------------------+
                                    |
                                    | mTLS / Bearer JWT (SPIFFE ID)
                                    v
+-----------------------------------------------------------------------+
|                     ZERO-TRUST MCP GATEWAY (ENVOY)                    |
|                                                                       |
|  1. Identity and OIDC Attestation (Verify client x509 cert and role)  |
|  2. Tool Schema Filtering (Strip unauthorized tools from tools/list)  |
|  3. Parameter Sanitization (Block destructive SQL, regex, and paths)  |
|  4. Token-Bucket Rate Limiting (Throttle calls per Agent session ID)  |
|  5. Outbound DLP Engine (Redact API keys, tokens, and PII on egress)  |
+-----------------------------------+-+---------------------------------+
                                    |
                                    | Internal Verified JSON-RPC 2.0
        +---------------------------+---------------------------+
        |                                                       |
        v                                                       v
+-------------------------------+       +-------------------------------+
|     Upstream Database MCP     |       |       Upstream Cloud MCP      |
|    PostgreSQL Staging Pod     |       |    AWS Infrastructure SRE     |
+-------------------------------+       +-------------------------------+

The gateway establishes mutual TLS (mTLS) with every client, enforcing cryptographic identity verification via SPIFFE verifiable identity documents (SVIDs). When a client sends a tools/list discovery request, the gateway dynamically rewrites the response payload, presenting only tools authorized for that agent's specific role. If an unauthorized client attempts to dispatch a tools/call for an administrative operation, the gateway intercepts the frame at the proxy boundary, logs an immutable audit event, and returns a standard JSON-RPC error frame without ever forwarding the request to the upstream infrastructure.


Prerequisites and Environment Matrix

Before deploying a Hierarchical Zero-Trust MCP Gateway in staging or production environments, verify that your host systems and container runtimes satisfy the minimum version matrix:

ComponentMinimum VersionRecommended VersionPurpose
Node.js Runtimev20.18.0 LTSv22.12.0 LTSGateway proxy middleware execution
Envoy Proxyv1.30.0v1.32.2Layer 7 mTLS termination and traffic routing
Docker Engine24.0.027.3.1Isolated container sandboxing for upstream servers
OpenSSL CLI3.0.23.3.1Generating x509 leaf and CA certificates for mTLS
TypeScript5.3.35.6.3Compiling custom policy interceptors

In addition to core runtimes, ensure you have provisioned:

  • ▸A private Certificate Authority (CA) or HashiCorp Vault instance for issuing client certificates.
  • ▸A running Redis 7.2.x cluster to maintain distributed token-bucket rate limits across gateway replicas.
  • ▸Read-only database credentials configured for upstream data stores.

Multi-Host Configuration Snippets

Connecting agent hosts to the Zero-Trust Gateway requires pointing clients to the gateway's secure entrypoint rather than raw backend servers. Below are tested configurations for Claude Desktop, Cursor, and OpenAI Codex CLI.

Claude Desktop Configuration

On macOS (~/Library/Application Support/Claude/claude_desktop_config.json) or Windows (%APPDATA%\Claude\claude_desktop_config.json), configure Claude Desktop to connect via the gateway's authenticated SSE transport:

json
{
  "mcpServers": {
    "enterprise-gateway": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "https://mcp-gateway.internal.example.com/sse"
      ],
      "env": {
        "GATEWAY_CLIENT_CERT": "/etc/ssl/certs/agent-claude.crt",
        "GATEWAY_CLIENT_KEY": "/etc/ssl/private/agent-claude.key",
        "GATEWAY_AUTH_TOKEN": "<YOUR_ENTERPRISE_JWT_TOKEN>"
      }
    }
  }
}

Cursor IDE Configuration

In Cursor's root settings file (.cursor/mcp.json or Global Features settings), define the gateway endpoint using secure headers:

json
{
  "mcpServers": {
    "enterprise-gateway": {
      "url": "https://mcp-gateway.internal.example.com/sse",
      "headers": {
        "Authorization": "Bearer <YOUR_ENTERPRISE_JWT_TOKEN>",
        "X-Agent-Role": "developer-read-only",
        "X-Client-Version": "cursor-0.44.0"
      }
    }
  }
}

OpenAI Codex CLI Configuration

For command-line agent loops running OpenAI Codex CLI, declare the gateway in your local or global configuration (~/.codex/config.toml):

toml
# ~/.codex/config.toml
[mcp_servers.enterprise_gateway]
url = "https://mcp-gateway.internal.example.com/sse"
transport = "sse"
bearer_token = "<YOUR_ENTERPRISE_JWT_TOKEN>"
timeout_seconds = 30

[mcp_servers.enterprise_gateway.headers]
X-Agent-Role = "developer-read-only"
X-Environment = "staging"

Step-by-Step Tool Discovery and Invocation

When a client initiates contact with the gateway, the proxy performs capability negotiation and schema filtering before any tool execution occurs.

1. Protocol Handshake and Initialization

The client dispatches the standard JSON-RPC 2.0 initialize frame over the authenticated transport:

json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "roots": { "listChanged": true },
      "sampling": {}
    },
    "clientInfo": {
      "name": "Claude-Desktop",
      "version": "1.0.4"
    }
  }
}

The gateway validates the client's mTLS certificate, maps the identity to an assigned RBAC role, and responds with the gateway server capabilities:

json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": { "listChanged": true },
      "resources": {},
      "logging": {}
    },
    "serverInfo": {
      "name": "Envoy-ZeroTrust-MCP-Gateway",
      "version": "2026.2.0"
    }
  }
}

2. Dynamically Filtered Tool Discovery

Next, the client requests the list of accessible tools:

json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

If the upstream PostgreSQL server exposes both query_read_only and execute_ddl, the gateway intercepts the upstream response and removes execute_ddl because the agent's role is developer-read-only:

json
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "query_read_only",
        "description": "Execute parameterized SELECT queries against staging data.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "sql": { "type": "string", "description": "SQL SELECT query string" }
          },
          "required": ["sql"]
        }
      }
    ]
  }
}

3. Tool Execution with Real-Time DLP Redaction

To trigger the tool, prompt the model host: "Query the customer accounts table for active enterprise subscribers in region US-EAST."

The client transmits the tools/call request:

json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "query_read_only",
    "arguments": {
      "sql": "SELECT id, company_name, billing_contact_email, api_key_hash FROM accounts WHERE region = 'US-EAST' LIMIT 2;"
    }
  }
}

The gateway passes the query to the upstream database, receives the raw rows, redacts private tokens and contact info via regex masks, and returns the sanitized result:

json
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[{\"id\": 1042, \"company_name\": \"Acme Corp\", \"billing_contact_email\": \"[REDACTED_EMAIL]\", \"api_key_hash\": \"[REDACTED_SECRET]\"}, {\"id\": 1043, \"company_name\": \"Globex\", \"billing_contact_email\": \"[REDACTED_EMAIL]\", \"api_key_hash\": \"[REDACTED_SECRET]\"}]"
      }
    ]
  }
}

Common Errors and Production Troubleshooting

Deploying zero-trust proxies introduces specific failure modes around TLS certificates, policy enforcement, and stream timeouts.

1. Error Code -32001: RBAC Policy Violation

  • ▸Symptom: The client receives JSON-RPC error code -32001:
    json
    {"jsonrpc": "2.0", "id": 4, "error": {"code": -32001, "message": "Policy Denied: Role 'developer-read-only' lacks permission for tool 'drop_table'."}}
  • ▸Root Cause: An LLM prompt attempted an unlisted or forbidden administrative tool.
  • ▸Fix: Review the gateway RBAC configuration matrix in /etc/mcp-gateway/policies.yaml. If the agent legitimately requires administrative access, update the role mapping in your identity provider and reissue the client's SPIFFE certificate.

2. Error Code -32602: Parameter Sanitization Failure

  • ▸Symptom: The gateway rejects queries with error code -32602:
    json
    {"jsonrpc": "2.0", "id": 5, "error": {"code": -32602, "message": "Security Violation: Destructive SQL keyword 'TRUNCATE' rejected by gateway AST parser."}}
  • ▸Root Cause: The tool arguments contained keywords flagged by the gateway's AST sanitizer.
  • ▸Fix: Ensure the client agent is instructed to use read-only semantics. Verify the gateway SQL validator rules in src/sanitizer.ts.

3. Connection Failures: mTLS Handshake and Network Drops

  • ▸Symptom: ECONNREFUSED or SSL alert number 46 (certificate unknown) during gateway startup.
  • ▸Root Cause: The client certificate is expired, missing intermediate CA chains, or rejected by Envoy's trusted CA bundle.
  • ▸OS-Specific Terminal Fixes:
    • ▸macOS / Linux: Verify your certificate validity and subject alternative names (SAN):
      bash
      openssl verify -CAfile /etc/ssl/certs/ca-chain.crt /etc/ssl/certs/agent-claude.crt
      openssl x509 -in /etc/ssl/certs/agent-claude.crt -text -noout | grep -A 2 "Subject Alternative Name"
    • ▸Windows (PowerShell): Ensure your local proxy certificates are properly imported into the current user certificate store:
      powershell
      Get-ChildItem Cert:\CurrentUser\My | Where-Object { $_.Subject -like "*mcp-gateway*" } | Format-List Subject, NotAfter
      Test-NetConnection -ComputerName mcp-gateway.internal.example.com -Port 443

External Citations and Security Guardrails

To maintain production security and adhere to industry standards, reference the official technical specifications and libraries:

Minimum Privilege Security Checklist

  1. ▸Air-Gapped Credentials: Store upstream database passwords and cloud API keys exclusively in the gateway secret manager. Never provide raw credentials to desktop client configs.
  2. ▸Ephemeral SVIDs: Issue short-lived client mTLS certificates (maximum 4-hour lifespan) with automated rotation via HashiCorp Vault or cert-manager.
  3. ▸Structured Audit Logs: Export every JSON-RPC frame digest to OpenTelemetry or Amazon S3 with tamper-evident hashing to satisfy SOC 2 compliance.
Ready to Deploy?

Build your full agent toolstack in the Visual Generator

Combine verified MCP servers with databases, search APIs, and memory graphs in a single configuration file.

Customize in Generator
Developer Verification & Feedback
0 reports

Did this setup guide work with your AI host?

Help test this configuration across Claude, Cursor, and Codex CLI. Be the first to report:

RT✓

Written by Rad Tome

Lead AI Systems Architect & Maintainer, MCP Codex

Specializing in Model Context Protocol (MCP) integrations, autonomous AI agent orchestration, and distributed developer toolchains. Researches and benchmarks production MCP client-server architectures across OpenAI Codex, Claude, and Cursor.

Editorial Integrity: Package names verified via npm registry API. Repositories verified via GitHub REST API.
Verification Charter →

Related Guides