> ## 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. # List MCP clients > Returns a paginated list of configured MCP clients with their tools and connection state. Supports case-insensitive name search and exact-match filtering by connection type, auth type, code-mode, and enabled/disabled status. Multi-value filters accept a comma-separated list and use OR semantics within a field. ## OpenAPI ````yaml /openapi/openapi.json get /api/mcp/clients 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/clients: get: tags: - MCP summary: List MCP clients description: > Returns a paginated list of configured MCP clients with their tools and connection state. Supports case-insensitive name search and exact-match filtering by connection type, auth type, code-mode, and enabled/disabled status. Multi-value filters accept a comma-separated list and use OR semantics within a field. operationId: getMCPClients parameters: - name: limit in: query description: Maximum number of clients to return (1–100, default 25). schema: type: integer minimum: 1 maximum: 100 default: 25 - name: offset in: query description: Number of clients to skip. schema: type: integer minimum: 0 - name: search in: query description: Case-insensitive search by client name. schema: type: string - name: server in: query description: Filter to a single client by its exact client_id. schema: type: string - name: connection_type in: query description: Comma-separated connection types to include (OR semantics). schema: type: string example: http,sse - name: auth_type in: query description: Comma-separated auth types to include (OR semantics). schema: type: string example: oauth,per_user_oauth - name: state in: query description: | Comma-separated runtime connection states to include (OR semantics), resolved against live engine state. Only `healthy` and `unstable` are meaningful filter values: `healthy` matches clients the engine currently reports as healthy; `unstable` matches everything else (error, pending states, needs_reauth, disabled, not present in the engine). Selecting both, or neither, applies no state filter. Note the response-only needs_reauth projection on per-user clients happens after filtering, so such clients still match `healthy`. schema: type: string example: healthy - name: all_virtual_keys in: query description: >- When true, include clients that are open to all virtual keys (allow_on_all_virtual_keys). ORs with virtual_keys. schema: type: boolean - name: virtual_keys in: query description: >- Comma-separated virtual key IDs; includes clients explicitly assigned to any of them. ORs with all_virtual_keys. schema: type: string - name: code_mode in: query description: Filter by code-mode clients. Omit for no filter. schema: type: boolean - name: disabled in: query description: >- Filter by disabled status — true returns disabled clients, false returns enabled clients. Omit for no filter. schema: type: boolean responses: '200': description: Successful response content: application/json: schema: type: object description: Paginated list of MCP clients. required: - clients - count - total_count - limit - offset properties: clients: type: array items: $ref: '#/components/schemas/MCPClient' count: type: integer description: Number of clients returned in this page total_count: type: integer format: int64 description: >- Total number of clients matching the query (before pagination) limit: type: integer description: Page size used for the response offset: type: integer description: Page offset used for the response '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: [] - BasicAuth: [] components: schemas: MCPClient: type: object description: Connected MCP client with its tools properties: config: $ref: '#/components/schemas/MCPClientConfig' tools: type: array items: type: object description: Tool function definition properties: name: type: string description: type: string parameters: type: object additionalProperties: true strict: type: boolean state: type: string enum: - healthy - unstable - error - pending_verification - needs_reauth - disabled - degraded description: > Connection state of an MCP client: - healthy: Bifrost's own periodic connection check (ping/list_tools for sticky clients, list_tools for per-call clients) most recently succeeded. - unstable: The periodic connection check most recently failed with a transient-classified error. Purely informational — unlike needs_reauth, this never gates execution; tool calls are still attempted normally. Self-heals to healthy on the next successful check, no human action required. - error: A data-consistency fallback used only when a client is registered in the config store but missing from the runtime manager entirely — a deeper anomaly than anything in the normal connect/health-check lifecycle, which never assigns this value itself. - pending_verification: Declared (typically via config.json) but the one-time admin verification has not been completed yet. Complete it via POST /api/mcp/client/{id}/initiate-verification (auth_type oauth / per_user_oauth) or POST /api/mcp/client/{id}/verify-headers (auth_type per_user_headers). - needs_reauth: Setup completed at least once, but a credential an admin is responsible for has permanently died and needs a human to repair it. For shared OAuth clients the connection credential itself was rejected/expired with no silent recovery; the state is sticky (the health monitor will not clobber it) until an admin runs POST /api/mcp/client/{id}/reauthorize. For per-user clients this is a response-only projection — computed at list-time, never stored in the runtime manager — meaning the retained admin discovery credential needs repair; end-user credentials and tool calls keep working, only periodic tool-list refresh pauses. Overlays onto both healthy and unstable runtime readings, never onto disabled or pending_verification. Repair via reauthorize (per_user_oauth), verify-headers with fresh sample values (per_user_headers), or verify-exchange (token_exchange, which re-exchanges the signed-in admin's own identity token — no sample values to supply). - disabled: Client has been intentionally disabled; no connection or workers are active - degraded: A read-time cluster aggregate, never a single node's own local state — multiple instances of a distributed deployment each currently hold a different self-reported state for the same client. Only meaningful for states that can genuinely vary per instance (healthy, unstable, pending_verification); needs_reauth/disabled are config-sourced facts expected to already agree everywhere. Never appears in a single-instance deployment. last_failure: $ref: '#/components/schemas/MCPConnectionFailure' node_states: type: object additionalProperties: $ref: '#/components/schemas/MCPInstanceState' description: > Per-instance breakdown behind `state` in a distributed deployment: instance ID -> that instance's own self-reported state and last_failure. Present when instances disagree (`state` is then `degraded`) and when they all agree on `unstable`, so each instance's own reason is visible. Never present in a single-instance deployment. vk_configs: type: array items: type: object description: >- Per-virtual-key tool access configuration as returned in list/get responses properties: virtual_key_id: type: string description: ID of the virtual key virtual_key_name: type: string description: Display name of the virtual key tools_to_execute: type: array items: type: string description: | Tools this virtual key is allowed to call on this MCP client. ["*"] => all tools allowed ["tool1", "tool2"] => only the specified tools description: Virtual key assignments for this MCP client 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' MCPClientConfig: type: object description: Full MCP client configuration (used in responses) properties: client_id: type: string description: Unique identifier for the MCP client name: type: string description: Display name for the MCP client is_code_mode_client: type: boolean description: Whether this client is available in code mode connection_type: type: string enum: - http - stdio - sse - inprocess description: Connection type for MCP client connection_string: type: string description: HTTP or SSE URL (required for HTTP or SSE connections) stdio_config: type: object description: STDIO configuration for MCP client 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 tls_config: type: object description: TLS configuration for HTTP and SSE connections. properties: insecure_skip_verify: type: boolean description: Disable TLS certificate verification. Development/testing only. ca_cert_pem: type: string description: > PEM-encoded CA certificate. Supports env.VAR_NAME syntax for input. Responses return a redacted placeholder rather than the raw PEM value. 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. References the oauth_configs table. Only set 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". 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 tool_pricing: type: object additionalProperties: type: number format: double description: | 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} allow_on_all_virtual_keys: type: boolean default: false description: > 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. per_user_header_keys: type: array items: type: string description: > For `per_user_headers` clients only. The list of header names each end-user must supply via the inline-401 flow. Header values themselves are stored per-user in a separate table (surfaced on `/api/mcp/sessions`). 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: > For `token_exchange` clients only. `client_id` and `client_secret` are redacted in this response. disabled: type: boolean default: false description: > Whether the client is intentionally disabled. When true, the client has no active connection or workers and its tools are not available for inference. MCPConnectionFailure: type: object description: | The latest failure recorded by the instance serving the request for its own connection handling of this client: which step failed, the error it failed with, when that last happened, and when the current run of failures began. Present only after that instance has attempted a connect or check that failed. Absent while `healthy`, cleared the moment a check passes, and absent when a state changed without such an attempt, for example `needs_reauth` projected from a credential row that died before the next scheduled check ran. Describes only Bifrost's own connection checks and connect attempts, never the outcome of real tool calls made through the client. required: - stage - message - at - since properties: stage: type: string enum: - connect - ping - list_tools - tool_discovery - transport_lost - credential description: > The step that failed: - connect: establishing the shared connection (dial, initialize, connect gate, or the initial list_tools a new connection must pass) - ping: the periodic check's ping over an existing sticky connection - list_tools: the periodic check's list_tools over an existing sticky connection - tool_discovery: the periodic check's ephemeral connect-discover-close cycle for per-call auth types - transport_lost: a live SSE connection dropped outside any check - credential: a credential the connection depends on was rejected upstream or rotated by an admin message: type: string description: >- The error the step failed with, whitespace-collapsed and capped at 512 characters. at: type: string format: date-time description: | The most recent failed attempt. While a client is unstable the check retries every 10 seconds, so this keeps moving for as long as the outage lasts. since: type: string format: date-time description: The first failed attempt of the current unhealthy run. MCPInstanceState: type: object description: One instance's own view of an MCP client in a distributed deployment. required: - state properties: state: type: string enum: - healthy - unstable - error - pending_verification - needs_reauth - disabled description: > That instance's own self-reported connection state. Never `degraded`, which only ever exists as the aggregate above this map. last_failure: $ref: '#/components/schemas/MCPConnectionFailure' 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: - anthropic - azure - bedrock - bedrock_mantle - cerebras - cohere - deepseek - gemini - groq - mistral - ollama - opencode-go - opencode-zen - openai - parasail - perplexity - sgl - vertex - openrouter - elevenlabs - huggingface - nebius - xai - replicate - vllm - runway - runware - fireworks - sarvam - wafer - databricks 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 the Bifrost admin username and password (`auth_config.admin_username` / `auth_config.admin_password`). Accepted on management APIs (`/api/*`, `/metrics`, `/ws`) only - the inference middleware never validates Basic credentials. 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 `, where `` is one of: - a Bifrost management API key, - a dashboard session token issued by `POST /api/session/login`, - base64 of `:` (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. ````