OptiGate — Self-Hosted MCP Gateway with Token-Sparing Tool Retrieval

Your optimized, self-hosted MCP gateway. One endpoint for all your MCP servers — with token-sparing tool retrieval built in. Optional: with decision-model based reranking.

📚 Documentation: https://ninjaede.github.io/optigate

OptiGate is a self-hosted MCP (Model Context Protocol) server registry and gateway for LLM tools. It manages your MCP servers (registration, health, approval workflow, audit, per‑tenant credential isolation) and exposes them to any MCP client — Claude, ChatGPT, Hermes, coding agents — 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 LLM tools don't fit into a context window. OptiGate's token-sparing retrieval returns the top‑k relevant tools per query (~200–800 tokens regardless of registry size), cutting LLM context usage and token costs.

• 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 an MCP gateway, every client needs every server registered individually. With OptiGate, one entry covers them all.

• Cloud lock‑in — OptiGate is fully self-hosted (Docker Compose, MIT licensed): your tool traffic, credentials, and audit data stay on your own infrastructure — homelab, VPS, or on‑prem.

Related MCP server: Smart MCP Proxy

Who is it for

• AI agent builders connecting Claude, GPT, or open‑weights models to self-hosted LLM tools without blowing the context window.

• Homelabs & small teams running private MCP servers (files, media, smart home, scrapers) behind one governed MCP gateway.

• Platform teams needing multi‑tenant tool access with audit trails, approval gates, and per‑tenant credentials.

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

OptiGate's token-sparing retrieval keeps LLM context usage flat:

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.

Decision‑model reranking (mode="decision")

Lexical search is fast but misses paraphrases ("download web page" vs. a tool named http_fetch). Opt‑in per request, search_tools can hand its candidate pool to a decision model that reranks semantically — and may honestly report "no matching tool" instead of guessing:

// tools/call search_tools
{ "query": "download web page", "k": 5, "mode": "decision" }

Two backends are supported through one provider‑agnostic interface:

Behavioral guarantees:

• Reranker, never retriever — lexical search builds the candidate pool (decisionModel.candidatePool, default 20); the model only re‑orders it.

• "None" is a first‑class answer — with none the response is empty plus a confidence score, so agents can rephrase instead of calling the wrong tool.

• Fail‑safe — timeout, error, or invalid model output falls back to lexical results; the second content block always reports {used, provider, fallback, latencyMs, …}.

• Injection‑safe — the model selects only from supplied candidate keys (re‑validated server‑side); tool descriptions are treated as untrusted data and the model never executes anything (execute_tool is unchanged).

# .env — OpenRouter (key at https://openrouter.ai/settings/keys)
DECISION_MODEL_ENABLED=true
DECISION_MODEL_PROVIDER=jev
DECISION_MODEL_BASE_URL=https://openrouter.ai/api/v1
DECISION_MODEL_MODEL=typesafe/jev-1.13
DECISION_MODEL_API_KEY=<key>
DECISION_MODEL_TIMEOUT_MS=3000
DECISION_MODEL_CANDIDATE_POOL=20

The API key can also be stored at runtime in the UI's Settings view (decisionModel.apiKey): it is AES‑256‑GCM encrypted at rest and never returned in plaintext. Precedence for all decisionModel.* settings: database value > environment variable > built‑in default.

Forcing reranking server-side: by default the LLM opts in per call via mode="decision". Set decisionModel.forceWhenConfigured=true (DECISION_MODEL_FORCE=true) and every search_tools call — gateway and REST alike — is reranked once a model is configured, no matter which mode was requested. Forced responses carry "forced": true in the decision metadata, so callers can always tell what happened. Note the cost implication: every search then pays model tokens + latency.

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

MCP gateway · Model Context Protocol registry · token-sparing tool retrieval · self-hosted LLM tools · LLM tool router · AI agent tooling · reduce LLM context usage and token costs