---
title: "Add MCP client"
method: POST
path: "/api/mcp/client"
tags: ["MCP"]
---

# Add MCP client

`POST /api/mcp/client`

Adds a new MCP client with the specified configuration.
Note: tool_pricing is not available when creating a new client as tools are fetched after client creation.

## Request body

- union — 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)
  - object
    - `client_id` string — Unique identifier for the MCP client (optional, auto-generated if not provided)
    - `name` string, required — Display name for the MCP client
    - `is_code_mode_client` boolean
    - `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.
    - `connection_type` 'http', required — Connection type for MCP client
    - `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. 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` OAuthConfigRequest — OAuth configuration for MCP client creation
      - `client_id` string — 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.
      - `client_secret` string — OAuth client secret. Optional for public clients using PKCE or clients obtained via dynamic registration.
      - `authorize_url` string — OAuth authorization endpoint URL. Optional - will be discovered from server_url if not provided.
      - `token_url` string — OAuth token endpoint URL. Optional - will be discovered from server_url if not provided.
      - `registration_url` string — Dynamic client registration endpoint URL (RFC 7591). Optional - will be discovered from server_url if not provided.
      - `scopes` string[] — OAuth scopes requested. Optional - can be discovered from server_url if not provided. Example: ["read", "write"]
    - `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
    - `allow_on_all_virtual_keys` boolean — 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` object — TLS configuration for HTTP and SSE connections. Not applicable to stdio or inprocess connection types.
      - `insecure_skip_verify` boolean — 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` string — 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` string[] — 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.
    - `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. Discarded after the create call — not persisted. Mirrors how the admin's temp OAuth token is used for `per_user_oauth` setup.
    - `connection_string` string, required — HTTP URL (required for HTTP connection type)
  - object
    - `client_id` string — Unique identifier for the MCP client (optional, auto-generated if not provided)
    - `name` string, required — Display name for the MCP client
    - `is_code_mode_client` boolean
    - `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.
    - `connection_type` 'sse', required — Connection type for MCP client
    - `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. 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` OAuthConfigRequest — OAuth configuration for MCP client creation
      - `client_id` string — 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.
      - `client_secret` string — OAuth client secret. Optional for public clients using PKCE or clients obtained via dynamic registration.
      - `authorize_url` string — OAuth authorization endpoint URL. Optional - will be discovered from server_url if not provided.
      - `token_url` string — OAuth token endpoint URL. Optional - will be discovered from server_url if not provided.
      - `registration_url` string — Dynamic client registration endpoint URL (RFC 7591). Optional - will be discovered from server_url if not provided.
      - `scopes` string[] — OAuth scopes requested. Optional - can be discovered from server_url if not provided. Example: ["read", "write"]
    - `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
    - `allow_on_all_virtual_keys` boolean — 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` object — TLS configuration for HTTP and SSE connections. Not applicable to stdio or inprocess connection types.
      - `insecure_skip_verify` boolean — 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` string — 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` string[] — 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.
    - `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. Discarded after the create call — not persisted. Mirrors how the admin's temp OAuth token is used for `per_user_oauth` setup.
    - `connection_string` string, required — SSE URL (required for SSE connection type)
  - object
    - `client_id` string — Unique identifier for the MCP client (optional, auto-generated if not provided)
    - `name` string, required — Display name for the MCP client
    - `is_code_mode_client` boolean
    - `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.
    - `connection_type` 'stdio', required — Connection type for MCP client
    - `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. 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` OAuthConfigRequest — OAuth configuration for MCP client creation
      - `client_id` string — 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.
      - `client_secret` string — OAuth client secret. Optional for public clients using PKCE or clients obtained via dynamic registration.
      - `authorize_url` string — OAuth authorization endpoint URL. Optional - will be discovered from server_url if not provided.
      - `token_url` string — OAuth token endpoint URL. Optional - will be discovered from server_url if not provided.
      - `registration_url` string — Dynamic client registration endpoint URL (RFC 7591). Optional - will be discovered from server_url if not provided.
      - `scopes` string[] — OAuth scopes requested. Optional - can be discovered from server_url if not provided. Example: ["read", "write"]
    - `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
    - `allow_on_all_virtual_keys` boolean — 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` object — TLS configuration for HTTP and SSE connections. Not applicable to stdio or inprocess connection types.
      - `insecure_skip_verify` boolean — 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` string — 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` string[] — 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.
    - `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. Discarded after the create call — not persisted. Mirrors how the admin's temp OAuth token is used for `per_user_oauth` setup.
    - `stdio_config` object, required — STDIO configuration (required for STDIO connection type)
      - `command` string — Executable command to run
      - `args` string[] — Command line arguments
      - `envs` string[] — Environment variables required

## Response `200`

MCP client added successfully

- SuccessResponse — Generic success response
  - `status` string
  - `message` string

## 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)