ExBifrost.Api.MCP (ex_bifrost v0.1.0)

API calls for all endpoints tagged MCP.

Summary

Functions

add_mcp_client(connection, add_mcp_client_request, opts \\ [])

Add 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.

complete_mcp_client_o_auth(connection, id, opts \\ [])

Complete MCP client OAuth flow Completes the OAuth flow for an MCP client after the user has authorized the request. This endpoint should be called after the OAuth provider redirects back to the callback endpoint and the OAuth token has been stored. It retrieves the pending MCP client configuration and establishes the connection with the OAuth-provided credentials.

edit_mcp_client(connection, id, edit_mcp_client_request, opts \\ [])

Edit MCP client Updates an existing MCP client's configuration. Unlike client creation, tool_pricing can be included to set per-tool execution costs since tools are already fetched. Optionally provide vk_configs to manage which virtual keys have access to this MCP server and with which tools. When provided, this fully replaces all existing VK assignments in a single atomic transaction. Set disabled: true to shut down the client's connection and workers without removing it. Set disabled: false to reconnect a previously disabled client.

execute_mcp_tool(connection, execute_tool_request, opts \\ [])

Execute MCP tool Executes an MCP tool and returns the result.

get_mcp_clients(connection, opts \\ [])

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.

get_per_user_headers_flow(connection, id, opts \\ [])

Get per-user-headers submission flow Returns the pending submission flow row plus the live MCP client's schema (required header names + optional admin header names). Used by the /workspace/mcp-sessions/auth?flow=<id>&kind=headers landing page to render the values form. Requires management API authentication via Authorization: Bearer <API key>.

list_mcp_sessions(connection, opts \\ [])

List MCP sessions Returns every per-user MCP authentication artifact visible to the caller — OAuth tokens, header credentials, and pending submission / consent flows. Row visibility is scoped to the caller's identity (Virtual Key, signed-in user, or asserted session ID). Server-level headers / oauth clients are not surfaced here; their credentials live on the MCP client config. When both a credential and a pending flow exist for the same (identity, mcp_client) binding, the credential is returned and the flow is suppressed to avoid duplicate entries.

reauth_mcp_session(connection, id, opts \\ [])

Re-authenticate or edit an MCP session Mints a fresh authentication flow against the same MCP client and identity as the existing row. Two branches based on row type: - OAuth token (any non-orphaned row, typically needs_reauth — but active is also accepted) — opens a fresh upstream OAuth consent flow. Caller is expected to follow authorize_url to the provider; on callback the credential is replaced in place. - Header credential (active or needs_update) — opens a fresh per-user-headers submission flow. Caller follows the same URL field to the Bifrost submission form; on submit the credential is replaced in place. kind: "headers" is set on the response. Refused with 403 if the row is orphaned — a fresh credential wouldn't help; the issue is the identity has lost access to the MCP, which the admin must fix.

reconnect_mcp_client(connection, id, opts \\ [])

Reconnect MCP client Reconnects an MCP client that is in an error or disconnected state.

remove_mcp_client(connection, id, opts \\ [])

Remove MCP client Removes an MCP client from the configuration.

revoke_mcp_session(connection, id, opts \\ [])

Revoke an MCP session Revokes a session by primary key. Accepts these row kinds: - OAuth token rows → hard-deletes the token plus any pending OAuth flow for the same binding (so an in-flight callback can't undo the revoke) - Header credential rows → hard-deletes the credential plus any pending header submission flow for the same binding - Pending per-user-headers flow rows → hard-deletes just the flow Note: pending per-user OAuth flow rows are not revocable by this endpoint — they expire naturally or are cleared when the bound token row is revoked. To cancel a pending OAuth flow, revoke its parent token (if one exists) or wait for expiry. Bifrost does not call the upstream provider's revoke endpoint — revocation is local. Per-user-headers credentials never call upstream.

revoke_per_user_headers_credential(connection, id, opts \\ [])

Revoke a per-user-headers credential Hard-deletes a per-user-headers credential row by primary key. Authorization scoping is enforced server-side — callers may only delete credentials visible to their identity. The unified DELETE /api/mcp/sessions/{id} is the more convenient entry point; this typed endpoint exists for callers that already know they're acting on a header credential row.

submit_per_user_headers_flow(connection, id, mcp_headers_submit_request, opts \\ [])

Submit per-user-headers values Consumes a pending submission flow row: verifies the caller's values against the upstream MCP server, upserts the credential keyed by the flow row's (mode, identity), then deletes the flow row and the bound temp token. Mirrors the OAuth callback's "complete the flow" semantics. Values for any key not in the live per_user_header_keys schema are dropped server-side so a stale UI can't persist deprecated keys.

Functions

add_mcp_client(connection, add_mcp_client_request, opts \\ [])

@spec add_mcp_client(
  Tesla.Env.client(),
  ExBifrost.Model.AddMcpClientRequest.t(),
  keyword()
) ::
  {:ok, ExBifrost.Model.SuccessResponse.t()}
  | {:ok, ExBifrost.Model.BifrostError.t()}
  | {:error, Tesla.Env.t()}

Add 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.

Parameters

connection (ExBifrost.Connection): Connection to server
add_mcp_client_request (AddMcpClientRequest):
opts (keyword): Optional parameters

Returns

{:ok, ExBifrost.Model.SuccessResponse.t} on success
{:error, Tesla.Env.t} on failure

complete_mcp_client_o_auth(connection, id, opts \\ [])

@spec complete_mcp_client_o_auth(Tesla.Env.client(), String.t(), keyword()) ::
  {:ok, ExBifrost.Model.SuccessResponse.t()}
  | {:ok, ExBifrost.Model.BifrostError.t()}
  | {:error, Tesla.Env.t()}

Parameters

connection (ExBifrost.Connection): Connection to server
id (String.t): MCP client ID
opts (keyword): Optional parameters

Returns

{:ok, ExBifrost.Model.SuccessResponse.t} on success
{:error, Tesla.Env.t} on failure

edit_mcp_client(connection, id, edit_mcp_client_request, opts \\ [])

@spec edit_mcp_client(
  Tesla.Env.client(),
  String.t(),
  ExBifrost.Model.EditMcpClientRequest.t(),
  keyword()
) ::
  {:ok, ExBifrost.Model.SuccessResponse.t()}
  | {:ok, ExBifrost.Model.BifrostError.t()}
  | {:error, Tesla.Env.t()}

Parameters

connection (ExBifrost.Connection): Connection to server
id (String.t): MCP client ID
edit_mcp_client_request (EditMcpClientRequest):
opts (keyword): Optional parameters

Returns

{:ok, ExBifrost.Model.SuccessResponse.t} on success
{:error, Tesla.Env.t} on failure

execute_mcp_tool(connection, execute_tool_request, opts \\ [])

@spec execute_mcp_tool(
  Tesla.Env.client(),
  ExBifrost.Model.ExecuteToolRequest.t(),
  keyword()
) ::
  {:ok, ExBifrost.Model.BifrostError.t()}
  | {:ok, ExBifrost.Model.ExecuteMcpTool200Response.t()}
  | {:error, Tesla.Env.t()}

Execute MCP tool Executes an MCP tool and returns the result.

Parameters

connection (ExBifrost.Connection): Connection to server
execute_tool_request (ExecuteToolRequest):
opts (keyword): Optional parameters
- :format (String.t): Format of the tool execution request/response.

Returns

{:ok, ExBifrost.Model.ExecuteMcpTool200Response.t} on success
{:error, Tesla.Env.t} on failure

get_mcp_clients(connection, opts \\ [])

@spec get_mcp_clients(
  Tesla.Env.client(),
  keyword()
) ::
  {:ok, ExBifrost.Model.GetMcpClients200Response.t()}
  | {:ok, ExBifrost.Model.BifrostError.t()}
  | {:error, Tesla.Env.t()}

Parameters

connection (ExBifrost.Connection): Connection to server
opts (keyword): Optional parameters
- :limit (integer()): Maximum number of clients to return (1–100, default 25).
- :offset (integer()): Number of clients to skip.
- :search (String.t): Case-insensitive search by client name.
- :server (String.t): Filter to a single client by its exact client_id.
- :connection_type (String.t): Comma-separated connection types to include (OR semantics).
- :auth_type (String.t): Comma-separated auth types to include (OR semantics).
- :state (String.t): Comma-separated runtime connection states to include (OR semantics), resolved against live engine state. connected matches clients the engine currently reports as connected; disconnected matches everything else.
- :all_virtual_keys (boolean()): When true, include clients that are open to all virtual keys (allow_on_all_virtual_keys). ORs with virtual_keys.
- :virtual_keys (String.t): Comma-separated virtual key IDs; includes clients explicitly assigned to any of them. ORs with all_virtual_keys.
- :code_mode (boolean()): Filter by code-mode clients. Omit for no filter.
- :disabled (boolean()): Filter by disabled status — true returns disabled clients, false returns enabled clients. Omit for no filter.

Returns

{:ok, ExBifrost.Model.GetMcpClients200Response.t} on success
{:error, Tesla.Env.t} on failure

get_per_user_headers_flow(connection, id, opts \\ [])

@spec get_per_user_headers_flow(Tesla.Env.client(), String.t(), keyword()) ::
  {:ok, ExBifrost.Model.McpHeadersFlowDetail.t()}
  | {:ok, ExBifrost.Model.BifrostError.t()}
  | {:error, Tesla.Env.t()}

Parameters

connection (ExBifrost.Connection): Connection to server
id (String.t): Flow row ID
opts (keyword): Optional parameters

Returns

{:ok, ExBifrost.Model.McpHeadersFlowDetail.t} on success
{:error, Tesla.Env.t} on failure

list_mcp_sessions(connection, opts \\ [])

@spec list_mcp_sessions(
  Tesla.Env.client(),
  keyword()
) ::
  {:ok, ExBifrost.Model.McpSessionsListResponse.t()}
  | {:ok, ExBifrost.Model.BifrostError.t()}
  | {:error, Tesla.Env.t()}

Parameters

connection (ExBifrost.Connection): Connection to server
opts (keyword): Optional parameters

Returns

{:ok, ExBifrost.Model.McpSessionsListResponse.t} on success
{:error, Tesla.Env.t} on failure

reauth_mcp_session(connection, id, opts \\ [])

@spec reauth_mcp_session(Tesla.Env.client(), String.t(), keyword()) ::
  {:ok, ExBifrost.Model.McpSessionReauthResponse.t()}
  | {:ok, nil}
  | {:ok, ExBifrost.Model.BifrostError.t()}
  | {:error, Tesla.Env.t()}

Parameters

connection (ExBifrost.Connection): Connection to server
id (String.t): Session row ID (OAuth token or header credential)
opts (keyword): Optional parameters

Returns

{:ok, ExBifrost.Model.McpSessionReauthResponse.t} on success
{:error, Tesla.Env.t} on failure

reconnect_mcp_client(connection, id, opts \\ [])

@spec reconnect_mcp_client(Tesla.Env.client(), String.t(), keyword()) ::
  {:ok, ExBifrost.Model.SuccessResponse.t()}
  | {:ok, ExBifrost.Model.BifrostError.t()}
  | {:error, Tesla.Env.t()}

Reconnect MCP client Reconnects an MCP client that is in an error or disconnected state.

Parameters

connection (ExBifrost.Connection): Connection to server
id (String.t): MCP client ID
opts (keyword): Optional parameters

Returns

{:ok, ExBifrost.Model.SuccessResponse.t} on success
{:error, Tesla.Env.t} on failure

remove_mcp_client(connection, id, opts \\ [])

@spec remove_mcp_client(Tesla.Env.client(), String.t(), keyword()) ::
  {:ok, ExBifrost.Model.SuccessResponse.t()}
  | {:ok, ExBifrost.Model.BifrostError.t()}
  | {:error, Tesla.Env.t()}

Remove MCP client Removes an MCP client from the configuration.

Parameters

connection (ExBifrost.Connection): Connection to server
id (String.t): MCP client ID
opts (keyword): Optional parameters

Returns

{:ok, ExBifrost.Model.SuccessResponse.t} on success
{:error, Tesla.Env.t} on failure

revoke_mcp_session(connection, id, opts \\ [])

@spec revoke_mcp_session(Tesla.Env.client(), String.t(), keyword()) ::
  {:ok, nil} | {:ok, ExBifrost.Model.BifrostError.t()} | {:error, Tesla.Env.t()}

Parameters

connection (ExBifrost.Connection): Connection to server
id (String.t): Session / credential / flow row ID
opts (keyword): Optional parameters

Returns

{:ok, nil} on success
{:error, Tesla.Env.t} on failure

revoke_per_user_headers_credential(connection, id, opts \\ [])

@spec revoke_per_user_headers_credential(Tesla.Env.client(), String.t(), keyword()) ::
  {:ok, nil} | {:ok, ExBifrost.Model.BifrostError.t()} | {:error, Tesla.Env.t()}

Parameters

connection (ExBifrost.Connection): Connection to server
id (String.t): Credential row primary key
opts (keyword): Optional parameters

Returns

{:ok, nil} on success
{:error, Tesla.Env.t} on failure

submit_per_user_headers_flow(connection, id, mcp_headers_submit_request, opts \\ [])

@spec submit_per_user_headers_flow(
  Tesla.Env.client(),
  String.t(),
  ExBifrost.Model.McpHeadersSubmitRequest.t(),
  keyword()
) ::
  {:ok, nil}
  | {:ok, ExBifrost.Model.BifrostError.t()}
  | {:ok, ExBifrost.Model.McpHeadersSubmitResponse.t()}
  | {:error, Tesla.Env.t()}

Parameters

connection (ExBifrost.Connection): Connection to server
id (String.t): Flow row ID
mcp_headers_submit_request (McpHeadersSubmitRequest):
opts (keyword): Optional parameters

Returns

{:ok, ExBifrost.Model.McpHeadersSubmitResponse.t} on success
{:error, Tesla.Env.t} on failure