# Mcpx

> A self-hosted MCP Gateway for enterprise environments. Secure AI agent connections to MCP servers with tool governance, multi-tenant isolation, and full observability. Built with Rust and Vue.

- **Type:** MCP server
- **Install:** `agentstack add mcp-thiagomendes-mcpx`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [thiagomendes](https://agentstack.voostack.com/s/thiagomendes)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [thiagomendes](https://github.com/thiagomendes)
- **Source:** https://github.com/thiagomendes/mcpx
- **Website:** https://www.tmdevlab.com/mcpx-gateway-incubating.html

## Install

```sh
agentstack add mcp-thiagomendes-mcpx
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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](https://www.tmdevlab.com). While functional, it may contain bugs or incomplete features. If you encounter issues, please report them via [GitHub Issues](https://github.com/thiagomendes/mcpx/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

```mermaid
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:

  
    
      
        
        01. Create Server
      
    
    
      
        
        02. Create Gateway
      
    
    
      
        
        03. Observability
      
    
    
      
        
        04. 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

```bash
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:

```bash
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

```bash
docker compose build
docker compose up -d
```

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

### Verify Installation

```bash
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

```bash
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](https://www.timescale.com/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](https://external-secrets.io/).

#### Deploy

```bash
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](https://console.cloud.google.com/apis/credentials)
2. Create OAuth Client ID
3. Configure redirect URI: `{BASE_URL}/api/auth/google/callback`

#### GitHub

1. Go to [GitHub Developer Settings](https://github.com/settings/developers)
2. Create new OAuth App
3. Configure callback URL: `{BASE_URL}/api/auth/github/callback`

#### Microsoft

1. Go to [Azure Portal App Registrations](https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade)
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](https://github.com/thiagomendes)
- **Source:** [thiagomendes/mcpx](https://github.com/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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-thiagomendes-mcpx
- Seller: https://agentstack.voostack.com/s/thiagomendes
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.