mcpx: MCP Gateway for Enterprise

1. The Problem

As AI agents become increasingly capable, the need to connect them to enterprise data and tools grows proportionally. The Model Context Protocol (MCP), introduced by Anthropic and now supported by major industry players, emerged as the standard for this integration. However, deploying MCP servers in production environments reveals several challenges:

• Credential Management: Each MCP server may require different authentication methods (API keys, OAuth tokens, certificates). Agents shouldn't hold these credentials directly, both for security reasons and to avoid credential sprawl across multiple clients.
• Access Control: Not every tool should be available to every agent. Organizations need granular control over which tools can be invoked, with audit trails for compliance.
• Multi-tenancy: Different teams, projects, or customers need isolated environments with their own servers, credentials, and configurations—without deploying separate infrastructure.
• Observability: Understanding what agents are doing, which tools they invoke, latency patterns, and error rates requires comprehensive logging, metrics, and alerting.
• Connection Management: Managing multiple MCP server URLs across different clients (desktop apps, IDEs, custom agents) becomes unwieldy at scale.

The N×M Problem: Without a gateway, each agent (N) must be configured individually for each MCP server (M), leading to N×M configurations. A gateway reduces this to N+M configurations—each agent connects to one gateway, and the gateway manages all server connections.

mcpx addresses these challenges by providing a central gateway layer between AI agents and MCP servers, inspired by API gateway patterns that have proven effective in microservices architectures.

2. Architecture Overview

mcpx acts as a reverse proxy that sits between MCP clients (desktop apps, IDEs, custom agents) and your MCP servers. The architecture follows established gateway patterns with credential injection, governance enforcement, and comprehensive audit logging.

flowchart LR
    subgraph Clients["MCP Clients"]
        CD["Desktop Apps"]
        VS["IDEs"]
        Agent["Custom Agents"]
    end

    subgraph mcpx["mcpx Gateway"]
        Proxy["MCP Proxy"]
        Auth["Auth Layer"]
        Gov["Governance"]
        Audit["Audit Log"]
    end

    subgraph Servers["MCP Servers"]
        S1["Finance MCP"]
        S2["HR MCP"]
        S3["External MCP"]
    end

    CD --> Proxy
    VS --> Proxy
    Agent --> Proxy
    Proxy --> Auth
    Auth --> Gov
    Gov --> S1
    Gov --> S2
    Gov --> S3
    Proxy --> Audit

    style Proxy fill:#6366f1,stroke:#4f46e5,color:#fff
    style Auth fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style Gov fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style Audit fill:#06b6d4,stroke:#0891b2,color:#fff
                    

Core Components

3. Server Management

Servers represent external MCP endpoints that mcpx proxies requests to. Each server is registered with connection details and authentication credentials that are securely stored and injected at request time.

Supported Authentication Methods

• API Key: Header-based authentication (e.g., X-API-Key: secret)
• Bearer Token: Standard OAuth-style bearer tokens in the Authorization header
• OAuth Client Credentials: Automatic token acquisition and refresh using client_id/client_secret

sequenceDiagram
    participant User
    participant Dashboard
    participant API as mcpx API
    participant DB as Database

    User->>Dashboard: Fill server form
    Dashboard->>API: POST /api/servers
    API->>API: Validate request
    API->>DB: Insert server record
    DB-->>API: Server created
    API->>API: Test connection (optional)
    API-->>Dashboard: Return server details
    Dashboard->>User: Show success

    rect rgb(99, 102, 241)
        Note over API: Server stored with
org_id for isolation
    end
                    

Credential Security

Credentials are encrypted at rest using AES-256-GCM before storage. The encryption key is derived from the ENCRYPTION_KEY environment variable (or JWT_SECRET if not set). Credentials are never exposed in API responses—only a masked indicator is returned.

4. MCP Proxy Flow

When an MCP client invokes a tool, the request flows through several processing stages before reaching the upstream server. Each stage adds security, governance, or observability capabilities.

sequenceDiagram
    participant Client as MCP Client
    participant Proxy as mcpx Proxy
    participant Gov as Governance
    participant Upstream as MCP Server
    participant Audit as Audit Log
    participant Metrics as Metrics

    Client->>Proxy: tools/call (tool_name, args)
    Proxy->>Proxy: Authenticate request
    Proxy->>Gov: Check governance rules
    
    alt Tool blocked
        Gov-->>Proxy: Denied
        Proxy-->>Client: Error: tool not allowed
    else Tool allowed
        Gov-->>Proxy: Allowed
        Proxy->>Proxy: Inject upstream credentials
        Proxy->>Upstream: Forward request
        Upstream-->>Proxy: Tool result
        Proxy->>Audit: Log invocation
        Proxy->>Metrics: Record latency
        Proxy-->>Client: Return result
    end

    rect rgb(99, 102, 241)
        Note over Proxy: Credentials injected
per server config
    end

    rect rgb(139, 92, 246)
        Note over Gov: Allowlist/blocklist
enforcement
    end

    rect rgb(6, 182, 212)
        Note over Audit,Metrics: Full request/response
captured
    end
                    

Request Processing Stages

1. Authentication: Validate the client's JWT session, Personal Access Token, or Service Account credentials
2. Server Resolution: Map the request to the appropriate upstream MCP server based on the tool name or gateway configuration
3. Governance Check: Apply allowlist/blocklist rules to determine if the tool invocation is permitted
4. Credential Injection: Add the appropriate authentication headers for the upstream server
5. Upstream Call: Forward the MCP request to the upstream server and await response
6. Audit & Metrics: Record the complete invocation (sanitized) in the audit log and update metrics
7. Response: Return the upstream response to the client

5. Tool Governance

Each server can have governance rules applied to control which tools are exposed through the proxy. This enables fine-grained access control without modifying the upstream MCP servers.

Governance Modes

Tool Prefixing

When multiple MCP servers expose tools with the same name, conflicts arise. mcpx solves this with optional tool prefixing: tools are namespaced with a server-specific prefix, making them unique.

// Without prefix (conflict)
Server A: get_user()
Server B: get_user()

// With prefix (unique)
Server A (prefix: "hr_"): hr_get_user()
Server B (prefix: "crm_"): crm_get_user()

flowchart TB
    subgraph Request["Incoming Request"]
        TR["tools/call: hr_get_user"]
    end

    subgraph Governance["Governance Engine"]
        PM["Prefix Matcher"]
        RL["Rule Lookup"]
        AL["Allowlist Check"]
    end

    subgraph Result["Result"]
        Allow["✓ Allowed"]
        Block["✗ Blocked"]
    end

    TR --> PM
    PM --> RL
    RL --> AL
    AL --> Allow
    AL --> Block

    style PM fill:#6366f1,stroke:#4f46e5,color:#fff
    style RL fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style AL fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style Allow fill:#10b981,stroke:#059669,color:#fff
    style Block fill:#ef4444,stroke:#dc2626,color:#fff
                    

6. Virtual Gateways

For agents that need access to tools across multiple servers, Virtual Gateways provide a single endpoint that aggregates tools from configured servers. The client connects to one URL and gains access to all tools, with governance applied per-server.

flowchart LR
    subgraph Client["MCP Client"]
        Agent["MCP Client"]
    end

    subgraph Gateway["Virtual Gateway"]
        VG["Single Endpoint
/mcp/gateway/all-tools"]
    end

    subgraph Servers["Aggregated Servers"]
        S1["Finance MCP
balance, transfer"]
        S2["HR MCP
lookup, schedule"]
        S3["CRM MCP
contacts, deals"]
    end

    Agent --> VG
    VG --> S1
    VG --> S2
    VG --> S3

    style VG fill:#6366f1,stroke:#4f46e5,color:#fff
    style S1 fill:#1e293b,stroke:#8b5cf6,color:#f8fafc
    style S2 fill:#1e293b,stroke:#8b5cf6,color:#f8fafc
    style S3 fill:#1e293b,stroke:#8b5cf6,color:#f8fafc
                    

Benefits of Virtual Gateways

• Simplified Configuration: Agents only need one URL, regardless of backend complexity
• Dynamic Tool Discovery: Adding a server to the gateway makes its tools available immediately
• Consistent Governance: Per-server governance rules apply even through the gateway
• Unified Authentication: One credential for the gateway, separate credentials per upstream server

7. Observability

Understanding what's happening in a production MCP deployment is critical for debugging, optimization, and compliance. mcpx provides comprehensive observability across three dimensions:

Metrics Dashboard

• Real-time latency percentiles (P50, P95, P99) per server and tool
• Request throughput and error rate visualization
• Time-series data powered by TimescaleDB with automatic retention policies
• Filterable by server, time range, and tool

Audit Logs

• Complete record of all tool invocations
• Request and response payloads (with sensitive data redaction options)
• User, timestamp, server, and outcome (success/error)
• Searchable and exportable for compliance requirements

Health Monitoring

• Periodic health checks against registered MCP servers
• Last-seen status with latency information
• Automatic alerting on server unavailability

Alerting

Configure alert rules to be notified when things go wrong:

• Threshold alerts: Trigger when metrics exceed defined values (e.g., error rate > 5%)
• Spike detection: Trigger on sudden increases in latency or error rates
• No-data alerts: Trigger when expected data stops flowing

8. Authentication & RBAC

mcpx implements a layered authentication model supporting both interactive users and programmatic access.

User Authentication

Users authenticate via OAuth providers (Google, GitHub, Microsoft). Multiple providers can be linked to the same account based on email address. On first login, a personal organization is created automatically.

Programmatic Access

• Personal Access Tokens (PATs): User-scoped tokens with configurable expiration for automation scripts
• Service Accounts: Machine-to-machine authentication using OAuth Client Credentials flow, ideal for CI/CD pipelines

Role-Based Access Control

Each organization has three roles with distinct permissions:

9. Deployment

mcpx provides deployment configurations for both local development and production environments.

Technical Stack

• Backend: Rust with Axum framework for high-performance async HTTP handling
• Frontend: Vue 3 with TypeScript and Tailwind CSS
• Database: TimescaleDB (PostgreSQL with time-series extensions)
• Authentication: OAuth with JWT sessions

Docker Compose

For local development and testing, Docker Compose provides single-command startup:

# Build and start all services
docker compose build
docker compose up -d

# Access the dashboard
open http://localhost:3000

Kubernetes

For production deployments, mcpx provides Kustomize-based manifests with overlays for different environments:

• Local overlay: For Kind, k3s, or minikube with NodePort services
• Production overlay: With Ingress, TLS, resource limits, and horizontal pod autoscaling

10. Status: Incubating

mcpx is currently in incubating status. The core functionality is working and tested, but the project may contain bugs and the API surface may change as we iterate based on real-world usage.

What's Next

• Enhanced governance policies with more granular controls
• Integration with external policy engines (OPA, Cedar)
• Improved metrics and alerting capabilities
• Documentation and onboarding improvements based on community feedback

11. References

1. Anthropic. (2024). "Model Context Protocol Specification." Anthropic. Retrieved from https://modelcontextprotocol.io/specification/2025-11-25
2. Production-Ready MCP Series. (2025). "From Localhost to Production on Kubernetes." TM Dev Lab. Retrieved from scalable-mcp-servers-kubernetes.html
3. Production-Ready MCP Series. (2025). "Gateway Architecture & Federated Registries." TM Dev Lab. Retrieved from mcp-gateway-architecture-enterprise.html
4. Production-Ready MCP Series. (2025). "Zero Trust Security & Governance." TM Dev Lab. Retrieved from mcp-zero-trust-security-governance.html
5. mcpx Repository. (2026). "MCP Gateway for Enterprise." GitHub. Retrieved from https://github.com/thiagomendes/mcpx