Connections, States & Lifecycles

​

Two independent axes

1. Who authenticates — server-level (none, headers, oauth) vs. per-user (per_user_headers, per_user_oauth, token_exchange). Covered in MCP Authentication.
2. How the connection is held — sticky (one persistent upstream connection, reused for every tool call) vs. per-call (a fresh connection dialed per tool call, closed immediately after). This page’s focus.

​

Connection states

​

Why a server is in a state

"state": "unstable",
"last_failure": {
  "stage": "list_tools",
  "message": "context deadline exceeded",
  "at": "2026-09-03T10:41:12Z",
  "since": "2026-09-03T10:32:04Z"
}

• It is the serving instance’s own record. It describes what this Bifrost instance last ran into, never the outcome of real tool calls made through the server.
• It clears on the first passing check. A healthy server never carries a stale reason; the record is gone the moment the state flips back.
• It can lag a credential-driven state. A needs_reauth that comes from a credential row dying in the store (a rejected refresh, a rotation) shows no reason until the server’s next scheduled check actually hits the dead credential, at which point the provider’s rejection is recorded. Shared-OAuth servers hit it on their next reconnect; per-user servers on their next tool-discovery check.
• A single failed check is enough. There is no consecutive-failure counter across checks. Each check already retries with backoff internally (three retries per operation), and that budget is what absorbs an ordinary blip. A check that exhausts it marks the server unstable and records why.
• Reasons are logged once per transition. The state-change log line at INFO carries the stage and message. Individual failed checks during an outage log at DEBUG only, so a long outage does not flood the log.

​

Lifecycle: sticky server-level (needs_session_stickiness: true, or sse/stdio)

• Connect happens once at AddClient (boot, or client creation) and again on every reconnect. Reconnects are make-before-break: the old connection keeps serving until the new one is ready, so token rotation never causes downtime.
• unstable is purely informational — a network blip doesn’t stop tool calls, and the client self-heals on the next successful check with no human involvement.
• needs_reauth is a hard gate specifically for server-level clients: the periodic checker stops retrying entirely (retrying against a known-dead credential is pointless), and tool calls are refused outright rather than attempted. Recovery is POST /api/mcp/client/{id}/reauthorize (also covers oauth; headers/none credentials don’t expire the same way, so this state is effectively OAuth-only in practice for server-level clients).
• Every discovered tool list — from the initial connect and from every periodic refresh — persists to the DB, gated on the tool list actually having changed (no write on an unchanged tick), so a restart doesn’t lose anything a running instance had already discovered.

​

Lifecycle: per-call server-level (needs_session_stickiness: false/omitted, http only)

• No persistent connection ever exists — every tool call dials fresh and closes immediately after. There’s nothing to reconnect (POST /reconnect returns 400 for this mode), and needs_reauth doesn’t apply here (there’s no single connection credential to die — headers/none/oauth per-call clients cycle through a fresh credential resolution on every call).
• AddClient runs a synchronous first discovery pass if no tools are already known (e.g. from a prior successful discovery persisted to the DB) — without this, a client would sit at healthy/0-tools until the periodic checker’s slow first tick, which can be minutes away for an already-healthy client.
• The periodic checker’s ongoing ticks are the only thing revisiting this client afterward — same content-hash gating as the sticky case, so an unchanged tool list doesn’t cause a write.

​

Lifecycle: per-user (per_user_oauth, per_user_headers, token_exchange)

1. Bootstrap. An admin submits a sample credential once (POST /verify-headers, POST /verify-exchange, or the complete-oauth callback for per_user_oauth). This is the one and only time a live admin session is required. As a side effect, that credential is retained server-side.
2. Ongoing refresh. AddClient’s own synchronous first-discovery pass and the periodic checker’s ongoing ticks both reuse the retained credential (never a fresh admin login) to keep the tool list current — same content-hash-gated persistence as server-level clients.
3. Repair. If the retained credential itself dies (OAuth refresh fails, or a header schema change flips it to stale), it projects as needs_reauth in the client list — but only when the underlying runtime reading is healthy or unstable; a client sitting in pending_verification or disabled keeps that state instead. Repair is auth-type-specific: POST /verify-headers (headers), POST /verify-exchange (token exchange), or reauthorize → complete-oauth (per_user_oauth).

1. A caller’s request carries an identity (VK, signed-in user, or session ID — see Identity modes).
2. Bifrost looks up that identity’s own stored credential for this MCP client. Found and active → the call proceeds transparently. Missing or stale → an mcp_auth_required payload with an auth URL is returned instead of executing the tool.
3. The caller completes their own auth (OAuth consent, or submitting header values) once; every later call resolves transparently from then on.

​

Recovery endpoints by combination

​

Next Steps

• Session Stickiness — how to set needs_session_stickiness
• MCP Authentication — which auth type to pick
• MCP Gateway — reconnection behavior, dynamic tool discovery, health monitoring