MCP tools

Give your agent the tools from any remote MCP server, such as your own internal API or a third-party service. You create a connection once, with its URL and credentials, then attach it to every agent that should use it. Blazing Agents stores the credentials, refreshes OAuth tokens, and discovers the server's tools at the start of every turn.

Connect and attach a server

This example connects a server that needs a bearer token, checks that it exposes a lookup_customer tool, and attaches it to an agent:

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

const test = await client.mcpConnections.test({
  mcpConnectionId: connection.id,
});
if (!test.ok) throw new Error(`${test.error.code}: ${test.error.message}`);
if (!test.toolNames.includes("lookup_customer")) {
  throw new Error("Expected a lookup_customer tool");
}

const agent = await client.agents.get({ agentId });
await client.agents.update({
  agentId,
  mcpConnectionIds: [...new Set([...agent.mcpConnectionIds, connection.id])],
});

The list of connection IDs you send replaces the agent's whole list, so the example adds to the current one. From the next turn, the agent can call lookup_customer. When a chat turn succeeds, the call and its result are saved in the session, so check them there rather than in the agent's reply.

A connection has no on or off switch. Attaching it to an agent is what makes its tools available, and one connection can serve many agents.

Choose how to sign in

The server URL must use HTTPS and cannot contain credentials, a query string, or a fragment.

For every type except oauth_authorization_code, Blazing Agents checks the server before it saves the connection. If the check fails, nothing is saved.

Credentials are write-only. Responses never include bearer tokens, client secrets, or OAuth tokens.

Sign in with an authorization code

A connection that uses oauth_authorization_code starts with status needs_auth. To finish it, a tenant administrator opens the MCP connections page in the dashboard, clicks Connect, and signs in to the MCP server. If the server's authorization server asks for a redirect URL, register https://api.blazingagents.com/v1/mcp/oauth/callback.

The connect() SDK method starts the same flow, but it needs a signed-in dashboard administrator rather than an API key, so an API-key client gets unauthorized.

Check a connection

Each connection has a status: connected, needs_auth, or error. Treat needs_auth as a sign to reconnect.

test() returns the server's identity, response time, and tool names, or a safe error with one of these codes:

• MCP_CONNECTION_AUTHENTICATION_FAILED
• MCP_CONNECTION_INVALID
• MCP_CONNECTION_UNREACHABLE
• MCP_CONNECTION_DISCOVERY_FAILED

Run it again after you change credentials or the server changes, because tools are discovered live on every turn.

What happens during a turn

At the start of each turn, Blazing Agents connects to every attached server and lists its tools. A connection that needs sign-in fails the turn, and so can a server that cannot be reached or a tool that fails. Blazing Agents does not quietly run the turn with fewer tools. MCP tools that require the MCP task protocol are not offered to the agent.

Requests to the server use HTTPS, follow only safe redirects, and have time and size limits. Tool results are size-limited too, and a result that echoes a stored credential is rejected.

Each attachment decides what end-user context the server receives. Turn on forwarding of the turn's userId or selected metadata keys with agents.updateMcpAttachment() (update_mcp_attachment() in Python). The server receives that context as information only; it does not grant access.

Reconnect or delete

reconnect() replaces a connection's URL and credentials under the same ID. With a token or client credentials, the new details are checked first, and the old ones stay in use if the check fails. With an authorization code, the old credentials are dropped right away and the connection returns to needs_auth until someone signs in again.

Agent versions store only the connection ID. Reconnecting therefore changes what older pinned versions use too. You can delete a connection only after every agent has detached it, and restoring a version that names a deleted connection fails.

Production checklist

• Use credentials with the least access the tools need, and keep them out of names, URLs, metadata, tool arguments, and logs.
• Forward userId or metadata only when the server needs it.
• Plan for server errors, timeouts, and a turn that fails because a connection needs sign-in.
• MCP tools follow the same tool approvals as any other tool.
• Review security and credentials.

Next

• Tool approvals to require a decision before an MCP call runs.
• MCP connection methods in the TypeScript SDK and Python SDK.