Skip to main content
POST
Error
Required Permissions How permissions work

Authorizations

Authorization
string
header
required

Management API authentication for /api/* endpoints. Use the Authorization header with Bearer <token>, where <token> is one of:

  • a Bifrost management API key,
  • a dashboard session token issued by POST /api/session/login,
  • base64 of <admin-username>:<admin-password> (legacy equivalent of BasicAuth).

Virtual keys (sk-bf-*) and the x-api-key header are not accepted on management APIs - the sole exception is GET /api/governance/virtual-keys/quota, which is virtual-key-only.

Authentication alone is not sufficient in Bifrost Enterprise: each operation page shows a Required Permissions table (Resource:Operation, for example Dashboard:View) above its Authorizations section, and the caller's RBAC role or management API key scopes must include what it lists, otherwise the request is rejected with 403 Forbidden.

A local admin — authenticated with the admin password, or any caller on a deployment with dashboard auth disabled — bypasses these checks and can call every management endpoint.

OSS setup lock. On Bifrost OSS, while dashboard auth is not active (no admin account, or auth disabled), every management endpoint except the public ones (/health, /api/version, /api/session/is-auth-enabled, /api/session/login, ...) requires the operator's setup token in the X-Bifrost-Setup-Token header, in place of Authorization. The token is set with setup_token in config.json or the BIFROST_SETUP_TOKEN environment variable. A missing header returns 401, a wrong token 403. The header stops working once dashboard auth is enabled. The dashboard instead trades the token once for an HttpOnly bifrost_setup_session cookie via POST /api/session/setup. See Required permissions for how permissions are derived and which endpoints are exempt.

Body

application/json

MCP client configuration for creating a new client (tool_pricing not available at creation). The schema varies based on connection_type:

  • HTTP/SSE: connection_string is required
  • STDIO: stdio_config is required
  • OpenAPI: openapi_config is required (spec or spec_url); connection_string must be omitted
  • InProcess: server instance must be provided programmatically (Go package only)
name
string
required

Display name for the MCP client

connection_type
enum<string>
required

Connection type for MCP client. openapi synthesizes an in-process MCP server from an OpenAPI/Swagger document (see openapi_config): every supported operation becomes a tool whose call is proxied as an HTTP request to the described API.

Available options:
http
connection_string
string
required

HTTP URL (required for HTTP connection type)

client_id
string

Unique identifier for the MCP client (optional, auto-generated if not provided)

is_code_mode_client
boolean
server_type_on_slug
enum<string>
default:inherit

Code mode on this client's own /mcp/ endpoint only. "inherit" follows is_code_mode_client, "enabled" turns code mode on there, "disabled" serves the client's tools directly there. /mcp, Virtual MCP endpoints and LLM requests always follow is_code_mode_client.

Available options:
inherit,
enabled,
disabled
is_ping_available
boolean
default:true

Whether the MCP server supports ping for health checks. If true, uses lightweight ping method for health checks. If false, uses listTools method for health checks instead.

needs_session_stickiness
boolean
default:false

HTTP-only. Only meaningful for auth_type "oauth", "headers", or "none" (a server-level connection) — per-user auth types are always per-call regardless of this field. When true, Bifrost holds one persistent upstream connection, reused for every tool call. When false or omitted (the default), a fresh connection is dialed per tool call. Cannot be set to false for connection_type "sse" or "stdio" — both are always sticky.

tool_sync_interval
integer

Per-client tool-list sync interval in minutes. 0 (or omitted) falls back to the global mcp_tool_sync_interval client config.

Required range: x >= 0
max_protocol_version
enum<string>

Newest MCP protocol version Bifrost offers this server; the server can still negotiate an older one. "auto" uses the newest version Bifrost supports. Omitted or "" follows the global mcp_max_protocol_version. Ignored for openapi servers.

Available options:
,
auto,
2026-07-28,
2025-11-25,
2025-06-18
tool_execution_timeout
integer

Per-client tool execution timeout in seconds. 0 (or omitted) falls back to the global mcp_tool_execution_timeout client config.

Required range: x >= 0
max_instructions_length
integer

Per-client cap on forwarded instructions, in bytes. 0 (or omitted) falls back to the global mcp_max_instructions_per_client client config. The aggregate across servers is still bounded by mcp_max_instructions_total.

Required range: x >= 0
allowed_extra_headers
string[]

Allowlist of request-level headers callers may forward to this MCP server at execution time. ["*"] => any header may be forwarded [] or omitted => no extra headers are forwarded ["header1", "header2"] => only the specified headers

auth_type
enum<string>
required if per_user_discovery = true

Authentication type for the MCP connection

Available options:
none,
headers,
oauth,
per_user_oauth,
per_user_headers,
token_exchange
oauth_config_id
string

OAuth config ID for OAuth authentication. Set after OAuth flow is completed. References the oauth_configs table. Only relevant when auth_type is "oauth".

headers
object

Custom headers to include in requests. Only used when auth_type is "headers".

oauth_config
object

OAuth configuration for initiating OAuth flow. Required when creating a client with auth_type "oauth" or "per_user_oauth". This will trigger the OAuth flow and return an authorization URL (see the pending_oauth response variant).

tools_to_execute
string[]

Include-only list for tools. ["*"] => all tools are included [] => no tools are included ["tool1", "tool2"] => include only the specified tools

tools_to_auto_execute
string[]

List of tools that can be auto-executed without user approval. Must be a subset of tools_to_execute. ["*"] => all executable tools can be auto-executed [] => no tools are auto-executed ["tool1", "tool2"] => only specified tools can be auto-executed

prompts_to_expose
string[] | null

Prompts (by the server's own name) served through Bifrost's MCP gateway. Omitted, null or ["*"] => all prompts; [] => none.

resources_to_expose
string[] | null

Resource URIs and URI templates served through Bifrost's MCP gateway. Omitted, null or ["*"] => all; [] => none.

endpoint_slug
string

URL-safe path segment this client is served at (/mcp/). Derived from the name when omitted; rejected with 400 if no slug can be derived and 409 if it is taken. Immutable after creation.

tool_pricing
object

Per-tool cost in USD for execution. Key is the tool name, value is the cost per execution.

allow_by_default
boolean
default:false

When true, this MCP client's tools are available to all virtual keys by default, without requiring an explicit virtual key assignment. An explicit virtual key config always overrides this setting for that key.

allow_on_all_virtual_keys
boolean
deprecated

Deprecated earlier name of allow_by_default, still accepted. allow_by_default decides when both are sent.

tls_config
object

TLS configuration for HTTP and SSE connections. Not applicable to stdio or inprocess connection types.

per_user_header_keys
string[]
required if auth_type = per_user_headers

Required when auth_type is per_user_headers. List of header names each end-user must supply the first time they hit this MCP server. Values are submitted per user via the inline-401 flow — never persisted on the MCP client config.

token_exchange
object
required if auth_type = token_exchange

Required when creating a client with auth_type "token_exchange". Verification runs automatically as the signed-in admin, exchanging the identity-provider token on the request or, when it carries none, the access token from the admin's own Bifrost sign-in (see POST /api/mcp/client/{id}/verify-exchange). A request with neither, such as one made with an API key, creates the client in pending_verification. There is no sample-token field on this request.

per_user_discovery
boolean
default:false

Per-user auth types only (per_user_oauth, per_user_headers, token_exchange), and not for connection_type "openapi". When true, each caller's tools, prompts and resources are discovered with their own credential when they connect, and the client keeps no admin credential or discovery of its own: the admin's verification only checks the server. Every caller is served their own tools, prompts, resources and resource templates, the MCP gateway (/mcp) included, and a caller who has not connected yet is offered the client's <name>-connect tool. When false or omitted, every caller is served what was discovered with the admin credential.

user_headers
object

Used only at create time when auth_type is per_user_headers. A sample set of header values the admin supplies so Bifrost can run a one-time upstream verify and discover the tool list. The create call also keeps them as the client's admin discovery credential, as POST /api/mcp/client/{id}/verify-headers does, used only for periodic and on-demand (POST /api/mcp/client/{id}/refresh-tools) tool-list refresh. Keeping them is best effort: if storing the credential fails, the client is still created. Each end-user submits their own values at runtime.

Response

MCP client added successfully. For auth_type "oauth" and "per_user_oauth" the client is not created yet — the response is the pending_oauth variant carrying authorize_url plus status_url / complete_url / next_steps hints; the client is created when the flow is completed via complete_url.

Generic success response

status
string
Example:

"success"

message
string
Example:

"Operation completed successfully"