Mcpr Gateway

MCPR Gateway

A self-hosted code execution MCP gateway that turns standard upstream MCP servers into sandboxed, dynamically discoverable execution backends — with governed routing and namespace-aware access control.

> Some say MCP is dead, hopefully we can give it CPR.. 🥁

| Demo |

Inspired by

• Anthropic's Code Execution
• Cloudflare Code Mode

Current features

| Category | Feature | Status | |---------------------------|-----------------------------------|-----------| | 🗄️ Database | SQLite Support | ✅ | | | PostgreSQL Support | ❌ Planned | | 🖥️ Interface & Admin | WebUI and Admin API | ✅ | | | Active sessions management | ✅ | | | Bootstrap file support | ✅ | | | Config versioning & rollback | ✅ | | | Config export as JSON | ✅ | | ⚙️ Operating Modes | All Tools Loaded Mode | ✅ Default | | | Two-tool Low Schema Mode | ✅ Compat | | | BM25 / lexical ranking | ✅ Compat | | | Sandbox Execution Tool discovery | ✅ Code | | 📡 Transport | HTTP-Streamable Support | ✅ | | | Stdio Support | ❌ Planned | | | Stdio Interactive Auth | ✅ | | | Protocol version negotiation | ✅ | | 🔌 Downstream Servers | Tool editing | ✅ | | | Tool token usage counter | ✅ | | | Namespaces for isolation | ✅ | | | Token ENV Support | ✅ | | | Encrypted Token SQL Storage | ✅ | | | OAuth Support | ✅ | | | Bearer Token Support | ✅ | | | Command allowlist (stdio) | ✅ | | | Health-aware tool ranking | ✅ | | | Tool quarantining | ✅ | | | Server import preview | ✅ | | 🛡️ Security | External idP + DCR OAuth | ✅ | | | Bearer token per user/service | ✅ | | | SSRF protection | ✅ | | | Shell injection prevention | ✅ | | | OAuth URL allowlist (wildcards) | ✅ | | | Env var sanitization | ✅ | | | Admin session (HttpOnly cookie) | ✅ | | | HTTP security headers | ✅ | | | CORS restricted to loopback | ✅ | | 🎯 Focus Mode | Adaptive tool window | ✅ | | | Tool capability inference | ✅ | | | Write/admin/unhealthy penalties | ✅ | | | Successful pattern tracking | ✅ | | ⚡ Resilience | Per-session rate limiting | ✅ | | | Per-user rate limiting | ✅ | | | Per-downstream concurrency | ✅ | | | Circuit breaker | ✅ | | | Connect/response/total timeouts | ✅ | | 🔄 Triggers | refreshOnSuccess | ✅ | | | refreshOnTimeout | ✅ | | | refreshOnError | ✅ | | | FirstSuccessInDomain | ✅ | | | ErrorThreshold | ✅ | | | IdleTimeout | ✅ | | | replaceOrAppend mode | ✅ | | | cooldownSeconds | ✅ | | 📦 Starter Packs | preferredTags filtering | ✅ | | | Risk level filtering | ✅ | | | Mode filtering | ✅ | | | maxTools cap | ✅ | | 💾 Code Runtime | Artifact store (save/list) | ✅ | | | Result APIs (pick/limit/grep) | ✅ | | | Handle registry (TTL-based) | ✅ | | | Memory/execution limits | ✅ | | 🔐 RBAC | Roles (allow/deny namespaces) | ✅ | | | Permission Management | ✅ | | | Bearer Token Management | ✅ | | | Allowed OAuth providers | ✅ | | 🏷️ Tool Trust | Risk levels (Low/Med/High) | ✅ | | | Source trust (Untrusted/Verified) | ✅ | | | Schema compression | ✅ | | 🔍 Observability | Auto refresh tools | ✅ | | | Audit & Observability | ✅ | | | Pino structured logging | ✅ | | | Audit log pruning | ✅ | | | Debug endpoints (loopback) | ✅ | | 🔌 Client Support | Claude Code | ✅ | | | OpenAI Codex | ✅ | | | OpenCode | ✅ | | | Claude Web Client | ✅ | | | ChatGPT Web Client | ✅ |

Operating Modes

| Mode | Tool Window | Best For | |-------------|-----------------------------------------------------|----------------------------------------| | Code | 2 tools only | Auto orchestration in a JS sandbox | | Compat | 4 meta-tools | Large tool sets, minimal context usage | | Default | All enabled downstream tools, filtered by namespace | Full transparency, small tool sets |

Go to [Benchmarking](#-benchmarking) for current token-usage comparison details.

Modes are configured per namespace and can be mixed across different access paths. For instance, you can create a mcp/dev with complex tools to be used in code mode or /mcp/personal with a small set of tools to be used in default mode for example.

Demo

---

🏗️ Architecture

flowchart LR
    subgraph clients["MCP Clients"]
        claude["Claude / Claude Code"]
        codex["OpenAI Codex"]
        inspector["MCP Inspector"]
    end

    subgraph gateway["MCPR Gateway  (Fastify + TypeScript)"]
        direction TB
        auth["🔐 Auth & RBAC\nBearer token → role → namespace"]
        modes["⚙️ Operating Modes\nCode · Compat · Default"]
        registry["📡 Server Registry\n& Health Monitor"]
        sessions["💾 Session Store"]
    end

    subgraph downstream["Downstream MCP Servers"]
        s1["Server A\n(stdio)"]
        s2["Server B\n(HTTP)"]
        s3["Server C\n(SSE)"]
    end

    adminui["🖥️ Admin WebUI\n/ui/"]
    subgraph webui["Admin Panels"]
        direction TB
        wp1["📊 Dashboard · 🔌 Servers · 🛠️ Tools"]
        wp2["💬 Sessions · 🔑 Access Control"]
        wp3["📋 Audit · ⚙️ Config & History · 🌐 Namespaces"]
    end
    sqlite[("🗄️ SQLite\nSessions · Audit · Config")]

    clients -->|"Bearer token\nPOST /mcp/:namespace"| auth
    auth --> modes
    modes --> registry
    registry --> s1 & s2 & s3
    sessions  sqlite
    gateway --- sessions
    adminui -->|"admin_session cookie\n/admin/*"| gateway
    adminui --- webui

---

⚡ Quick Setup

1. Install and configure

node --version   # must be 24.x LTS
git clone https://github.com/TempoNaoTenho/mcpr-gateway.git && cd mcpr-gateway
cp .env.example .env
npm ci
npm run build
npm start                 # built UI + MCP gateway on PORT

Before running npm start, replace change-me-* in .env with your own secure values.

Use Node 24 LTS. Run: npm ci, npm run build, then npm start (serves UI + gateway on same port). The build step auto-rebuilds isolated-vm/better-sqlite3 if needed.

.env is optional; environment variables take priority. The app exits if required security settings are missing or default. Native module fixes and test preflights are automatic for all scripts. Use npm run setup if you want help editing .env or generating bootstrap.json.

App runs at http://127.0.0.1:3000 (UI at /ui/). For development, use npm run dev (UI on PORT, API on PORT+1).

Minimum security variables

| Variable | Purpose | Required | |----------------------------------|-------------------------------------------------|-----------------------------------------| | ADMIN_TOKEN | Enables authentication on all /admin/* routes | Yes | | GATEWAY_ADMIN_USER | Username typed at the admin login | Yes for production | | GATEWAY_ADMIN_PASSWORD | Password typed at the admin login | Yes | | DOWNSTREAM_AUTH_ENCRYPTION_KEY | AES-256 key for downstream credentials at rest | Required for managed downstream secrets |

Without ADMIN_TOKEN, the admin panel is unprotected — anyone with network access can reach it. The default npm start path now fails fast instead of silently accepting missing or placeholder values, whether they come from .env or platform-injected environment variables.

# Export variables in your shell (CI/CD), or pass an env file explicitly:
docker compose --env-file .env -f docker/docker-compose.yml up --build

The compose file reads ADMIN_TOKEN, GATEWAY_ADMIN_PASSWORD, and DOWNSTREAM_AUTH_ENCRYPTION_KEY for interpolation from the shell/CI environment or an explicit env file such as --env-file .env. Runtime HOST inside the container is always 0.0.0.0 in this file — your dev .env value HOST=127.0.0.1 does not apply there. If ADMIN_TOKEN or GATEWAY_ADMIN_PASSWORD are missing, docker compose up fails immediately with a clear error before the container starts. If DOWNSTREAM_AUTH_ENCRYPTION_KEY is malformed, the container exits on startup.

If the UI or /health fails from the browser, try http://127.0.0.1:3000 instead of http://localhost:3000 (some systems resolve localhost to IPv6 first).

---

🔌 Connect an MCP client

Issue a client Bearer token from the Access Control panel at /ui/access (or add it to auth.staticKeys in bootstrap.json), then configure your client.

> 💡 Without bootstrap.json, the built-in namespace is default. Replace it only when you configure custom namespaces.

---

🛠️ Development Tools

Claude Code (~/.claude/settings.json)

{
  "mcpServers": {
    "mcpr-gateway": {
      "type": "http",
      "url": "http://localhost:3000/mcp/",
      "headers": { "Authorization": "Bearer " }
    }
  }
}

OpenAI Codex (~/.codex/config.toml)

[mcp_servers.mcpr-gateway]
type = "http"
url  = "http://localhost:3000/mcp/"
bearer_token_env_var = "MCPR_GATEWAY_TOKEN"

export MCPR_GATEWAY_TOKEN=

OpenCode

# Add via CLI or config file
opencode mcp add mcpr-gateway \
  --url "http://localhost:3000/mcp/" \
  --token ""

---

🌐 Web Clients

Claude Web (claude.ai)

1. Go to Settings → Integrations → MCP Servers
2. Click Add Integration
3. Fill the form:

• Name: MCPR Gateway
• URL: http://localhost:3000/mcp/

1. Save and enable the integration

ChatGPT Web (chat.openai.com)

1. Go to Settings → Plugins → MCP Servers (or search "MCP" in plugin store)
2. Add a new MCP server
3. Configure:

• Server URL: http://localhost:3000/mcp/

1. Save and activate

Both supports OAuth.

---

🔗 Any HTTP MCP Client

Send Authorization: Bearer on every request. After initialize, include the Mcp-Session-Id header returned by the gateway.

---

🔍 Feature Details

🔐 Security

| Concern | Implementation | |------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Client auth | Bearer token per user/service, issued via Admin UI or auth.staticKeys in bootstrap | | Admin protection | ADMIN_TOKEN enables login; GATEWAY_ADMIN_USER / GATEWAY_ADMIN_PASSWORD are the credentials; in NODE_ENV=production with no ADMIN_TOKEN, admin routes are not mounted | | Downstream credentials | AES-encrypted in SQLite when DOWNSTREAM_AUTH_ENCRYPTION_KEY is set | | HTTP security headers | @fastify/helmet applied to all responses | | CORS | Restricted to loopback origins (localhost, 127.0.0.1, ::1) for MCP endpoints |

🌐 Sessions & Transport

| Topic | Detail | |----------------|----------------------------------------------------------------------------------| | Persistence | SQLite (default) or in-memory (SESSION_BACKEND=memory) | | TTL | 30 min default (session.ttlSeconds = 1800), automatic cleanup | | Transport | HTTP-Streamable: GET /mcp/:namespace (SSE) + POST /mcp/:namespace (JSON-RPC) | | Session header | Mcp-Session-Id required on all requests after initialize | | Admin ops | Query, inspect, and revoke sessions via /ui/sessions or GET /admin/sessions |

🔌 Downstream Servers

| Topic | Detail | |-------------------|-------------------------------------------------------------------------| | Transports | stdio and http / streamable-HTTP | | Auth options | none,

…

Source & license

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

• Author: tempont
• Source: tempont/mcpr-gateway
• License: MIT
• Homepage: https://mcpr-gateway.onrender.com

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