Skip to main content

Overview

When Bifrost acts as an MCP Gateway, external MCP clients connect to its /mcp endpoint. This page covers how those inbound clients authenticate to Bifrost. There are two ways a client can present itself:
  • Header credentials — a virtual key, API key, or session token sent as a request header. Simple to script, ideal for backend and machine-to-machine use.
  • OAuth 2.1 — Bifrost acts as an OAuth authorization server, and the client connects through a browser consent flow, receiving a short-lived JWT. Ideal for interactive clients like Claude Desktop, Claude Code, or Cursor, where pasting a raw key into client config is awkward.
This page is about authenticating clients to Bifrost. For how Bifrost authenticates to upstream MCP servers it connects to, see the outbound Authentication guides instead — that’s the opposite direction.

Authentication Modes

A single setting, mcp_server_auth_mode, controls which credential types /mcp accepts:
  • headers — /mcp accepts header credentials only. The OAuth surface is not served: the .well-known discovery endpoints and the issuance endpoints (/oauth2/register, /oauth2/authorize, /oauth2/token) all return 404.
  • both — /mcp accepts header credentials and Bifrost-issued JWTs. Discovery is served so OAuth clients can connect.
  • oauth — /mcp accepts Bifrost-issued JWTs only; header credentials are rejected.
A request must carry exactly one credential type. If an OAuth access token and a header credential (x-bf-vk, X-Api-Key, or a Bearer VK) arrive on the same request, Bifrost rejects it with a conflicting credentials error — even in both mode. both means either credential is accepted, not both at once.
In oauth mode, clients that authenticate with a virtual key or API key header can no longer reach /mcp. Use both if you need header and OAuth clients to coexist.
In oauth mode, /mcp accepts Bifrost-issued JWTs only, so callers cannot send their own identity-provider token to Token Exchange (token_exchange) MCP clients through it. On Enterprise with SSO, callers who connect in user mode still reach them: Bifrost exchanges the access token from that user’s Bifrost sign-in. Virtual-key and session-mode tokens carry nothing to exchange. Use headers or both if callers send their identity-provider token directly.

How the OAuth Connect Flow Works

When mcp_server_auth_mode is both or oauth, Bifrost is a full OAuth 2.1 authorization server for the /mcp resource. A client that doesn’t yet have a token discovers the server, identifies itself with a client metadata document or by registering, and walks the user through a browser consent step. The flow follows current OAuth standards so off-the-shelf MCP clients work without custom code:
  • Protected resource metadata (RFC 9728) — the 401 response points clients at the discovery documents.
  • Client ID Metadata Documents — a client identifies itself with the address of a document it publishes; nothing is registered with Bifrost.
  • Dynamic Client Registration (RFC 7591) — clients self-register; no manual client setup.
  • PKCE (S256) — public clients authenticate without a shared secret.
  • Resource indicators (RFC 8707) — tokens are bound to the /mcp resource via the aud claim.

Client ID Metadata Documents

An MCP client can use the HTTPS address of a metadata document it publishes as its client ID, instead of registering with Bifrost. Bifrost reads the document during sign-in and advertises support in its discovery metadata, so clients that support documents use them automatically. There is nothing to configure. Bifrost accepts a document when:
  • its address uses HTTPS, has a path, and resolves to a public address. Private and loopback addresses are refused;
  • it is served directly from that address, without a redirect, and is no larger than 64 KB;
  • its client_id is exactly that address, and it lists a client name and at least one redirect URI;
  • the client is public, with no client secret;
  • its redirect URIs pass the same checks as a registered client’s. Remote callbacks must be listed in allowed_redirect_uris.
Bifrost caches a document for as long as its HTTP cache headers allow, between 1 minute and 24 hours, and for 1 hour when they say nothing. A document that could not be used is retried after 1 minute. Clients that registered before this support keep their registration and existing grants.
During the consent step, Bifrost shows the user how they can identify themselves. The page header names the connecting client — for example “Claude Code wants to connect” — and offers the modes available for your deployment: MCP OAuth consent page with identity options Check the application before you continue. The page also shows:
  • Where the sign-in returns to: the host and full address of the client’s callback.
  • Who published the client: for a client using a metadata document, Published by names the host of its document. The name in the page header comes from that document.
  • A local-only warning: when a client’s callback is only on your own computer, the page warns that its name cannot be verified, since any app running locally could use it.
MCP OAuth consent page showing the document host and callback
  • Virtual key carries the same governance (budgets, rate limits, tool scoping) the key already has — the JWT simply represents that key.
  • Session is an anonymous identity for development and open deployments. Because the grant itself carries no identity, Bifrost only lets a signed-in person hand it out: the consent page offers session mode when the browser has a valid dashboard session (or an SSO user), and PUT /api/oauth2/consent/flows/{id} answers 401 to a session-mode submit that arrives with only the consent link’s token. Running with dashboard auth disabled does not count as being signed in. Session mode is unavailable altogether once enforce_auth_on_inference is on.
  • User binds the grant to the authenticated person, so per-user upstream tool authorizations unify under one identity. It is also the only consent mode that reaches Token Exchange servers, which exchange the access token from the user’s Bifrost sign-in. It needs the user’s own sign-in: a request authenticated with a management API key cannot complete it.
User mode requires SSO/SCIM (enterprise). When no identity provider is configured, the consent page offers virtual key mode, plus session mode when the consenting person is signed in to the dashboard.

Configuration

  1. When using both or oauth, first open Config → Security and set the OAuth Issuer URL (required, since otherwise the issuer would be derived from the unauthenticated request Host header). It lives under Security because Cross App Access uses the same issuer. Click Save Changes.
  2. Open Config and go to the MCP settings.
  3. Set MCP Server Auth Mode to headers, both, or oauth.
  4. When using both or oauth, set the Authorization Code and Access Token lifetimes. The issuer is shown read-only, with a link back to Security.
  5. Click Save. MCP server auth mode and OAuth server settings
oauth2_server_config only applies when mcp_server_auth_mode is both or oauth. The RSA signing key used for JWTs is generated automatically the first time it’s needed — no setup required. It is persisted to the database, so it survives restarts and is shared across all replicas; previously issued tokens stay valid after a restart.
issuer_url is required whenever mcp_server_auth_mode is both or oauth, for single-host deployments too: saving a config that turns on discovery without one is rejected. Left to a per-request fallback, the issuer identity would be derived from the unauthenticated request Host header on the always-public /.well-known/ endpoints, so the issuer, token_endpoint, and jwks_uri that MCP clients trust would depend on whatever Host value a request carried.

Connecting a Client

With both or oauth enabled, point the MCP client at Bifrost’s /mcp URL — for example https://bifrost.example.com/mcp. No key needs to be pasted into the client config.
  1. The client hits /mcp, gets a 401, and discovers the authorization server.
  2. It registers itself and opens a browser to the consent page.
  3. The user chooses an identity (virtual key, session, or user).
  4. The client receives a token and connects; aggregated tools become available.
When the access token expires, the client uses its refresh token to obtain a new one silently — the browser step happens only once.

Managing Grants

Each completed OAuth connection is a grant — a refresh-token lineage Bifrost issued to a client. The OAuth Grants page lists them: the client, the bound identity, when the grant was created, and when it was last used, with a Revoke action. OAuth Grants table with revoke action Revoking a grant stops its refresh token from rotating immediately, so the client can no longer renew access. The page is backed by GET /api/oauth2/sessions (list active grants, filtered and paginated) and DELETE /api/oauth2/sessions/{id} (revoke a grant), so the same operations are scriptable.
A revoked grant’s current access token is a short-lived JWT that keeps working on /mcp until it expires (up to access_token_ttl, default 600 seconds). After that the client is fully cut off and must reconnect through the consent flow.This is deliberate: a holder of the virtual key or user credentials can always start a new authorized session, so invalidating the access token mid-flight adds little security while costing a per-request lookup. Lower access_token_ttl for a tighter window.
The OAuth Grants page lists credentials Bifrost issued to clients for inbound /mcp access. This is distinct from MCP Sessions, which tracks per-user credentials Bifrost holds for upstream MCP servers.

Token Lifetime & Revocation

  • Access tokens are JWTs valid for access_token_ttl (default 600s). On every /mcp request Bifrost validates the JWT (signature, expiry, issuer, and audience) and confirms the bound identity still exists: a user-mode token is rejected with 401 when the user is gone, and a vk-mode token resolves to its key, which governance refuses with 403 when it is inactive or expired, the same way the inference endpoints refuse it. The identity check reads an in-memory cache, so in the common case it adds no database round-trip (vk-mode falls back to a single store lookup only on a cache miss).
  • Refresh tokens rotate on each use and have no fixed expiry. A token is invalidated by rotation, by the bound virtual key becoming inactive, expiring or being deleted, by the bound user becoming inactive or deleted, or by an explicit revoke. An expired virtual key also cannot consent to a new grant.
  • Authorization codes are single-use. Exchanging a code a second time returns 400 invalid_grant and revokes the refresh token its first exchange issued, since a replayed code may have been stolen. The access token from that first exchange keeps working until it expires.
  • Rotating a virtual key (POST /api/governance/virtual-keys/{id}/rotate, bulk rotation, or a scheduled rotation) revokes every vk-mode grant that key minted: their refresh tokens return invalid_grant on the next refresh, and authorization codes consented to with the key but not yet exchanged can no longer be exchanged. The revocation and the new key value are saved together, so a rotation that fails changes neither. Clients connected through the key must complete the OAuth flow again with the new value. The rotation cooldown keeps the old key value working for direct use; it does not keep grants alive.
  • An explicit revoke marks the grant’s refresh-token row revoked, so renewals stop immediately — but it does not remove the bound identity, so the identity check still passes and the already-issued access token keeps working until it expires. Lower access_token_ttl to shorten that window.
  • Deleting the bound virtual key or user is stronger than revoking a grant: it revokes the grant immediately and the identity check rejects the grant’s already-issued access token on its next /mcp request, instead of letting it live out its TTL.
  • Enabling disable_vk_identity (require identity-provider login) cuts off all virtual-key–mode grants immediately — they are rejected at /mcp and denied on refresh — so those clients must re-authenticate as a user. Only applies in oauth mode with an identity provider configured.
  • Enabling enforce_auth_on_inference blocks session-mode (anonymous) tokens at /mcp, but does not delete or invalidate their grants — the grants remain in the database and become valid again if enforcement is later disabled. To remove a session-mode grant permanently, revoke it on the OAuth Grants page.

Discovery Endpoints

When discovery is enabled (both or oauth), Bifrost serves the standard documents MCP clients fetch automatically: In headers mode these endpoints return 404, as do the issuance endpoints /oauth2/register, /oauth2/authorize and /oauth2/token. Discovery responses are sent with Cache-Control: no-store so a shared cache or CDN in front of Bifrost never serves a stored copy. Client registration bounds its free-text fields: client_name up to 2048 bytes, scope up to 4096 bytes, and at most 32 redirect_uris of up to 2048 bytes each. The authorize request bounds state to 8192 bytes. Anything larger is refused with 400 before any state is stored.

Browser Clients

Browser-based MCP clients send an Origin header, and Bifrost checks it on every request to the MCP gateway. This stops a web page you happen to visit from reaching a gateway on your network or machine. Clients that send no Origin, such as CLI, desktop and server-side clients, are not affected.

Troubleshooting

Discovery returns 404

Symptom: A client can’t discover the authorization server; .well-known endpoints return 404. Cause: mcp_server_auth_mode is headers, so the OAuth surface is disabled. Fix: Set the mode to both or oauth. Cause: Bifrost is served under a path prefix and the proxy only forwards that prefix. For an issuer such as https://bifrost.example.com/bifrost, clients fetch https://bifrost.example.com/.well-known/oauth-authorization-server/bifrost at the host root. Fix: Forward /.well-known/ to Bifrost too; see Serving under a path prefix.

Header credential rejected on /mcp

Symptom: A virtual key or API key that worked before now gets a 401. Cause: mcp_server_auth_mode is oauth, which accepts JWTs only. Fix: Use both to accept header credentials alongside OAuth.

Key refused with 403 on /mcp

Symptom: A request with a valid virtual key gets 403 with virtual key is inactive or virtual key has expired. Cause: The key authenticated, but governance refuses it, exactly as it would on an inference request. Fix: Reactivate the key or extend its expiry; the change applies on the next /mcp request.

Browser app refused with 403 on /mcp

Symptom: A browser-based MCP client on another origin gets 403 saying the origin is refused, while the same server works from a CLI or desktop client. Cause: Browser requests to the MCP gateway must come from an allowed origin. While inference auth is off (enforce_auth_on_inference: false), only localhost origins and origins listed in allowed_origins by name or pattern are allowed; the "*" entry does not count. With inference auth on, allowed_origins applies as configured. Fix: List the app’s origin in allowed_origins (for example https://inspector.example.com or https://*.example.com). If allowed_origins already contains "*", turning on inference auth also works. Clients that send no Origin header are never affected.

Conflicting credentials on /mcp

Symptom: conflicting credentials: an OAuth token and a virtual key header were both provided. Cause: The client completed an OAuth flow but is also configured with a VK header, so both arrive on one request. Claude Code does this in both mode when the VK is set under x-bf-vk / X-Api-Key instead of Authorization. Fix: Send only one credential — remove the VK header, or configure it as Authorization: Bearer <vk> so the client uses header auth and skips OAuth. Symptom: Opening the consent link sends you to Bifrost’s sign-in page instead of showing the identity options. Cause: Authorizing without a Bifrost account is turned off. mcp_enable_temp_token_auth is off by default, so a signed-in account is the only way through. Fix: Sign in — you’ll be brought back to the consent page to choose an identity. To let people authorize without a Bifrost account, turn the toggle on. Symptom: The consent page offers only Virtual key, or submitting Session returns 401 with session mode requires an authenticated consenting user. Cause: Session mode grants an anonymous identity, so only a signed-in person can hand it out. The consent link’s own token is not a sign-in, and neither is running with dashboard auth disabled. Fix: Sign in to the Bifrost dashboard in the same browser and reopen the consent link, or authorize with a virtual key instead. Symptom: The consent page shows “This link is no longer valid”. Cause: Consent links are one-time and short-lived. This one has expired, was already used, or was altered. Fix: Restart the connection from your MCP client to get a fresh link.

Client keeps re-opening the browser

Symptom: The consent flow runs on every connection. Cause: The client isn’t persisting its tokens, or its refresh token was revoked (refreshing then returns 400 invalid_grant). Fix: Confirm the client stores its credentials; check the OAuth Grants page to see whether the grant was revoked. To see why, set the log level to debug and filter the logs on [oauth2-token]. Each sign-in, refresh, rejection and revocation is logged with its client, grant and reason. Tokens and codes are never written to the logs. A grant revoked with reason=refresh_replay means a refresh token that was already revoked was used again. The most common cause is a client that refreshed but did not save the new token, for example Codex before 0.164. A token revoked on the OAuth Grants page or with its virtual key also logs this when it is next used; the earlier family.revoked line for that grant shows the original reason.

Token rejected after issuer change

Symptom: Previously issued tokens fail validation after changing issuer_url, and refreshing them returns 400 invalid_grant. Cause: The iss claim in existing tokens no longer matches the configured issuer, and their grants are bound to the /mcp resource at the old address, so they cannot refresh. Fix: Clients reconnect, authorizing again, to obtain tokens with the new issuer.

Save rejected with “issuer_url must be set”

Symptom: Switching mcp_server_auth_mode to both or oauth is rejected with a 400 mentioning issuer_url. Cause: issuer_url is required whenever discovery is enabled; see the warning above. Fix: Set oauth2_server_config.issuer_url to Bifrost’s stable public URL in the same request.

Next Steps

  • Bifrost as an MCP Gateway — Expose aggregated tools to external MCP clients.
  • MCP Sessions — Inspect and manage per-user credentials for upstream servers.
  • Virtual Keys — Govern budgets, rate limits, and tool scope for the identities behind grants.

Callback destinations

By default, remote OAuth clients must have their exact callback URI configured in client.oauth2_server_config.allowed_redirect_uris before registration or authorization, unless the list contains the "*" wildcard described below. For example, add "https://app.example.com/oauth/callback" (or "https://www.cursor.com/agents/mcp/oauth/callback" for Cursor’s web agents). Existing registrations and pending flows are checked against the current list. URI credentials, fragments, missing hosts, and unsafe schemes are rejected. The consent page shows the client name and exact callback destination before you grant access. Only approve applications and destinations you recognize. To accept every remote https callback without listing each one, set the list to ["*"]. Only a bare "*" is a wildcard: patterns such as "https://*.example.com/cb" are rejected. The shape checks above still apply, so plain http callbacks to non-loopback hosts, credentials, and fragments are still refused. Custom-scheme callbacks (other than the built-in cursor://anysphere.cursor-mcp) are not covered by "*" and still need an exact entry.
With "*", any client can register itself with a callback on any host. The consent page is then the only protection against a phishing client that sends the authorization code to an attacker’s server. Prefer listing exact callbacks, and use "*" only when every user who can reach the consent page is trusted to check the destination it shows.