Per-User Headers

Documentation Index

Fetch the complete documentation index at: https://docs.getbifrost.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

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.
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.

File-based config is not supported for per_user_headers. Bifrost needs to run the one-time upstream verify with the admin’s sample values during create, which can only happen via an interactive admin step (Web UI or API).If you want a declarative-ish setup, run the API create once with your sample values, then check the resulting mcp_client_id into your config to reference it from other parts of the system. The MCP client itself stays in Bifrost’s database.

​

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

​

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": { "value": "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