Mcpx

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

For detailed workflows with sequence diagrams and RBAC matrix, see Use Cases.

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:

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:

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.

Test Credentials

Quick Start

Prerequisites

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:

Kubernetes Local

For testing Kubernetes deployments locally with HTTPS support.

Prerequisites

Create Cluster

cat <<EOF | kind create cluster --name local --config=-
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
  kubeadmConfigPatches:
  - |
    kind: InitConfiguration
    nodeRegistration:
      kubeletExtraArgs:
        node-labels: "ingress-ready=true"
  extraPortMappings:
  - containerPort: 80
    hostPort: 80
    protocol: TCP
  - containerPort: 443
    hostPort: 443
    protocol: TCP
EOF

Install Dependencies

kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/deploy/static/provider/kind/deploy.yaml

kubectl wait --namespace ingress-nginx \
  --for=condition=ready pod \
  --selector=app.kubernetes.io/component=controller \
  --timeout=120s

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.0/cert-manager.yaml

kubectl wait --for=condition=Available deployment --all -n cert-manager --timeout=120s

Build and Load Images

docker build --target web -t mcpx-backend:latest ./backend
docker build --target worker -t mcpx-worker:latest ./backend
docker build -t mcpx-frontend:latest ./frontend

kind load docker-image mcpx-backend:latest --name local
kind load docker-image mcpx-worker:latest --name local
kind load docker-image mcpx-frontend:latest --name local

Configure Secrets

cp k8s/base/secrets.yaml k8s/overlays/local-https/secrets.local.yaml

Edit k8s/overlays/local-https/secrets.local.yaml with your credentials.

Deploy

kubectl apply -k k8s/overlays/local-https

Access the application at https://mcpx.127.0.0.1.nip.io

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

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

    subgraph K8s["Kubernetes Cluster"]
        direction TB
        subgraph Services
            Web["Web<br/>3+ replicas"]
            Worker["Worker<br/>2+ replicas"]
        end
    end

    subgraph Data["Managed Services"]
        DB[("PostgreSQL<br/>TimescaleDB")]
    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.

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

Secrets Management

Use your cloud provider's secrets management service:

Integrate with Kubernetes using External Secrets Operator.

Deploy

kubectl apply -k k8s/overlays/production

Production Checklist

Configuration

Environment Variables

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

* 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

Server Management

Gateway Management

MCP Proxy

Metrics and Audit

Tech Stack

Contributing

Contributions are welcome. Please read 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.

License

This project is licensed under the Apache License 2.0. See LICENSE for details.

Support

For questions or issues, contact [email protected] or open an issue on GitHub.

Copyright 2025 TM Dev Lab