OptiGate

Your optimized MCP gateway. One endpoint for all your MCP servers — with token-sparing tool retrieval built in.

OptiGate is an MCP server registry and gateway. It manages your MCP servers (registration, health, approval workflow, audit, per‑tenant credential isolation) and exposes them to any MCP client through a single Streamable HTTP endpoint. Instead of loading hundreds of tool schemas into the LLM context, clients query two meta‑tools and retrieve only the tools they actually need.

MCP Client ──▶ POST /mcp ──▶ OptiGate ──▶ managed MCP servers (HTTP/SSE/stdio)
                search_tools + execute_tool only

Why

• Token explosion — dozens of MCP servers with hundreds of tools don't fit into a context window. OptiGate's retrieval returns the top‑k relevant tools per query (~200–800 tokens regardless of registry size).

• No governance — who may register which server? Which tool was called when, by whom, with what arguments? OptiGate ships roles, approval workflow, full audit log, and per‑tenant credential isolation.

• N+1 client configuration — without a gateway, every client needs every server registered individually. With OptiGate, one entry covers them all.

Related MCP server: Smart MCP Proxy

Features

Admin UI

Quick Start (Docker Compose)

The fastest way to run OptiGate is the bundled Compose stack — no local Node or Postgres required:

# Copy the example env and adjust
cp .env.example .env

# Development stack: Postgres + API (hot reload via tsx watch) + Web UI (Vite HMR)
docker compose -f docker-compose.dev.yml up

# UI   → http://localhost:3030
# API  → http://localhost:8100/health
# MCP  → http://localhost:8100/mcp

For production:

# Set these in your environment or .env:
#   AUTH_MODE=keycloak   KEYCLOAK_URL=...   KEYCLOAK_REALM=...
#   SECRET_ENCRYPTION_KEY=...   POSTGRES_PASSWORD=...
docker compose up --build -d

# UI  : http://localhost:8080  (nginx, /api proxied to the server)
# API : http://localhost:8100  (Keycloak JWT required)

Data lives in the pgdata volume; the schema is created idempotently on boot.

Run without Docker

Both services are plain Node projects:

cd server && npm i && AUTH_MODE=dev npm run dev    # API on :8100
cd web    && npm i && npm run dev                  # UI on :5173 (proxies /api)

Without DATABASE_URL the server runs on an in‑memory repository — handy for trying it out, but data is lost on restart.

Connecting MCP clients

Register OptiGate once in any MCP client:

{
  "mcpServers": {
    "optigate": {
      "type": "http",
      "url": "http://localhost:8100/mcp",
      "headers": { "x-dev-user": "alice" }
    }
  }
}

That's it — search_tools and execute_tool now give the client access to every visible registry server.

For machine clients (agents, CI) without Keycloak, admins can issue gateway API keys (POST /api/api-keys — admin: own tenant only, superadmin: any tenant; also manageable in the UI's API-Keys view). Keys are gateway-only (/mcp, never /api), bound to a user/role/tenant, and shown in plaintext exactly once. Note: on the gateway, visibility only distinguishes superadmin keys (platform-wide) from the rest (tenant-scoped) — an admin key sees what a user key of the same tenant sees:

{
  "mcpServers": {
    "optigate": {
      "type": "http",
      "url": "http://localhost:8100/mcp",
      "headers": { "x-api-key": "og_..." }
    }
  }
}

How the token saving works

1. search_tools("chart", k=5) → lexically scored tool cards (name, description, input schema) across all indexed servers.

2. execute_tool(server_id, tool_name, args) → routed through the connection pool; only healthy/degraded servers, scope‑checked for the caller, args validated against the cached schema.

Context cost stays constant no matter whether you manage 20 or 2,000 tools. The web UI has a Tool Search view that runs the exact same retrieval path, so you can inspect what agents would see.

Multi‑tenancy & user separation

Every request carries an authenticated identity (AuthContext) consisting of userId, role, and tenantId. This identity drives three policy checks:

1. Scope visibility (canView) — what may this user see?

All list/search/execute endpoints filter through this rule, so tenants cannot see each others' servers and private servers stay invisible to everyone else.

2. Registration rights (canRegister) — who may register what?

global scope requires superadmin; tenant and private require at least admin. The registering user's tenant/user id is stored on the server record and later used for visibility and ownership checks.

3. Approvals (canApprove) — supply‑chain gate

New servers start as pending_approval when APPROVAL_REQUIRED=true; only superadmins can approve them into healthy state (or re‑enable disabled ones). Unapproved servers never appear in any index or search result.

4. Credential bindings — shared servers, per‑tenant credentials

Shared HTTP/SSE servers are visible platform‑wide, but each tenant can bind its own credentials via the bindings API (PUT /api/servers/:id/bindings/:tenantId). The connection pool resolves the caller's tenant scope and injects the correct auth headers on every request. Bindings are persisted in Postgres (server_credential_bindings table).

In production the identity comes from a Keycloak JWT: userId from the sub claim, roles from realm_access/resource_access, and tenantId from the first organization claim.

Dev authentication (AUTH_MODE=dev) and its headers

Dev mode skips token verification and derives the identity from optional request headers — so you can test multi‑user behavior locally without an IdP:

Example — simulate a plain user of another tenant:

curl -H "x-dev-user: bob" -H "x-dev-role: user" -H "x-dev-tenant: other" \
  http://localhost:8100/api/servers

Without these headers every dev request acts as the default superadmin in dev-tenant.

Warning: dev headers grant full identity control by design. Never run AUTH_MODE=dev on a network‑exposed instance; use Keycloak or local mode instead.

Local authentication (AUTH_MODE=local)

Username/password login without any external IdP — for home labs and small teams that don't run Keycloak. Passwords are stored as scrypt hashes (local_users table in Postgres, in-memory otherwise); sessions are self-signed HS256 JWTs.

# .env
AUTH_MODE=local
LOCAL_JWT_SECRET=<min-32-chars-secret>
LOCAL_BOOTSTRAP_ADMIN_USER=admin
LOCAL_BOOTSTRAP_ADMIN_PASSWORD=<min-10-chars>

On first boot with an empty user table, the bootstrap superadmin is created once. Afterwards sign in via the UI login form (or POST /auth/login) and manage the rest in the Benutzer view (GET/POST/PATCH/DELETE /api/users) — admins manage their own tenant only, superadmins manage all. There is no self-signup. Deactivated users lose access immediately, including already-issued tokens (checked against the user record on every request).

# Login from the shell
curl -X POST http://localhost:8100/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"..."}'
# → {"token":"...","expiresAt":"...","user":{...}}

curl http://localhost:8100/api/servers \
  -H "Authorization: Bearer <token>"

Configuration

All of the above (plus registry.approvalRequired) are runtime‑tunable by admins in the UI's Settings view (GET/PUT/DELETE /api/settings) — precedence: database value > environment variable > built‑in default. Security‑sensitive keys (ssrf.*, registry.approvalRequired) require superadmin; every change is audited as setting.changed.

Security features

Development

cd server && npm test          # vitest (92+ tests)
cd server && npm run lint      # eslint
cd server && npm run typecheck # tsc --noEmit
cd server && npm run build     # tsc → dist/
cd web    && npm run build     # vite build

Stack

Node.js 24 · Fastify · TypeScript · official MCP SDK · Postgres 17 · React 18 · Vite · Tailwind CSS v4

License

MIT — free to use, modify, and distribute.

If this project saves you time or helps your agents work better, you can support it here:

☕ Buy me a coffee