Architecture

The complete stack has five application services and two stateful dependencies. Each external interface accepts a different credential class and has a deliberately bounded job.

Browser
  → Next.js dashboard
  → management API
  → Postgres

App or agent + Gate Token
  → request gateway
  → policy + budget + active credential
  → provider adapter
  → upstream API

MCP client + MCP session token
  → MCP server
  → read tools or access request
  → Postgres

Worker
  → expiration, rollups, alerts, reconciliation
  → Postgres

Dashboard

A Next.js interface for setup, Provider Vault, Gate Tokens, policies, requests, usage, budgets, audit, and settings.

Management API

An authenticated service for sessions and administrative operations. It performs role checks and writes audit events.

Gateway

The hot path for provider traffic: token verification, route normalization, policy, rates, budget reservation, credential unlock, proxying, and events.

MCP server

A JSON-RPC 2.0 streamable HTTP surface for actor-bound read tools and structured token requests. It never receives the provider master key.

Worker

Runs token and request expiry, abandoned reservation cleanup, usage rollups, budget alerts, and supported provider cost reconciliation.

1. Assign a request identifier and extract the bearer Gate Token.
2. Parse its kind, public identifier, and secret; load the candidate by public identifier.
3. Verify the peppered token HMAC in constant time, then check status and expiration.
4. Load and validate the attached policy. A missing or malformed policy denies the request.
5. Resolve the provider from the native route, provider header, model prefix, or one unambiguous allowed provider.
6. Ask the adapter to normalize a known method and path to a capability. Unknown paths deny.
7. Evaluate allow and deny rules, required metadata, environment, and model or endpoint boundaries.
8. Apply configured request rates and reserve a conservative estimate against applicable budgets.
9. Load and decrypt the active upstream credential in gateway memory.
10. Build provider-native authentication, forward the request, and pass streaming responses through.
11. Extract available usage, settle reservations, and write the usage event.

authenticated admin
  → create provider integration
  → submit candidate credential
  → management API encrypts before storage
  → test candidate through implemented adapter
  → activate candidate
  → previous active credential becomes retiring
  → revoke old credential after verification

The management API needs the encryption key to accept and test provider credentials. The gateway needs it to proxy. The worker needs it only for supported reconciliation jobs. The dashboard browser and MCP service do not receive it.

Browser session

Authenticates the management API. It is not accepted as provider-gateway or MCP authorization.

Gate Token

Authenticates one policy-bound provider identity. It cannot call management endpoints or authenticate directly to a provider.

MCP session token

Authenticates one known actor and permission level to MCP tools. It does not reveal provider credentials.

Provider credential

Accepted by an upstream provider and therefore the highest-value integration secret. It remains behind the gateway.

Application secrets

Sign browser sessions, verify Gate Tokens, and encrypt stored credentials or one-time MCP collections. Keep each purpose separate.

The repository’s full Docker Compose profile builds and starts the application services with Postgres and Redis. Published interfaces bind to loopback by default, while the management API and worker remain internal to the Compose network.

docker compose --profile full up -d --build