MCP connections

An MCP Connection is a tenant-level Agent extension for reaching a remote MCP server over Streamable HTTP, including its managed credential. Use one when an Agent needs remote Tools that should remain owned and operated outside Blazing Agents.

Ownership, authentication, and status

Connections belong to the tenant and are reusable across its Agents; they carry no Attribution. The public authentication modes are none, bearer, oauth_authorization_code, and oauth_client_credentials.

Public responses expose the authentication type, connected, needs_auth, or error status, a credential fragment of at most four characters or null, OAuth issuer/resource and expiry metadata where applicable, and lastAuthErrorCode. They never return the bearer token, OAuth client secret, access token, refresh token, or stored credential bundle. A connection test returns either ok: true with latency, server identity, count, and Tool names, or ok: false with a sanitized message and one code: MCP_CONNECTION_AUTHENTICATION_FAILED, MCP_CONNECTION_INVALID, MCP_CONNECTION_UNREACHABLE, or MCP_CONNECTION_DISCOVERY_FAILED.

Connection lifecycle

Creating a none, bearer, or Client Credentials connection validates it before returning connected; a validation failure removes the staged record. An Authorization Code connection starts as needs_auth. connect() returns a short-lived Blazing Agents continuation URL for a tenant-admin browser flow, and the callback records success without exposing upstream errors in its redirect.

test() performs live discovery and writes connected, needs_auth for authentication failure, or error for other validation failures. reconnect() replaces the URL and authentication material: Authorization Code returns to needs_auth, while the other modes validate before becoming connected. The public update changes only the name. Delete is blocked while an Agent remains attached; upstream OAuth client revocation after local deletion is best effort.

Attach a connection to an Agent

Set MCP_SERVER_URL to a reachable, non-secret test server that supports Streamable HTTP.

import { BlazingAgents } from "@blazing-agents/sdk";

const client = new BlazingAgents({
  apiKey: process.env.BLAZING_AGENTS_API_KEY!,
});
const connection = await client.mcpConnections.create({
  name: "Local test tools",
  url: process.env.MCP_SERVER_URL!,
  authType: "none",
});
const test = await client.mcpConnections.test(connection.id);
if (!test.ok) throw new Error(`${test.error.code}: ${test.error.message}`);

const agent = await client.agents.create({
  name: "MCP test Agent",
  mcpConnectionIds: [connection.id],
});
const attachments = await client.agents.listMcpAttachments(agent.id);
console.log(test.ok, attachments.mcpAttachments[0]?.mcpConnectionId);

The test prints true and the attached connection ID. Membership in mcpConnectionIds enables the attachment; there is no separate enabled field. Attachment settings independently control whether the Turn's userId and named metadata keys are forwarded, and do not change connection ownership.

Runtime Tool exposure

At Turn startup, the runtime opens each attached connection, discovers its Tools, validates their schemas and limits, and exposes namespaced Tool keys to the Agent. Connections in needs_auth fail closed, required MCP Task Tools are not exposed, and one connection setup or Tool failure can fail the Turn rather than silently reducing its capabilities.

Outbound requests use the platform's fixed network policy. Production fetch accepts HTTPS; an explicit local-test setting can permit loopback HTTP. It rejects credentials in URLs and private or otherwise denied addresses, revalidates redirects, bounds time and response size, and strips sensitive headers on allowed cross-origin redirects. Tool definitions and results are size-bounded, remote metadata is removed from model-facing results, credential echoes are rejected, and runtime failures use sanitized messages.

Production considerations

• Follow the platform's security and credential boundaries. Use the least-privileged bearer token or OAuth client and never put a usable credential in names, URLs, metadata, Tool arguments, or logs.
• Keep Authorization Code continuation and callback handling in the tenant-admin browser flow; do not expose setup URLs to end-users.
• Treat needs_auth as a reconnect signal. A runtime authentication failure updates status and does not turn the credential into Agent-visible data.
• Forward userId or metadata only when the remote server needs it, and remember that forwarded Attribution is context, not authorization.
• Expect discovery, timeout, cancellation, remote application, and cleanup failures; test a connection after credential or server changes.

Related guides

• Connect an MCP server

Reference

• TypeScript SDK: MCP connections and Agent MCP attachments
• REST API: MCP connections, MCP OAuth, and Agent MCP attachments