MCP connections

client.mcpConnections manages tenant-level remote Streamable HTTP MCP Connections. Attach connection IDs to an Agent through its configuration, then manage forwarding through MCP Attachments. CRUD, test, and reconnect operations are available to ordinary API-key clients.

Overview

Authentication is a discriminated union: none; bearer with bearerToken; oauth_authorization_code with an optional client ID/secret pair and scope; or oauth_client_credentials with required client ID/secret and optional scope. URLs must be HTTP(S) without credentials, query, or fragment.

The SDK normally authenticates with an API key. The authorization-code connect() route is the exception: it requires a Tenant admin session carrying a Supabase Auth JWT (authUserId), and an API-key SDK call receives HTTP 403. Complete that browser authorization through the authenticated application control plane; the backend SDK intentionally has no option for supplying a second credential.

Methods

`create()`

create(body: CreateMcpConnectionBody): Promise<McpConnectionResponse> — POST /v1/mcp-connections. Requires name, url, and the auth-specific fields. Authorization-code OAuth is created as needs_auth; none, bearer, and client-credentials inputs are validated before returning connected, and failed validation removes the staged record.

`list()`

list(): Promise<McpConnectionsResponse> — GET /v1/mcp-connections.

`get()`

get(id: string): Promise<McpConnectionResponse> — GET /v1/mcp-connections/:id.

`update()`

update(id: string, body: UpdateMcpConnectionBody): Promise<McpConnectionResponse> — PATCH /v1/mcp-connections/:id. The body is { name?: string }, validated to require the name; only that field is mutable without reconnecting.

`delete()`

delete(id: string): Promise<void> — DELETE /v1/mcp-connections/:id.

`test()`

test(id: string): Promise<McpConnectionTestResponse> — POST /v1/mcp-connections/:id/test. Returns live server/tool details or a typed failure and persists the resulting lifecycle state: success sets connected and clears lastAuthErrorCode, authentication failure sets needs_auth, and other validation failure sets error. OAuth validation can also persist refreshed credentials.

`connect()`

connect(id: string): Promise<{ authorizationUrl: string }> — POST /v1/mcp-connections/:id/connect. This method exists in the public SDK contract, but an ordinary API-key client cannot successfully call it: the route requires a Tenant admin JWT and otherwise returns HTTP 403. The returned application URL starts the authorization-code browser continuation described by MCP OAuth.

`reconnect()`

reconnect(id: string, body: ReconnectMcpConnectionBody): Promise<McpConnectionReconnectResult> — POST /v1/mcp-connections/:id/reconnect. Replaces URL/auth credentials. Authorization-code OAuth returns needs_auth and then requires the admin-session connect() flow; none, bearer, and client-credentials reconnects validate first and return connected.

Types

Responses expose no secret, only credential fragment, status (connected, needs_auth, or error), last auth error, OAuth issuer/resource, token expiry, and timestamps. Tests discriminate on ok; reconnect discriminates on status. See objects and schemas.

Errors

Invalid URLs or incomplete auth pairs are invalid_request. Connection test failures are normally returned as ok: false with MCP-specific error codes. See errors.

Example

import { BlazingAgents, BlazingAgentsError } from "@blazing-agents/sdk";
const client = new BlazingAgents({ apiKey: process.env.BLAZING_AGENTS_API_KEY! });
const mcpServerUrl = process.env.MCP_SERVER_URL;
if (!mcpServerUrl) throw new Error("MCP_SERVER_URL is required");

const connection = await client.mcpConnections.create({
  name: "Issue tracker",
  url: mcpServerUrl,
  authType: "none",
});
try {
  await client.mcpConnections.connect(connection.id);
} catch (error) {
  if (!(BlazingAgentsError.isInstance(error) && error.status === 403)) {
    throw error;
  }
}
await client.mcpConnections.list();
await client.mcpConnections.get(connection.id);
await client.mcpConnections.update(connection.id, { name: "Issue tracker tools" });
const test = await client.mcpConnections.test(connection.id);
const reconnected = await client.mcpConnections.reconnect(connection.id, {
  authType: "none",
  url: mcpServerUrl,
});
console.log(test.ok, reconnected.status);
await client.mcpConnections.delete(connection.id);

The connect() call demonstrates the expected API-key boundary: authorization-code setup requires a Tenant admin session, so this backend client handles the resulting HTTP 403 without treating another failure as expected.

On this page