> ## Documentation Index > Fetch the complete documentation index at: https://bifrost-dev.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Add MCP client > Adds a new MCP client with the specified configuration. Note: tool_pricing is not available when creating a new client; tool pricing can only be set once the tool list is known. For shared-connection clients tools are fetched after client creation; for per-user auth types they are discovered during the create/verify flow itself. ## OpenAPI ````yaml /openapi/openapi.json post /api/mcp/client openapi: 3.1.0 info: title: Bifrost API description: > Bifrost HTTP Transport API for AI model inference and gateway management. This API provides a unified interface for interacting with multiple AI providers including OpenAI, Anthropic, Bedrock, Gemini, and more through a single API, along with comprehensive management APIs for configuring and monitoring the gateway. ## API Structure ### Unified Inference API (`/v1/*`) The primary API using Bifrost's unified format. Model parameters use the format `provider/model` (e.g., `openai/gpt-4`, `anthropic/claude-3-opus`). ### Async Inference API (`/v1/async/*`) Submit inference requests for asynchronous execution. Returns a job ID immediately and allows polling for results. Supports all inference types except batches, files, and containers. ### Provider Integration APIs Native provider-format APIs for drop-in compatibility: - `/openai/*` - OpenAI-compatible API - `/anthropic/*` - Anthropic-compatible API - `/genai/*` - Google GenAI (Gemini) compatible API - `/bedrock/*` - AWS Bedrock compatible API - `/cohere/*` - Cohere compatible API ### Framework Integration APIs Multi-provider proxy endpoints for AI frameworks: - `/litellm/*` - LiteLLM proxy with all provider formats - `/langchain/*` - LangChain compatible endpoints - `/pydanticai/*` - PydanticAI compatible endpoints ### Management APIs (`/api/*`) APIs for managing and monitoring the Bifrost gateway: - `/api/config` - Configuration management - `/api/providers` - Provider and API key management - `/api/plugins` - Plugin management - `/api/governance/*` - Virtual keys, teams, customers, budgets, rate limits, routing rules, and pricing overrides - `/api/logs` - Log search and analytics - `/api/mcp/*` - MCP (Model Context Protocol) client management - `/api/session/*` - Authentication and session management - `/api/cache/*` - Cache management - `/health` - Health check endpoint ## Fallbacks Requests can include fallback models that will be tried if the primary model fails. version: 1.0.0 contact: name: Contact Us url: https://getmaxim.ai/bifrost license: name: Apache 2.0 url: https://opensource.org/licenses/Apache-2.0 servers: - url: '{baseUrl}' description: Your Bifrost instance variables: baseUrl: default: http://localhost:8080 description: Base URL of your Bifrost instance (e.g. https://bifrost.mycompany.com) security: - BearerAuth: [] - BasicAuth: [] - ApiKeyAuth: [] tags: - name: Models description: Model listing and information - name: Chat Completions description: Chat-based text generation - name: Text Completions description: Text completion generation - name: Responses description: OpenAI Responses API compatible endpoints - name: OCR description: Optical character recognition for documents and images - name: Rerank description: Document reranking by relevance to a query - name: Embeddings description: Text embedding generation - name: Images description: Image generations, editing, and variations - name: Videos description: Video generation and management - name: Audio description: Speech synthesis and transcription - name: Count Tokens description: Token counting utilities - name: Batch description: Batch processing operations - name: Files description: File management operations - name: Containers description: Container management operations - name: Async Jobs description: Asynchronous job submission and retrieval endpoints - name: Realtime description: Realtime WebSocket and WebRTC endpoints - name: OpenAI Integration description: OpenAI-compatible API endpoints (/openai/*) - name: Azure Integration description: Azure OpenAI integration endpoints - name: Anthropic Integration description: Anthropic-compatible API endpoints (/anthropic/*) - name: GenAI Integration description: Google GenAI (Gemini) compatible API endpoints (/genai/*) - name: Bedrock Integration description: AWS Bedrock compatible API endpoints (/bedrock/*) - name: Cohere Integration description: Cohere compatible API endpoints (/cohere/*) - name: LiteLLM Integration description: LiteLLM proxy endpoints with multi-provider support (/litellm/*) - name: LangChain Integration description: LangChain compatible endpoints with multi-provider support (/langchain/*) - name: PydanticAI Integration description: >- PydanticAI compatible endpoints with multi-provider support (/pydanticai/*) - name: Health description: Health check endpoints - name: Configuration description: Configuration management endpoints - name: Session description: Session and authentication endpoints - name: Providers description: Provider management endpoints - name: Plugins description: Plugin management endpoints - name: MCP description: Model Context Protocol endpoints - name: Governance description: Virtual keys, teams, and customers management - name: Routing description: Routing rules and complexity analyzer configuration - name: Logging description: Log search and management endpoints - name: Cache description: Cache management endpoints - name: Vault description: Vault secret management endpoints - name: Skills description: Skills Repository management, marketplace, and download endpoints - name: Audit Logs description: >- CADF-compliant audit log search, export, and signature verification endpoints - name: Webhooks description: Webhook endpoint management and signed async-job delivery history - name: Notifications description: >- Role-targeted dashboard notifications, delivered over the dashboard WebSocket paths: /api/mcp/client: post: tags: - MCP summary: Add MCP client description: > Adds a new MCP client with the specified configuration. Note: tool_pricing is not available when creating a new client; tool pricing can only be set once the tool list is known. For shared-connection clients tools are fetched after client creation; for per-user auth types they are discovered during the create/verify flow itself. operationId: addMCPClient requestBody: required: true content: application/json: schema: oneOf: - allOf: - type: object required: - name - connection_type allOf: - if: required: - auth_type properties: auth_type: const: per_user_headers then: required: - per_user_header_keys properties: per_user_header_keys: type: array minItems: 1 items: type: string minLength: 1 description: > When `auth_type` is `per_user_headers`, `per_user_header_keys` must declare at least one header name — the submission flow has nothing to ask the end-user for otherwise. - if: required: - auth_type properties: auth_type: const: token_exchange then: required: - token_exchange description: > When `auth_type` is `token_exchange`, `token_exchange` must declare at least `audience`, plus either `client_id` or `use_idp_credentials: true` — there is nothing to scope the exchange to, or exchange with, otherwise. - if: required: - auth_type properties: auth_type: not: const: token_exchange then: not: required: - token_exchange description: > A `token_exchange` block only applies to auth_type "token_exchange"; reject it for every other auth_type instead of silently ignoring it. properties: client_id: type: string description: >- Unique identifier for the MCP client (optional, auto-generated if not provided) name: type: string description: Display name for the MCP client is_code_mode_client: type: boolean is_ping_available: type: boolean default: true description: > 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: type: boolean default: false description: > 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: type: integer minimum: 0 description: > Per-client tool-list sync interval in minutes. 0 (or omitted) falls back to the global mcp_tool_sync_interval client config. tool_execution_timeout: type: integer minimum: 0 description: > Per-client tool execution timeout in seconds. 0 (or omitted) falls back to the global mcp_tool_execution_timeout client config. allowed_extra_headers: type: array items: type: string description: > 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 connection_type: type: string enum: - http - stdio - sse - inprocess description: Connection type for MCP client auth_type: type: string enum: - none - headers - oauth - per_user_oauth - per_user_headers - token_exchange description: Authentication type for the MCP connection oauth_config_id: type: string description: > 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: type: object additionalProperties: type: string description: | Custom headers to include in requests. Only used when auth_type is "headers". oauth_config: $ref: '#/components/schemas/OAuthConfigRequest' description: > 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: type: array items: type: string description: > Include-only list for tools. ["*"] => all tools are included [] => no tools are included ["tool1", "tool2"] => include only the specified tools tools_to_auto_execute: type: array items: type: string description: > 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 allow_on_all_virtual_keys: type: boolean default: false description: > 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. tls_config: type: object description: > TLS configuration for HTTP and SSE connections. Not applicable to stdio or inprocess connection types. properties: insecure_skip_verify: type: boolean description: > Disable TLS certificate verification. Takes priority over ca_cert_pem when both are set. Use only in development or trusted isolated environments. Not recommended for production. ca_cert_pem: type: string description: > PEM-encoded CA certificate to trust for MCP server connections. Use when the MCP server uses a self-signed or private CA certificate. Supports env.VAR_NAME syntax to read the certificate from an environment variable. per_user_header_keys: type: array items: type: string description: > 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: type: object required: - audience properties: audience: type: string minLength: 1 description: >- Resource identifier this server is scoped to at the identity provider (e.g. "api://jira-mcp") use_idp_credentials: type: boolean description: > When true, performs the exchange as the SSO login application itself instead of client_id/client_secret below, which are then ignored. Some providers require this: Microsoft Entra ID's on-behalf-of grant only accepts an assertion audienced to the exchanging application, and the SSO login flow always requests a token self-audienced to the SSO application, so a separate exchange application can never receive a usable one. client_id: type: string minLength: 1 description: > The identity-provider application authorized to perform exchanges for this audience — typically a dedicated registration carrying the token-exchange (or on-behalf-of) grant, separate from the SSO login application. Required unless use_idp_credentials is true. Supports env.VAR_NAME and vault.path references. Redacted in API responses. client_secret: type: string description: > Secret for the exchange application; omit for public clients. Ignored when use_idp_credentials is true. Supports env.VAR_NAME and vault.path references. Redacted in API responses. scopes: type: array items: type: string description: > Optional scopes to request on the exchanged token. Include "offline_access" (where the identity provider supports it) so the retained admin discovery credential gets a refresh token and stays self-renewing. authorization_server_url: type: string description: > Overrides the Authorization Server the exchange request is sent to. Only needed when the audience is registered on a different Authorization Server than the one used for SSO login (e.g. Okta's per-resource Custom Authorization Servers). Leave unset to use the deployment's SSO login issuer, which is correct for providers with a single tenant-wide token endpoint (Entra, Auth0). allOf: - if: not: properties: use_idp_credentials: const: true required: - use_idp_credentials then: required: - client_id description: > client_id is required unless use_idp_credentials is true, in which case the exchange uses the SSO login application's own credentials instead. additionalProperties: false description: > Required when creating a client with auth_type "token_exchange". Verification runs automatically as the signed-in admin (see POST /api/mcp/client/{id}/verify-exchange) — there is no sample-token field on this request. user_headers: type: object additionalProperties: type: string description: > 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. Not persisted by the create call; each end-user submits their own values at runtime. To have Bifrost retain an admin discovery credential for periodic tool-list refresh, use POST /api/mcp/client/{id}/verify-headers, which stores the sample values as that credential. - type: object required: - connection_string properties: connection_type: type: string enum: - http connection_string: type: string description: HTTP URL (required for HTTP connection type) - allOf: - type: object required: - name - connection_type allOf: - if: required: - auth_type properties: auth_type: const: per_user_headers then: required: - per_user_header_keys properties: per_user_header_keys: type: array minItems: 1 items: type: string minLength: 1 description: > When `auth_type` is `per_user_headers`, `per_user_header_keys` must declare at least one header name — the submission flow has nothing to ask the end-user for otherwise. - if: required: - auth_type properties: auth_type: const: token_exchange then: required: - token_exchange description: > When `auth_type` is `token_exchange`, `token_exchange` must declare at least `audience`, plus either `client_id` or `use_idp_credentials: true` — there is nothing to scope the exchange to, or exchange with, otherwise. - if: required: - auth_type properties: auth_type: not: const: token_exchange then: not: required: - token_exchange description: > A `token_exchange` block only applies to auth_type "token_exchange"; reject it for every other auth_type instead of silently ignoring it. properties: client_id: type: string description: >- Unique identifier for the MCP client (optional, auto-generated if not provided) name: type: string description: Display name for the MCP client is_code_mode_client: type: boolean is_ping_available: type: boolean default: true description: > 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: type: boolean default: false description: > 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: type: integer minimum: 0 description: > Per-client tool-list sync interval in minutes. 0 (or omitted) falls back to the global mcp_tool_sync_interval client config. tool_execution_timeout: type: integer minimum: 0 description: > Per-client tool execution timeout in seconds. 0 (or omitted) falls back to the global mcp_tool_execution_timeout client config. allowed_extra_headers: type: array items: type: string description: > 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 connection_type: type: string enum: - http - stdio - sse - inprocess description: Connection type for MCP client auth_type: type: string enum: - none - headers - oauth - per_user_oauth - per_user_headers - token_exchange description: Authentication type for the MCP connection oauth_config_id: type: string description: > 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: type: object additionalProperties: type: string description: | Custom headers to include in requests. Only used when auth_type is "headers". oauth_config: $ref: '#/components/schemas/OAuthConfigRequest' description: > 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: type: array items: type: string description: > Include-only list for tools. ["*"] => all tools are included [] => no tools are included ["tool1", "tool2"] => include only the specified tools tools_to_auto_execute: type: array items: type: string description: > 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 allow_on_all_virtual_keys: type: boolean default: false description: > 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. tls_config: type: object description: > TLS configuration for HTTP and SSE connections. Not applicable to stdio or inprocess connection types. properties: insecure_skip_verify: type: boolean description: > Disable TLS certificate verification. Takes priority over ca_cert_pem when both are set. Use only in development or trusted isolated environments. Not recommended for production. ca_cert_pem: type: string description: > PEM-encoded CA certificate to trust for MCP server connections. Use when the MCP server uses a self-signed or private CA certificate. Supports env.VAR_NAME syntax to read the certificate from an environment variable. per_user_header_keys: type: array items: type: string description: > 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: type: object required: - audience properties: audience: type: string minLength: 1 description: >- Resource identifier this server is scoped to at the identity provider (e.g. "api://jira-mcp") use_idp_credentials: type: boolean description: > When true, performs the exchange as the SSO login application itself instead of client_id/client_secret below, which are then ignored. Some providers require this: Microsoft Entra ID's on-behalf-of grant only accepts an assertion audienced to the exchanging application, and the SSO login flow always requests a token self-audienced to the SSO application, so a separate exchange application can never receive a usable one. client_id: type: string minLength: 1 description: > The identity-provider application authorized to perform exchanges for this audience — typically a dedicated registration carrying the token-exchange (or on-behalf-of) grant, separate from the SSO login application. Required unless use_idp_credentials is true. Supports env.VAR_NAME and vault.path references. Redacted in API responses. client_secret: type: string description: > Secret for the exchange application; omit for public clients. Ignored when use_idp_credentials is true. Supports env.VAR_NAME and vault.path references. Redacted in API responses. scopes: type: array items: type: string description: > Optional scopes to request on the exchanged token. Include "offline_access" (where the identity provider supports it) so the retained admin discovery credential gets a refresh token and stays self-renewing. authorization_server_url: type: string description: > Overrides the Authorization Server the exchange request is sent to. Only needed when the audience is registered on a different Authorization Server than the one used for SSO login (e.g. Okta's per-resource Custom Authorization Servers). Leave unset to use the deployment's SSO login issuer, which is correct for providers with a single tenant-wide token endpoint (Entra, Auth0). allOf: - if: not: properties: use_idp_credentials: const: true required: - use_idp_credentials then: required: - client_id description: > client_id is required unless use_idp_credentials is true, in which case the exchange uses the SSO login application's own credentials instead. additionalProperties: false description: > Required when creating a client with auth_type "token_exchange". Verification runs automatically as the signed-in admin (see POST /api/mcp/client/{id}/verify-exchange) — there is no sample-token field on this request. user_headers: type: object additionalProperties: type: string description: > 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. Not persisted by the create call; each end-user submits their own values at runtime. To have Bifrost retain an admin discovery credential for periodic tool-list refresh, use POST /api/mcp/client/{id}/verify-headers, which stores the sample values as that credential. - type: object required: - connection_string properties: connection_type: type: string enum: - sse connection_string: type: string description: SSE URL (required for SSE connection type) - allOf: - type: object required: - name - connection_type allOf: - if: required: - auth_type properties: auth_type: const: per_user_headers then: required: - per_user_header_keys properties: per_user_header_keys: type: array minItems: 1 items: type: string minLength: 1 description: > When `auth_type` is `per_user_headers`, `per_user_header_keys` must declare at least one header name — the submission flow has nothing to ask the end-user for otherwise. - if: required: - auth_type properties: auth_type: const: token_exchange then: required: - token_exchange description: > When `auth_type` is `token_exchange`, `token_exchange` must declare at least `audience`, plus either `client_id` or `use_idp_credentials: true` — there is nothing to scope the exchange to, or exchange with, otherwise. - if: required: - auth_type properties: auth_type: not: const: token_exchange then: not: required: - token_exchange description: > A `token_exchange` block only applies to auth_type "token_exchange"; reject it for every other auth_type instead of silently ignoring it. properties: client_id: type: string description: >- Unique identifier for the MCP client (optional, auto-generated if not provided) name: type: string description: Display name for the MCP client is_code_mode_client: type: boolean is_ping_available: type: boolean default: true description: > 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: type: boolean default: false description: > 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: type: integer minimum: 0 description: > Per-client tool-list sync interval in minutes. 0 (or omitted) falls back to the global mcp_tool_sync_interval client config. tool_execution_timeout: type: integer minimum: 0 description: > Per-client tool execution timeout in seconds. 0 (or omitted) falls back to the global mcp_tool_execution_timeout client config. allowed_extra_headers: type: array items: type: string description: > 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 connection_type: type: string enum: - http - stdio - sse - inprocess description: Connection type for MCP client auth_type: type: string enum: - none - headers - oauth - per_user_oauth - per_user_headers - token_exchange description: Authentication type for the MCP connection oauth_config_id: type: string description: > 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: type: object additionalProperties: type: string description: | Custom headers to include in requests. Only used when auth_type is "headers". oauth_config: $ref: '#/components/schemas/OAuthConfigRequest' description: > 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: type: array items: type: string description: > Include-only list for tools. ["*"] => all tools are included [] => no tools are included ["tool1", "tool2"] => include only the specified tools tools_to_auto_execute: type: array items: type: string description: > 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 allow_on_all_virtual_keys: type: boolean default: false description: > 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. tls_config: type: object description: > TLS configuration for HTTP and SSE connections. Not applicable to stdio or inprocess connection types. properties: insecure_skip_verify: type: boolean description: > Disable TLS certificate verification. Takes priority over ca_cert_pem when both are set. Use only in development or trusted isolated environments. Not recommended for production. ca_cert_pem: type: string description: > PEM-encoded CA certificate to trust for MCP server connections. Use when the MCP server uses a self-signed or private CA certificate. Supports env.VAR_NAME syntax to read the certificate from an environment variable. per_user_header_keys: type: array items: type: string description: > 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: type: object required: - audience properties: audience: type: string minLength: 1 description: >- Resource identifier this server is scoped to at the identity provider (e.g. "api://jira-mcp") use_idp_credentials: type: boolean description: > When true, performs the exchange as the SSO login application itself instead of client_id/client_secret below, which are then ignored. Some providers require this: Microsoft Entra ID's on-behalf-of grant only accepts an assertion audienced to the exchanging application, and the SSO login flow always requests a token self-audienced to the SSO application, so a separate exchange application can never receive a usable one. client_id: type: string minLength: 1 description: > The identity-provider application authorized to perform exchanges for this audience — typically a dedicated registration carrying the token-exchange (or on-behalf-of) grant, separate from the SSO login application. Required unless use_idp_credentials is true. Supports env.VAR_NAME and vault.path references. Redacted in API responses. client_secret: type: string description: > Secret for the exchange application; omit for public clients. Ignored when use_idp_credentials is true. Supports env.VAR_NAME and vault.path references. Redacted in API responses. scopes: type: array items: type: string description: > Optional scopes to request on the exchanged token. Include "offline_access" (where the identity provider supports it) so the retained admin discovery credential gets a refresh token and stays self-renewing. authorization_server_url: type: string description: > Overrides the Authorization Server the exchange request is sent to. Only needed when the audience is registered on a different Authorization Server than the one used for SSO login (e.g. Okta's per-resource Custom Authorization Servers). Leave unset to use the deployment's SSO login issuer, which is correct for providers with a single tenant-wide token endpoint (Entra, Auth0). allOf: - if: not: properties: use_idp_credentials: const: true required: - use_idp_credentials then: required: - client_id description: > client_id is required unless use_idp_credentials is true, in which case the exchange uses the SSO login application's own credentials instead. additionalProperties: false description: > Required when creating a client with auth_type "token_exchange". Verification runs automatically as the signed-in admin (see POST /api/mcp/client/{id}/verify-exchange) — there is no sample-token field on this request. user_headers: type: object additionalProperties: type: string description: > 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. Not persisted by the create call; each end-user submits their own values at runtime. To have Bifrost retain an admin discovery credential for periodic tool-list refresh, use POST /api/mcp/client/{id}/verify-headers, which stores the sample values as that credential. - type: object required: - stdio_config properties: connection_type: type: string enum: - stdio stdio_config: type: object description: >- STDIO configuration (required for STDIO connection type) properties: command: type: string description: Executable command to run args: type: array items: type: string description: Command line arguments envs: type: array items: type: string description: Environment variables required discriminator: propertyName: connection_type mapping: http: '#/MCPClientCreateRequestHTTP' sse: '#/MCPClientCreateRequestSSE' stdio: '#/MCPClientCreateRequestSTDIO' description: > 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 - InProcess: server instance must be provided programmatically (Go package only) responses: '200': description: | 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. content: application/json: schema: oneOf: - $ref: '#/components/schemas/SuccessResponse' - $ref: '#/components/schemas/OAuthFlowInitiation' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/BifrostError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/BifrostError' security: - ManagementBearerAuth: [] components: schemas: OAuthConfigRequest: type: object description: | OAuth configuration for an MCP client. Used both when creating a client (initiates the OAuth flow) and when updating one (rotates the stored OAuth config in place; see MCPClientUpdateRequest.oauth_config). properties: client_id: allOf: - type: object description: > A secret-capable value. Serialized as an object with the resolved `value` plus reference metadata; on input, a bare string is also accepted — plain text, `env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and only the reference is persisted). properties: value: type: string description: Resolved value (redacted in GET responses for secret fields) ref: type: string description: >- Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values type: type: string enum: - plain_text - env - vault description: Source type of the value description: > OAuth client ID. Optional if client supports dynamic client registration (RFC 7591). If not provided, the server_url must be set for OAuth discovery and dynamic registration. Supports env./vault. references. client_secret: allOf: - type: object description: > A secret-capable value. Serialized as an object with the resolved `value` plus reference metadata; on input, a bare string is also accepted — plain text, `env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and only the reference is persisted). properties: value: type: string description: Resolved value (redacted in GET responses for secret fields) ref: type: string description: >- Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values type: type: string enum: - plain_text - env - vault description: Source type of the value description: > OAuth client secret. Optional for public clients using PKCE or clients obtained via dynamic registration. Supports env./vault. references. authorize_url: type: string description: > OAuth authorization endpoint URL. Optional - will be discovered from server_url if not provided. token_url: type: string description: > OAuth token endpoint URL. Optional - will be discovered from server_url if not provided. registration_url: type: string description: > Dynamic client registration endpoint URL (RFC 7591). Optional - will be discovered from server_url if not provided. scopes: type: array items: type: string description: > OAuth scopes requested. Optional - can be discovered from server_url if not provided. Example: ["read", "write"] resource: type: string description: > Resource indicator (RFC 8707) sent on authorization and token requests. Optional - identifies the protected MCP resource the token is intended for, when the upstream provider supports resource indicators. SuccessResponse: type: object description: Generic success response properties: status: type: string example: success message: type: string example: Operation completed successfully OAuthFlowInitiation: type: object description: Response when initiating an OAuth flow properties: status: type: string enum: - pending_oauth message: type: string oauth_config_id: type: string description: ID of the OAuth config created for this flow authorize_url: type: string description: URL to redirect the user to for authorization expires_at: type: string format: date-time description: When the OAuth authorization request expires mcp_client_id: type: string description: The MCP client ID that initiated this OAuth flow complete_url: type: string description: | Relative URL to POST once the flow is authorized (/api/mcp/client/{oauth_config_id}/complete-oauth). Note the path parameter is the oauth_config_id, not the MCP client ID. status_url: type: string description: | Relative URL to poll for the flow status (/api/oauth/config/{oauth_config_id}/status). Wait for status "authorized" before calling complete_url. next_steps: type: array items: type: string description: >- Human-readable steps to complete the flow (authorize, poll, complete) BifrostError: type: object description: Error response from Bifrost properties: event_id: type: string type: type: string is_bifrost_error: type: boolean status_code: type: integer error: $ref: '#/components/schemas/ErrorField' extra_fields: $ref: '#/components/schemas/BifrostErrorExtraFields' ErrorField: type: object properties: type: type: string code: type: string message: type: string param: type: string event_id: type: string BifrostErrorExtraFields: type: object properties: provider: $ref: '#/components/schemas/ModelProvider' model_requested: type: string request_type: type: string ModelProvider: type: string description: AI model provider identifier enum: - openai - azure - anthropic - bedrock - cohere - vertex - vllm - mistral - ollama - groq - sgl - parasail - perplexity - replicate - cerebras - deepseek - gemini - openrouter - elevenlabs - huggingface - nebius - xai - runway - fireworks securitySchemes: BearerAuth: type: http scheme: bearer description: > Bearer token authentication. Use your provider API key or Bifrost authentication token. Virtual keys (prefixed with `sk-bf-`) can also be passed here. BasicAuth: type: http scheme: basic description: | Basic authentication using username and password. ApiKeyAuth: type: apiKey in: header name: x-api-key description: | API key authentication via the `x-api-key` header. Virtual keys (prefixed with `sk-bf-`) can also be passed here. ManagementBearerAuth: type: http scheme: bearer description: > Management API authentication for `/api/*` endpoints. Use the `Authorization` header with `Bearer `. Virtual keys, dashboard/user/session tokens, and `x-api-key` headers are not supported on management APIs. ````