---
title: "List MCP clients"
method: GET
path: "/api/mcp/clients"
tags: ["MCP"]
---

# List MCP clients

`GET /api/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.

## Query parameters

- `limit` integer
- `offset` integer
- `search` string
- `server` string
- `connection_type` string
- `auth_type` string
- `state` string
- `all_virtual_keys` boolean
- `virtual_keys` string
- `code_mode` boolean
- `disabled` boolean

## Response `200`

Successful response

- object — Paginated list of MCP clients.
  - `clients` MCPClient[], required
    - `config` MCPClientConfig — Full MCP client configuration (used in responses)
      - `client_id` string — Unique identifier for the MCP client
      - `name` string — Display name for the MCP client
      - `is_code_mode_client` boolean — Whether this client is available in code mode
      - `connection_type` 'http' | 'stdio' | 'sse' | 'inprocess' — Connection type for MCP client
      - `connection_string` string — HTTP or SSE URL (required for HTTP or SSE connections)
      - `stdio_config` object — STDIO configuration for MCP client
        - `command` string — Executable command to run
        - `args` string[] — Command line arguments
        - `envs` string[] — Environment variables required
      - `tls_config` object — TLS configuration for HTTP and SSE connections.
        - `insecure_skip_verify` boolean — Disable TLS certificate verification. Development/testing only.
        - `ca_cert_pem` string — PEM-encoded CA certificate. Supports env.VAR_NAME syntax for input. Responses return a redacted placeholder rather than the raw PEM value.
      - `auth_type` 'none' | 'headers' | 'oauth' | 'per_user_oauth' | 'per_user_headers' — Authentication type for the MCP connection
      - `oauth_config_id` string — OAuth config ID for OAuth authentication. References the oauth_configs table. Only set when auth_type is "oauth".
      - `headers` object — Custom headers to include in requests. Only used when auth_type is "headers".
      - `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
      - `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}
      - `allow_on_all_virtual_keys` 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.
      - `per_user_header_keys` string[] — 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`).
      - `disabled` boolean — Whether the client is intentionally disabled. When true, the client has no active connection or workers and its tools are not available for inference.
    - `tools` object[]
      - `name` string
      - `description` string
      - `parameters` object
      - `strict` boolean
    - `state` 'connected' | 'disconnected' | 'error' | 'pending_tools' | 'disabled' — Connection state of an MCP client: - connected: Client is connected and ready to use - disconnected: Client is not connected (will be auto-recovered by health monitor) - error: Client is in an unrecoverable error state - pending_tools: Connected but tools not yet populated (per-user OAuth clients) - disabled: Client has been intentionally disabled; no connection or workers are active
    - `vk_configs` object[] — Virtual key assignments for this MCP client
      - `virtual_key_id` string — ID of the virtual key
      - `virtual_key_name` string — Display name of the virtual key
      - `tools_to_execute` string[] — Tools this virtual key is allowed to call on this MCP client. ["*"] => all tools allowed ["tool1", "tool2"] => only the specified tools
  - `count` integer, required — Number of clients returned in this page
  - `total_count` integer, required — Total number of clients matching the query (before pagination)
  - `limit` integer, required — Page size used for the response
  - `offset` integer, required — Page offset used for the response

## Other responses

- `400` — Bad request
- `500` — Internal server error

---

[API](https://skmtc.net/getbifrost/apis/bifrost-api.md) · [All operations](https://skmtc.net/getbifrost/apis/bifrost-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/getbifrost/bifrost-api/versions/f8cab88f64ea/schema)