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.

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.

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