# Mcp Gateway

> Self-hosted MCP gateway/proxy for AI agents — OIDC auth, Casbin RBAC/ABAC, circuit breaking, PII redaction, a 42-connector catalog, and a full admin dashboard. TypeScript.

- **Type:** MCP server
- **Install:** `agentstack add mcp-cuongdev-mcp-gateway`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [cuongdev](https://agentstack.voostack.com/s/cuongdev)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [cuongdev](https://github.com/cuongdev)
- **Source:** https://github.com/cuongdev/mcp-gateway

## Install

```sh
agentstack add mcp-cuongdev-mcp-gateway
```

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

## About

# 🛡️ MCP Gateway

### One gateway for all your MCP servers — with the auth, access control, and observability that production actually needs.

[](https://github.com/cuongdev/mcp-gateway/actions/workflows/ci.yml)
[](LICENSE)
[](package.json)
[](https://www.typescriptlang.org/)
[](https://modelcontextprotocol.io/)
[](https://github.com/cuongdev/mcp-gateway/releases)

A self-hosted **Model Context Protocol (MCP) gateway / proxy** that puts every upstream MCP server behind **one endpoint** — with **OIDC authentication**, **fine-grained access control (RBAC/ABAC/ReBAC)**, **circuit breaking**, **PII/secret redaction**, a **42-connector catalog**, and a full **admin dashboard**.

---

## 💡 Why MCP Gateway?

Connecting AI agents (Claude, Cursor, VS Code…) to MCP servers one-by-one doesn't scale: every client re-configures every server, there's no central auth, no access control, no audit trail, and one flaky upstream can hang everything.

**MCP Gateway** sits in the middle and gives you a single control plane:

- 🔌 **Register once, use everywhere** — agents connect to one `/mcp` endpoint; the gateway fans out to all upstreams.
- 🔐 **Real authentication** — OIDC/SSO login + session cookies + personal access tokens, not just static API keys.
- 🛂 **Fine-grained authorization** — Casbin RBAC/ABAC/ReBAC decides exactly who can call which tool.
- 🧰 **Curated tool surfaces** — expose only the tools an agent needs via scoped group endpoints, cutting context-window pollution.
- 🩺 **Stays up** — per-server circuit breaker + health probes isolate failing upstreams automatically.
- 🕵️ **Stays safe** — built-in PII/secret redaction scrubs tool arguments and responses; approval gates protect sensitive tools.
- 📊 **Stays observable** — Prometheus metrics, OpenTelemetry tracing, JSONL audit logs, and per-principal usage stats.

> Already using **MCPJungle**? See the [honest side-by-side comparison](#-mcp-gateway-vs-mcpjungle) below.

---

## ✨ Features

| | |
|---|---|
| 🔌 **Unified MCP endpoint** | One `/mcp` for all upstreams. Canonical `server__tool` naming keeps names globally unique. |
| 🧰 **Tool Groups** | Curated, role-gated subsets of tools, each on its own endpoint (`/mcp/groups/:name`). |
| 🔐 **OIDC + Sessions + PATs** | SSO login via any OIDC provider, signed session cookies, and personal access tokens. |
| 🛂 **Casbin RBAC/ABAC/ReBAC** | Policy-file access control down to the individual tool. |
| 🩺 **Circuit Breaker** | Per-server state machine (`healthy → degraded → open → half-open`) + background probe recovery. |
| 🕵️ **PII / Secret Redaction** | 22 built-in rules (AWS, GitHub, Stripe, JWT, PEM, credit cards…) with `redact / block / warn` modes. |
| ✅ **Approval Workflows** | Mark tools `sensitive` → calls require admin approval before execution. |
| 🧩 **Virtual Tools** | Compose multiple upstream tools into one declarative DAG meta-tool. |
| 📦 **Connector Catalog** | 42 ready-to-install server templates with a guided install wizard. |
| 🚦 **Rate Limit · Quota · Cache** | Per-principal sliding-window limits, daily/monthly quotas, and tool-call caching (memory / SQL / Redis). |
| 🌐 **Outbound Proxy Mgmt** | Route upstream calls through named HTTP/HTTPS/SOCKS5 proxies. |
| 🏢 **Multi-tenancy** | Tenant isolation with per-tenant scoping. |
| 📊 **Observability** | Prometheus metrics + OpenTelemetry traces + JSONL audit + usage analytics. |
| 🖥️ **Admin Dashboard** | A full web UI for everything above. |

---

## 📸 Dashboard Tour

  
    📦 Connector Catalog42 one-click server templates.
    🕵️ PII / Secret Redaction22 built-in rules, redact/block/warn.
  
  
    🧰 ToolsCanonical server__tool naming.
    🩺 Servers & Circuit HealthLive status + circuit-breaker state.
  
  
    🛂 Policies (Casbin)Fine-grained RBAC/ABAC rules.
    🌐 Outbound ProxiesInline credentials auto-redacted.
  
  
    📊 MetricsPrometheus exposition + live counters.
    👥 IdentityUsers, MCP clients, tokens, OIDC.
  

---

## 🆚 MCP Gateway vs MCPJungle

Both projects solve the same core problem — *"one place to manage and connect to all your MCP servers."* [MCPJungle](https://github.com/mcpjungle/MCPJungle) is a mature, popular, **Go** single-binary gateway. MCP Gateway is a **TypeScript** gateway focused on **enterprise security, governance, and resilience**.

> The table reflects MCPJungle as of its **v0.4.5** (per its public docs/README) and MCP Gateway **v0.8.0**. Corrections welcome via PR.

| Capability | 🛡️ MCP Gateway | 🌿 MCPJungle |
|---|:---:|:---:|
| Language / distribution | TypeScript (Node ≥ 20) | **Go (single binary)** |
| Unified `/mcp` endpoint | ✅ | ✅ |
| Canonical `server__tool` naming | ✅ | ✅ |
| Tool Groups (scoped endpoints) | ✅ updatable, prompts included | ✅ no updates, no prompts in groups |
| Transports | streamable-HTTP, stdio | streamable-HTTP, stdio, SSE *(immature)* |
| **Client / user authentication** | **OIDC/SSO + session cookies + PATs** | Static bearer tokens only *(no OAuth/OIDC)* |
| **Authorization model** | **Casbin RBAC / ABAC / ReBAC** | admin/user roles + per-client allow-lists |
| Upstream auth | bearer token, custom headers | bearer, headers, **upstream OAuth (beta)** |
| **Circuit breaker + health probes** | ✅ | — *(not documented)* |
| **PII / secret redaction** | ✅ 22 rules | ❌ |
| **Approval workflows** | ✅ | ❌ |
| **Virtual tools (composition)** | ✅ DAG | ❌ |
| **Rate limit · quota · cache** | ✅ | — *(not documented)* |
| **Outbound proxy management** | ✅ | ❌ |
| **Multi-tenancy** | ✅ | ❌ |
| Connector catalog | ✅ 42 templates + installer | register via config files |
| MCP spec coverage | tools, prompts, resources, completion, logging, roots | tools, prompts, resources |
| Observability | Prometheus + **OTel tracing** + **JSONL audit** + usage | Prometheus metrics + `/health` |
| Admin dashboard | ✅ | ✅ |
| Maturity | newer (v0.8.0) | **mature** (~1k★, releasing since 2025) |
| License | MIT | MPL-2.0 |

**Choose MCP Gateway when** you need OIDC/SSO user login, fine-grained RBAC/ABAC, audit trails, PII redaction, circuit breaking, approval gates, or multi-tenancy — i.e. **production governance & security**.

**Choose MCPJungle when** you want a lightweight, battle-tested **Go single binary**, the smallest possible footprint, or its **browser-based upstream-OAuth** auto-negotiation. It's a great, more mature option for simpler setups.

*MCPJungle is excellent work and the inspiration for this project — this comparison is about fit, not winners.*

---

## 🚀 Quick Start

> Requires **Node.js >= 20**.

```bash
# Clone
git clone https://github.com/cuongdev/mcp-gateway.git
cd mcp-gateway

# Install dependencies
npm install

# Copy the env template and adjust as needed
cp .env.example .env

# Development mode (no auth, full access)
npm run dev

# Web dashboard (separate Vite dev server)
npm run dev:web

# Enterprise mode (OIDC + strict ACL)
GATEWAY_MODE=enterprise \
OIDC_DISCOVERY_URL=https://your-provider/.well-known/openid-configuration \
OIDC_CLIENT_ID=mcp-gateway \
OIDC_AUDIENCES=mcp-gateway \
GATEWAY_SESSION_SECRET="$(openssl rand -hex 32)" \
npm run dev
```

### Production build & CLI

```bash
npm run build              # compile to dist/ + bundle the web dashboard
npm start                  # run the compiled gateway
./bin/mcp-gateway --help   # admin CLI: register servers, manage tools/policies/catalog, etc.
```

---

## 🧩 Key Concepts

**Canonical Tool Naming** — every tool is exposed as `server-name__tool-name`, so names stay globally unique across servers (`filesystem__read_file`, `database__query_data`).

**Tool Groups** — curated subsets of tools with dedicated MCP endpoints. An agent on `/mcp/groups/data-analyst` only sees data tools, reducing context-window pollution.

**Dual Mode** — *Development* (no auth, full access, console logging) for local use; *Enterprise* (OIDC, strict Casbin ACL, file audit, metrics) for production.

**Session Manager** — abstracts transport differences: HTTP servers use `fetch`; STDIO servers use persistent child processes with idle timeouts.

---

## 📡 API Reference

### MCP Endpoints (for AI agents)

| Method   | Path                  | Description                       |
|----------|-----------------------|-----------------------------------|
| `POST`   | `/mcp`                | MCP JSON-RPC (all tools)          |
| `GET`    | `/mcp`                | SSE stream (server notifications) |
| `DELETE` | `/mcp`                | Close MCP session                 |
| `POST`   | `/mcp/groups/:name`   | Group-scoped MCP JSON-RPC         |

### Admin REST API (for developers)

| Method   | Path                          | Description                     |
|----------|-------------------------------|---------------------------------|
| `GET`    | `/api/health`                 | Gateway health check            |
| `GET`    | `/api/metrics`                | Prometheus metrics              |
| `GET`    | `/api/servers`                | List registered servers         |
| `POST`   | `/api/servers`                | Register a new MCP server       |
| `DELETE` | `/api/servers/:name`          | Deregister a server             |
| `POST`   | `/api/servers/:name/sync`     | Re-discover tools from server   |
| `GET`    | `/api/tools`                  | List all tools (canonical names)|
| `PUT`    | `/api/tools/:name/enable`     | Enable a tool                   |
| `PUT`    | `/api/tools/:name/disable`    | Disable a tool                  |
| `GET`    | `/api/groups`                 | List tool groups                |
| `POST`   | `/api/groups`                 | Create a tool group             |
| `GET`    | `/api/groups/:name`           | Get group details               |
| `PUT`    | `/api/groups/:name`           | Update a group                  |
| `DELETE` | `/api/groups/:name`           | Delete a group                  |
| `GET`    | `/api/policies`               | List Casbin policies            |
| `POST`   | `/api/policies`               | Add a policy rule               |
| `POST`   | `/api/policies/reload`        | Reload policies from file       |
| `POST`   | `/api/roles`                  | Assign role to user             |

---

## ⚙️ Configuration

### Server Registration

```json
{
  "servers": [
    {
      "name": "my-db",
      "transport": {
        "type": "streamable-http",
        "url": "http://localhost:8002/mcp",
        "bearerToken": "optional-token"
      },
      "autoDiscover": true
    },
    {
      "name": "local-tools",
      "transport": {
        "type": "stdio",
        "command": "node",
        "args": ["./my-mcp-server.js"],
        "stateful": true
      }
    }
  ]
}
```

### Tool Groups

```json
{
  "groups": [
    {
      "name": "data-analyst",
      "description": "Read-only data tools",
      "tools": ["my-db__query_data", "my-db__get_report"],
      "allowedRoles": ["analyst", "admin"]
    }
  ]
}
```

### Access Control (Casbin)

Edit `config/policy.csv`:

```csv
p, admin, *, *
p, analyst, tool:database__*, execute
p, user, tool:filesystem__read_file, execute

g, admin, analyst
g, analyst, user
g, alice@example.com, admin
```

---

## 📚 Documentation

- [Architecture](ARCHITECTURE.md) — components, request flow, module layout
- [Connector Catalog](docs/guides/catalog.md)
- [Circuit Breaker](docs/guides/circuit-breaker.md)
- [PII / Secret Redaction](docs/guides/redaction.md)
- [Virtual Tools](docs/guides/virtual-tools.md)
- [MCP Spec Coverage](docs/guides/mcp-spec-coverage.md)
- [Migration from v0.1](docs/guides/migration-from-v0.1.md)

---

## 🗒️ Release Highlights

### v0.8.0 — Pipeline Platform

Five user-visible features built on a unified foundation:

- **Circuit Breaker** — per-server state machine + probe-loop recovery; `mcp_circuit_*` metrics; `/circuits` dashboard.
- **PII / Secret Redaction** — 22 built-in rules, `redact/block/warn` modes, custom per-tenant rules, `safe-regex` validation; `/redaction` dashboard.
- **Full MCP Spec Coverage** — resources, prompts, completion, logging, roots in addition to tools.
- **Connector Catalog** — 42 seed templates, atomic installer with env validation + rollback; `/catalog` install wizard.
- **Virtual Tools** — declarative DAG composition of upstream tools, AJV-validated plans; `/virtual-tools` editor.

Earlier releases (v0.3 – v0.7)

- **v0.7.0-p5 — Outbound proxies:** named HTTP/HTTPS/SOCKS5 proxies with 3-level precedence, password redaction, fail-closed routing.
- **v0.6.0-p4 — Multi-tenancy:** `tenants` table, `X-Tenant` resolution middleware, system admin API, `tenant_id` scoping.
- **v0.5.0-p3 — Differentiation:** approval workflow, webhook dispatcher (HMAC-signed), OpenAPI 3.x → MCP adapter with SSRF guard.
- **v0.4.0-p2 — Hardening:** OIDC↔Principal unification, rate limiting, quotas, tool-call caching, OpenTelemetry tracing.
- **v0.3.0-p1 — Parity:** MCP client provisioning, user accounts + PATs, prompt registry, usage stats, Postgres adapter, full CLI.

---

## 🛠️ Tech Stack

**Hono** (HTTP) · **jose** (JWT/OIDC) · **Casbin** (policy engine) · **Pino** (logging) · **prom-client** (metrics) · **Zod** (config) · **React + Vite** (dashboard) · **libSQL / Postgres** (storage)

---

## 📄 License

[MIT](LICENSE) © Cuong Tuan Nguyen

Inspired by MCPJungle · Built with TypeScript

## Source & license

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

- **Author:** [cuongdev](https://github.com/cuongdev)
- **Source:** [cuongdev/mcp-gateway](https://github.com/cuongdev/mcp-gateway)
- **License:** MIT

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:** no
- **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-cuongdev-mcp-gateway
- Seller: https://agentstack.voostack.com/s/cuongdev
- 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%.