Skip to main content
PUT
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.

Path Parameters

id
string
required

MCP client ID

Body

application/json

MCP client configuration for updating an existing client (includes tool_pricing). All fields are optional; omitting a field retains its existing value (PATCH semantics). Immutable fields (connection_type, auth_type, connection_string, stdio_config, oauth_config_id) are not accepted here; they cannot be changed after creation.

openapi_config
object

openapi clients only (400 otherwise). Replaces the document and/or credentials: the block is merged onto the stored one (an omitted spec keeps the stored document, a redacted credential placeholder keeps the stored secret), re-synthesized, and the client's server is rebuilt so its tools reflect the new document. tools_to_execute entries are validated against the resulting tool names.

name
string

Display name for the MCP client

is_code_mode_client
boolean

Whether this client is available in code mode

server_type_on_slug
enum<string>

Code mode on this client's own /mcp/ endpoint only. Omit to keep the current value; "inherit" goes back to following is_code_mode_client.

Available options:
inherit,
enabled,
disabled
is_ping_available
boolean

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

HTTP-only. Only meaningful for auth_type "oauth", "headers", or "none" — 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, 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 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. "" follows the global mcp_max_protocol_version client config; "auto" uses the newest version Bifrost supports. Omitted keeps the current value. A change reconnects the server at the new version.

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

Per-client tool execution timeout in seconds. 0 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 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
headers
object

Custom headers to include in requests. Only used when auth_type is "headers". Supports env./vault. references. Values echoed back redacted from a GET response are recognized and preserve the stored value, so a fetch-modify-put round trip is safe.

allowed_extra_headers
string[]

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

oauth_config
object

Rotates the stored OAuth configuration in place. Only accepted for auth_type "oauth" or "per_user_oauth" (400 otherwise). Any provided field replaces the stored value; no new config row is created and no re-discovery or re-registration runs. Unset fields preserve stored values: client_id/client_secret follow the SecretVar masked-placeholder convention (send back the redacted placeholder from a GET response to keep the stored secret), while empty strings / empty arrays on the remaining fields mean "not provided".

When any field actually changes, every token bound to the OAuth config is flipped to needs_reauth regardless of auth mode, shared and per-user sessions alike must re-authenticate. A round trip that resolves to the stored values is a no-op and does not cascade. Rotation cannot run while the client is (or is being) disabled (400); send those as two separate requests.

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 or null keeps the current list; ["*"] => all prompts; [] => none.

resources_to_expose
string[] | null

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

tool_pricing
object

Per-tool cost in USD for execution. Key is the tool name, value is the cost per execution. Example: {"read_file": 0.001, "write_file": 0.002} Note: Only available when updating an existing client after tools have been fetched.

allow_by_default
boolean

When true, this MCP client's tools are accessible to all virtual keys without requiring explicit per-key assignment. All tools are allowed by default. If a virtual key has an explicit MCP config for this client, that config takes precedence and overrides this behaviour. Omit to keep the current value.

allow_on_all_virtual_keys
boolean
deprecated

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

per_user_header_keys
string[]

For per_user_headers clients only. Cannot be set to an empty list. Updating this list flips every existing active per-user credential row to needs_update; callers will be sent back to the submission form on their next tool call to satisfy the new schema. The retained admin discovery credential is flipped the same way; repair it by calling POST /api/mcp/client/{id}/verify-headers with fresh sample values.

per_user_discovery
boolean

Per-user auth types only, and not for openapi clients. Omitted preserves the stored value. Turning it on deletes the admin credential and the discovery the client keeps; each caller's tools, prompts and resources are then discovered with their own credential. Turning it off deletes every caller's discovery, and the client goes back to pending_verification until an admin verifies it again: through POST /api/mcp/client/{id}/verify-headers, verify-exchange, or, for per_user_oauth, initiate-verification or reauthorize, which sign the admin in on the client's existing OAuth registration so callers keep their sign-ins. For a provider that no longer recognises that registration, reregister registers a new OAuth client first, which needs the OAuth config's registration_url and a provider that accepts the registration (otherwise it answers 400 and changes nothing), and every caller then signs in again. While a client declared in config.json has not completed its first sign-in, reauthorize and reregister answer 400 for it, and initiate-verification runs that first sign-in. While it is on, POST /api/mcp/client/{id}/refresh-tools and POST /api/mcp/client/{id}/reauthorize return 400, as do POST /api/mcp/client/{id}/verify-headers and POST /api/mcp/client/{id}/verify-exchange on a verified client.

token_exchange
object

For token_exchange clients only. Omitted preserves the stored configuration. A redacted client_id / client_secret round-tripped from a prior GET is resolved back to the stored value rather than overwriting it; any other change re-scopes future exchanges and invalidates cached exchanged tokens for this client.

disabled
boolean
default:false

When true, the client's connection, health monitor, and tool syncer are shut down. The client entry is preserved so it can be re-enabled later by sending disabled: false. Disabled clients do not expose tools to inference requests.

tls_config
object

TLS configuration for HTTP, SSE and OpenAPI connections (for OpenAPI, the HTTP client that calls the API). Not applicable to stdio or inprocess connection types. On an enabled client a change applies at once: a client with a persistent connection reconnects with it, a per-call client uses it from its next call, and an OpenAPI client rebuilds the HTTP client that calls the API. A per-call client with none, headers or oauth auth also refreshes its tool list with it; a per-user client's tool list picks it up at its next periodic check. For headers and none auth the change is first tried against the server, and a failure answers 422 with nothing changed. If applying it to the live client then fails, the change is still stored and the answer is 200 with status partial_success. A client with a persistent connection then keeps serving on its current connection and uses the stored change from its next reconnect; call POST /api/mcp/client/{id}/reconnect to apply it now. The exception is a redial that finds the client's OAuth credential needs re-authorization: the connection is closed and the client moves to needs_reauth until it is reauthorized. A disabled client stores the change and connects with it when it is enabled again.

vk_configs
object[]

When provided, replaces all virtual key assignments for this MCP client. Each entry specifies a virtual key and the tools it is allowed to call. To remove all VK access, provide an empty array []. Omit this field to leave existing VK assignments unchanged.

Response

MCP client updated successfully

Generic success response

status
string
Example:

"success"

message
string
Example:

"Operation completed successfully"