Per-User Headers

​

Overview

​

How it works

1. Caller sends a request with an identity (header or SSO).
2. The LLM (or MCP client) asks to invoke a tool on a per_user_headers server.
3. Bifrost looks up an existing credential for (identity, mcp_client):
   • Found and active → Bifrost attaches the stored header values and calls upstream.
   • Missing, orphaned, or needs_update → Bifrost returns an mcp_auth_required payload with an inline submit_url. The tool is not executed.
4. The user opens the URL, sees a Bifrost form listing the required header names, fills in values, and submits.
5. Bifrost runs a one-time upstream verify with the submitted values, then stores the credential.
6. The next request executes the tool normally.

Authentication required for acme_api. Open this URL to submit the required headers: https://your-bifrost-domain.com/workspace/mcp-sessions/auth?flow=<flow-id>&kind=headers

​

Setup

• Web UI
• API
• config.json

1. Navigate to MCP Gateway in the sidebar
2. Click New MCP Server
3. Pick HTTP or SSE as the connection type, fill in the Connection URL
4. Set Auth Type to Per-User Headers
5. Fill in Required Headers — comma-separated list of header names each caller must supply (e.g. X-API-Key, X-Tenant-ID). Values are submitted per-user — never stored on this MCP config.
6. (Optional) Fill in Static Headers — admin-set headers that accompany every per-user request (e.g. a fixed tenant ID). These are visible to plugins; the per-user values aren’t.
7. Click Create — a dialog opens asking for sample header values to run a one-time verify
8. Enter sample values, click Run Test
9. On success, the MCP client is persisted with the discovered tool list

curl -X POST http://localhost:8080/api/mcp/client \
  -H "Content-Type: application/json" \
  -d '{
    "name": "acme_api",
    "connection_type": "http",
    "connection_string": "https://api.acme.example.com/mcp",
    "auth_type": "per_user_headers",
    "per_user_header_keys": ["X-API-Key", "X-Tenant-ID"],
    "user_headers": {
      "X-API-Key":   "your-admin-sample-key",
      "X-Tenant-ID": "your-admin-sample-tenant"
    },
    "headers": {
      "X-Region": { "value": "us-east-1" }
    },
    "tools_to_execute": ["*"]
  }'

Field	Type	Purpose
per_user_header_keys	string[]	Required header names end-users must supply. The schema.
user_headers	map[string]string	Admin’s sample values for the one-time verify. Discarded after the create call; only the verify-headers flow retains them as the admin discovery credential.
headers	map[string]EnvVar	Optional static admin headers that accompany every per-user request.

On success, Bifrost runs the upstream verify with user_headers, attaches the discovered tools, persists the MCP client, and returns:

{
  "status": "success",
  "message": "MCP client registered. 12 tools discovered. Each user will submit their own headers on first tool use."
}

If the verify fails, the call returns 422 Unprocessable Entity with the upstream error — nothing is persisted.

Declare the client with auth_type: "per_user_headers" and the required header-name schema. The admin’s sample values aren’t included in config.json — they’re collected by the UI when verification runs.

{
  "mcp": {
    "client_configs": [
      {
        "name": "acme_api",
        "connection_type": "http",
        "connection_string": "https://api.acme.example.com/mcp",
        "auth_type": "per_user_headers",
        "per_user_header_keys": ["X-API-Key", "X-Tenant-ID"],
        "headers": {
          "X-Region": "us-east-1"
        },
        "tools_to_execute": ["*"]
      }
    ]
  }
}

At boot the client lands in pending_verification state. From the MCP Gateway UI, open the client and click Verify — Bifrost opens the same sample-values dialog the Web UI Create flow uses. Submit values, the upstream verify runs, tools are discovered, the values are retained as the admin discovery credential for later tool-list refresh, and the client transitions to healthy.The same step is scriptable — no browser involved:

curl -X POST http://localhost:8080/api/mcp/client/{id}/verify-headers \
  -H "Content-Type: application/json" \
  -d '{
    "user_headers": {
      "X-API-Key": "sample-admin-key",
      "X-Tenant-ID": "verification-tenant"
    }
  }'

user_headers must cover every declared key. On success the response carries tools_count and the client transitions to healthy; a 422 means the upstream verify failed (retry with different values). A 409 means the client was already verified and its admin discovery credential is healthy (or absent), so there is nothing to re-verify. The one legitimate repeat call is a repair: while the admin credential sits in needs_update, the endpoint accepts fresh sample values and flips the credential back to active on success.Lifecycle across restarts and config edits: the verified state (discovered tools) is server-side and survives restarts and config.json re-syncs, including edits to per_user_header_keys — new keys apply to end-user submissions without re-verification. The key list cannot be emptied, though: an edit that removes all keys is ignored and the stored keys kept (with a warning at boot). Immutable fields — auth_type, connection_type, connection_string, stdio_config — cannot be changed after creation: file edits to them are ignored with a boot warning, matching the update API. Delete the client and re-declare it to change them.

​

Static admin headers

• Per-user values — what each end-user submits (e.g., X-API-Key, X-Tenant-ID)
• Static admin headers — what the admin sets once and is sent on every per-user request (e.g., X-Region, X-Tenant-Class)

1. Static admin headers are not allowed to override per-user header names. If X-API-Key appears in both per_user_header_keys and headers, the static value is dropped on the wire — the per-user value wins.
2. Authorization is treated as a credential by Bifrost and is never exposed to connect-plugins or accidentally leaked.
3. Static admin headers are visible to connect-plugins (so a plugin can read e.g. X-Region and mutate it); per-user values aren’t.

​

Editing the schema

• Web UI
• API

1. Open the MCP client in the MCP Gateway registry
2. Click Edit
3. Update Required Headers
4. Click Save

Existing per-user rows flip to needs_update. The next tool call from each user triggers a fresh submission.

curl -X PUT http://localhost:8080/api/mcp/client/mcp_client_abc123 \
  -H "Content-Type: application/json" \
  -d '{
    "per_user_header_keys": ["X-API-Key", "X-Tenant-ID", "X-Workspace"]
  }'

​

End-user submission flow

1. The page shows:
   • Which MCP server is asking for values
   • Which identity the resulting credential will be bound to (VK name, signed-in user, or session ID)
   • One input per required header name
   • Any static admin headers (names only) so the user knows what context their values will accompany
2. The user fills in values and clicks Submit
3. Bifrost runs a one-time upstream verify against the live MCP client config
4. On success, the credential is persisted; the user sees a “Headers saved” confirmation and can close the tab
5. On failure (bad key, upstream rejected), the page shows the error and offers Retry

​

Identity modes

​

Cross-gateway sharing

​

Lifecycle and sessions

​

Admin discovery credential

• Tool-list refresh only. The periodic tool syncer uses it for a one-shot connect, tools/list, disconnect cycle on the client’s tool sync interval. It is never used for end-user tool calls; those always run under the caller’s own submitted values.
• Invisible on the sessions page. Admin credentials are excluded from MCP Sessions; they are managed from the client sheet instead.

​

Periodic tool sync

• Positive: sync every N minutes for this client
• 0 / unset: inherit the global mcp_tool_sync_interval client setting (minutes, default 10)
• Negative: disable periodic sync for this client

​

Configuration reference

{
  "name": "acme_api",
  "connection_type": "http",
  "connection_string": "https://api.acme.example.com/mcp",
  "auth_type": "per_user_headers",
  "per_user_header_keys": ["X-API-Key", "X-Tenant-ID"],
  "headers": {
    "X-Region": "us-east-1"
  },
  "tools_to_execute": ["*"]
}

​

Troubleshooting

​

Next Steps

• Per-User OAuth — when the upstream provides OAuth
• Headers — when one admin key fits everyone
• MCP Sessions — credential lifecycle, orphan/reactivate, revoke
• MCP Gateway Mode — expose Bifrost as an MCP server for Claude Code / Cursor