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.ioresolves 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
- Go to Google Cloud Console
- Create OAuth Client ID
- Configure redirect URI:
{BASE_URL}/api/auth/google/callback
GitHub
- Go to GitHub Developer Settings
- Create new OAuth App
- Configure callback URL:
{BASE_URL}/api/auth/github/callback
Microsoft
- Go to Azure Portal App Registrations
- Create new registration
- 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:
- Fork and clone the repository
- Create a feature branch
- Make changes following coding standards
- 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
