MCP connections

client.mcpConnections saves the remote MCP servers your agents can call, along with their credentials. You create a connection once, then give it to any agent through the agent's mcpConnectionIds. To learn how MCP tools reach your agent, read MCP tools.

const connection = await client.mcpConnections.create({
  name: "Issue tracker",
  url: "https://mcp.example.com/mcp",
  authType: "bearer",
  bearerToken: process.env.MCP_BEARER_TOKEN!,
});

await client.agents.update({ agentId, mcpConnectionIds: [connection.id] });

Every method takes one input object and accepts an optional abortSignal. Credentials are never returned; responses show at most four characters in credentialFragment.

Authentication types

authType picks which credential fields the connection needs:

If the check fails, nothing is saved and the call throws. The url must be http or https without credentials, a query string, or a fragment. Servers must speak Streamable HTTP.

Available operations

Methods

create()

Saves a connection and, except for authorization-code OAuth, checks that the server answers.

Signature: create(input: CreateMcpConnectionBody & ResourceRequestOptions): Promise<McpConnectionResponse>

const connection = await client.mcpConnections.create({
  name: "Analytics",
  url: "https://mcp.example.com/mcp",
  authType: "oauth_client_credentials",
  clientId: process.env.MCP_CLIENT_ID!,
  clientSecret: process.env.MCP_CLIENT_SECRET!,
  scope: "tools.read",
});

Returns McpConnectionResponse with status: "connected", or "needs_auth" for authorization-code OAuth. Your tenant can hold up to 50 connections. Errors: validation_failed, mcp_connection_name_conflict, mcp_connection_limit_reached, and the check errors.

list()

Lists your connections.

Signature: list(input?: ResourceRequestOptions): Promise<McpConnectionsResponse>

const { mcpConnections } = await client.mcpConnections.list();

Returns { mcpConnections: McpConnectionResponse[] }.

get()

Reads one connection.

Signature: get(input: { mcpConnectionId: string } & ResourceRequestOptions): Promise<McpConnectionResponse>

const connection = await client.mcpConnections.get({ mcpConnectionId });

Returns McpConnectionResponse. Errors: validation_failed, not_found.

update()

Renames a connection. To change its URL or credentials, use reconnect().

Signature: update(input: UpdateMcpConnectionBody & { mcpConnectionId: string } & ResourceRequestOptions): Promise<McpConnectionResponse>

const connection = await client.mcpConnections.update({
  mcpConnectionId,
  name: "Production issue tracker",
});

Returns McpConnectionResponse. Errors: validation_failed, mcp_connection_name_conflict, not_found.

delete()

Deletes a connection and revokes any OAuth tokens it holds.

Signature: delete(input: { mcpConnectionId: string } & ResourceRequestOptions): Promise<void>

await client.mcpConnections.delete({ mcpConnectionId });

Remove it from every agent's mcpConnectionIds first, or the call fails with mcp_connection_in_use. Errors: validation_failed, not_found, mcp_connection_in_use.

test()

Connects to the server with the saved credentials and lists its tools.

Signature: test(input: { mcpConnectionId: string } & ResourceRequestOptions): Promise<McpConnectionTestResponse>

const result = await client.mcpConnections.test({ mcpConnectionId });
if (result.ok) {
  console.log(result.server.name, result.toolNames);
} else {
  console.error(result.error.code, result.error.message);
}

A failed check returns ok: false instead of throwing, and updates the connection's status: "connected" on success, "needs_auth" when the credentials are rejected, "error" otherwise. Testing an OAuth connection may refresh its token. Returns McpConnectionTestResponse. Errors: not_found.

connect()

Starts the sign-in for an authorization-code OAuth connection and returns a URL to open in a browser.

Signature: connect(input: { mcpConnectionId: string } & ResourceRequestOptions): Promise<McpConnectionOauthConnectResponse>

const dashboardClient = new BlazingAgents({ apiKey: dashboardUserAccessToken });
const { authorizationUrl } = await dashboardClient.mcpConnections.connect({ mcpConnectionId });

The URL opens the connection's page in the Blazing Agents dashboard, where the person signs in to the MCP server's provider and approves access. The connection then turns "connected". This call needs a signed-in dashboard user's access token in place of the API key; a client built with an API key gets unauthorized. Most apps send the person to the dashboard to finish OAuth instead.

Returns McpConnectionOauthConnectResponse. Errors: unauthorized, validation_failed.

reconnect()

Replaces a connection's URL, authentication type, and credentials, and keeps its name and ID.

Signature: reconnect(input: ReconnectMcpConnectionBody & { mcpConnectionId: string } & ResourceRequestOptions): Promise<McpConnectionReconnectResult>

const result = await client.mcpConnections.reconnect({
  mcpConnectionId,
  url: "https://mcp.example.com/v2/mcp",
  authType: "bearer",
  bearerToken: process.env.MCP_BEARER_TOKEN!,
});
console.log(result.status);

Takes the create() fields except name. Blazing Agents checks the new settings the same way as create() and keeps the old ones if the check fails. Agents that use the connection pick up the change without an update. Returns McpConnectionReconnectResult. Errors: validation_failed, not_found, mcp_connection_stale_credential_version (someone changed it at the same time; reload and retry), and the check errors.

Response types

McpConnectionResponse

McpConnectionsResponse is { mcpConnections: McpConnectionResponse[] }.

McpConnectionTestResponse

type McpConnectionTestResponse =
  | {
      ok: true;
      latencyMs: number;
      server: { name: string; version: string };
      toolCount: number;
      toolNames: string[];
    }
  | {
      ok: false;
      error: { code: McpConnectionTestErrorCode; message: string };
    };

type McpConnectionTestErrorCode =
  | "MCP_CONNECTION_AUTHENTICATION_FAILED"
  | "MCP_CONNECTION_INVALID"
  | "MCP_CONNECTION_UNREACHABLE"
  | "MCP_CONNECTION_DISCOVERY_FAILED";

McpConnectionReconnectResult

interface McpConnectionReconnectResult {
  status: "connected" | "needs_auth";
  connection: McpConnectionResponse;
}

McpConnectionOauthConnectResponse

interface McpConnectionOauthConnectResponse {
  authorizationUrl: string;
}

Errors

Failures throw BlazingAgentsError. create() and reconnect() throw these when the server check fails:

Other connection codes:

Next

• MCP tools
• Agents reference