Mcpx

mcpx

The MCP Gateway for Enterprise

Bridge the gap between AI agents and your data. Secure, scalable, production-grade.

Features • Quick Start • Deployment • Configuration • Use Cases • API • Contributing

> Note: This is an incubating project maintained by TM Dev Lab. While functional, it may contain bugs or incomplete features. If you encounter issues, please report them via GitHub Issues or consider contributing a fix following our [Contributing Guidelines](CONTRIBUTING.md).

Overview

mcpx is a self-hosted gateway for the Model Context Protocol (MCP). It enables organizations to securely connect AI agents to MCP servers while maintaining full control over access, credentials, and observability.

> Scope: mcpx focuses exclusively on MCP Tools, which represent the majority of protocol usage. Resources and Prompts are not currently supported.

Key Capabilities

| Capability | Description | |------------|-------------| | Proxy Layer | Route MCP traffic through a central gateway with credential injection | | Tool Governance | Allowlist or blocklist specific tools per server | | Virtual Gateways | Aggregate multiple servers into a single endpoint | | Observability | Audit logs, real-time metrics, and alerting | | Authentication | OAuth, API Keys, Bearer Tokens, and Service Accounts | | Multi-tenancy | Isolated organizations with role-based access control |

For detailed workflows with sequence diagrams and RBAC matrix, see [Use Cases](USECASES.md).

Architecture

flowchart LR
    subgraph Clients
        CD["Claude Desktop"]
        VS["VS Code"]
        Agent["AI Agents"]
    end

    subgraph mcpx["mcpx Gateway"]
        Proxy["MCP Proxy"]
        Auth["Auth"]
        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

Features

Connect Instantly

Point to any MCP server via URL. mcpx handles credential injection and protocol compliance automatically.

Tool Governance

Control which tools AI agents can access. Define allowlists or blocklists per server, and apply prefixes to tool names for namespace isolation.

Full Observability

Every MCP request is logged with timestamps, latency, tool names, and full request/response payloads. Query metrics by time range, server, or tool.

Rate Limiting

Protect your MCP servers with per-server rate limits. Configurable requests per minute with automatic 429 responses.

Flexible Authentication

Support for multiple authentication methods:

| Method | Use Case | |--------|----------| | OAuth | User authentication via Google, GitHub, or Microsoft | | Personal Access Tokens | Programmatic access for users | | Service Accounts | Machine-to-machine communication | | API Keys and Bearer Tokens | Credential injection to upstream servers |

Gateway Aggregation

Combine multiple MCP servers into a single endpoint. Connect Claude Desktop to one URL and access all your tools seamlessly.

See it in Action

Watch some of the key features in action:

1. Create Server

1. Create Gateway

1. Observability

1. Alerts

Example MCP Servers

The project includes example MCP servers in the mcp-servers-examples/ directory for testing different authentication methods. These servers start automatically with Docker Compose.

| Server | Auth Method | Internal URL | |--------|-------------|--------------| | weather-mcp | API Key | http://weather-mcp:8000/mcp | | utilities-mcp | Bearer Token | http://utilities-mcp:8000/mcp | | filesystem-mcp | OAuth Client Credentials | http://filesystem-mcp:8000/mcp |

Test Credentials

| Server | Credential | |--------|------------| | weather-mcp | Header: X-API-Key: weather-api-key-12345 | | utilities-mcp | Header: Authorization: Bearer utilities-token-secret-67890 | | filesystem-mcp | Client ID: filesystem-client, Secret: filesystem-secret-abc123 |

Quick Start

Prerequisites

| Software | Version | |----------|---------| | Docker | 24.x or later | | Docker Compose | 2.20 or later |

Clone and Configure

git clone https://github.com/thiagomendes/mcpx.git
cd mcpx

cp .env.example .env

Edit .env with your OAuth credentials. At minimum, configure one OAuth provider:

JWT_SECRET=your-32-character-secret-here

GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret

FRONTEND_URL=http://localhost:3000
BASE_URL=http://localhost:8080

Build and Start

docker compose build
docker compose up -d

> Note: First build may take a few minutes. Subsequent builds are cached.

Verify Installation

docker compose ps

curl http://localhost:8080/api/health

Open http://localhost:3000 to access the dashboard.

Deployment

mcpx supports multiple deployment options:

| Environment | Method | Documentation | |-------------|--------|---------------| | Local Development | Docker Compose | [Quick Start](#quick-start) | | Local Kubernetes | Kind with HTTPS | [Kubernetes Local](#kubernetes-local) | | Production | Kubernetes with managed services | [Production Deployment](#production-deployment) |

Kubernetes Local

For testing Kubernetes deployments locally with HTTPS support.

Prerequisites

| Software | Version | |----------|---------| | kubectl | 1.28 or later | | kind | 0.20 or later |

Create Cluster

cat  The domain `mcpx.127.0.0.1.nip.io` resolves to 127.0.0.1 automatically. No hosts file modification required.

### Production Deployment

For production environments on cloud providers (AWS, GCP, Azure).

#### Architecture

```mermaid
flowchart TB
    subgraph Internet
        LB["Load Balancer + TLS"]
    end

    subgraph K8s["Kubernetes Cluster"]
        direction TB
        subgraph Services
            Web["Web3+ replicas"]
            Worker["Worker2+ replicas"]
        end
    end

    subgraph Data["Managed Services"]
        DB[("PostgreSQLTimescaleDB")]
    end

    LB --> Web
    LB --> Worker
    Web --> DB
    Worker --> DB

    style LB fill:#6366f1,stroke:#4f46e5,color:#fff
    style Web fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style Worker fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style DB fill:#06b6d4,stroke:#0891b2,color:#fff

Managed Database

mcpx requires PostgreSQL with the TimescaleDB extension.

| Provider | Managed PostgreSQL | TimescaleDB Support | |----------|-------------------|---------------------| | AWS | RDS for PostgreSQL | Not available | | GCP | Cloud SQL | Not available | | Azure | Flexible Server | Available |

For AWS and GCP, use Timescale Cloud or run TimescaleDB in Kubernetes.

Secrets Management

Use your cloud provider's secrets management service:

| Provider | Service | |----------|---------| | AWS | Secrets Manager | | GCP | Secret Manager | | Azure | Key Vault |

Integrate with Kubernetes using External Secrets Operator.

Deploy

kubectl apply -k k8s/overlays/production

Production Checklist

| Item | Status | |------|--------| | Managed database with backups | Required | | Secrets in vault (not in git) | Required | | TLS via cloud provider | Required | | Horizontal Pod Autoscaler | Recommended | | Resource limits configured | Recommended | | Network policies | Recommended |

Configuration

Environment Variables

> Note: When using Docker Compose, most variables have sensible defaults. Only OAuth credentials and JWT_SECRET are required.

| Variable | Required | Description | |----------|:--------:|-------------| | JWT_SECRET | Yes | Secret for JWT signing (32+ characters) | | GOOGLE_CLIENT_ID | | Google OAuth client ID | | GOOGLE_CLIENT_SECRET | | Google OAuth client secret | | GITHUB_CLIENT_ID | | GitHub OAuth client ID | | GITHUB_CLIENT_SECRET | | GitHub OAuth client secret | | MICROSOFT_CLIENT_ID | | Microsoft OAuth client ID | | MICROSOFT_CLIENT_SECRET | | Microsoft OAuth client secret | | DATABASE_URL | ** | PostgreSQL connection string | | FRONTEND_URL | No | Frontend URL (default: http://localhost:3000) | | BASE_URL | No | Backend URL for OAuth callbacks | | RUST_LOG | No | Log level (default: info) | | ENCRYPTION_KEY | No | AES encryption key (defaults to JWT_SECRET) |

\* At least one OAuth provider is required.

\\ Required for standalone deployment. Docker Compose sets this automatically.

OAuth Provider Setup

Google

1. Go to Google Cloud Console
2. Create OAuth Client ID
3. Configure redirect URI: {BASE_URL}/api/auth/google/callback

GitHub

1. Go to GitHub Developer Settings
2. Create new OAuth App
3. Configure callback URL: {BASE_URL}/api/auth/github/callback

Microsoft

1. Go to Azure Portal App Registrations
2. Create new registration
3. Add redirect URI: {BASE_URL}/api/auth/microsoft/callback

API Reference

Authentication Endpoints

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/auth/{provider} | Initiate OAuth flow | | GET | /api/auth/{provider}/callback | OAuth callback | | POST | /api/auth/logout | End session | | GET | /api/auth/me | Current user info |

Server Management

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/servers | List servers | | POST | /api/servers | Create server | | GET | /api/servers/{name} | Get server | | PUT | /api/servers/{name} | Update server | | DELETE | /api/servers/{name} | Delete server |

Gateway Management

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/gateways | List gateways | | POST | /api/gateways | Create gateway | | GET | /api/gateways/{slug} | Get gateway | | PUT | /api/gateways/{slug} | Update gateway | | DELETE | /api/gateways/{slug} | Delete gateway |

MCP Proxy

| Method | Endpoint | Description | |--------|----------|-------------| | POST | /mcp/{org_slug}/{server} | Proxy MCP request to server | | POST | /mcp/{org_slug}/gw/{gateway} | Proxy MCP request to gateway |

Metrics and Audit

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/metrics/query | Query time-series metrics | | GET | /api/metrics/summary | Percentile summary | | GET | /api/audit | List audit logs | | GET | /api/audit/{id} | Audit log details |

Tech Stack

| Component | Technology | |-----------|------------| | Backend | Rust with Axum | | Frontend | Vue 3 with TypeScript | | Database | PostgreSQL 15 with TimescaleDB | | Authentication | OAuth with JWT | | Container Runtime | Docker | | Orchestration | Kubernetes |

Contributing

Contributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on:

1. Fork and clone the repository
2. Create a feature branch
3. Make changes following coding standards
4. Submit a pull request

For AI-assisted development guidelines, see [AGENT.md](AGENT.md).

License

This project is licensed under the Apache License 2.0. See [LICENSE](LICENSE) for details.

Support

For questions or issues, contact mail.thiagomendes@gmail.com or open an issue on GitHub.

Copyright 2025 TM Dev Lab

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: thiagomendes
• Source: thiagomendes/mcpx
• License: Apache-2.0
• Homepage: https://www.tmdevlab.com/mcpx-gateway-incubating.html

Install and usage instructions live in the source repository linked above.