MCP servers

BMA connects agents to MCP servers, discovers their tools, and exposes them to the model as mcp__{server}__{tool}.

Remote (URL) servers

Managed Agents API (/v1)
Native API

{
  "mcp_servers": [{
    "type": "url",
    "name": "linear",
    "url": "https://mcp.linear.app/mcp",
    "bma_auth": {"type": "bearer", "secret_id": "sec_..."}
  }]
}

bma_auth is a BMA extension: Anthropic’s shape has no secret reference. Types are bearer, oauth and sigv4 (sigv4 also requires service and region). Only secret_id is echoed back.

mcp:
  linear:
    url: https://mcp.linear.app/mcp
    auth:
      type: oauth
      secret_id: sec_...
    permission:
      mode: always_ask
    tools:
      get_issue:
        permission:
          mode: always_allow

default_enabled: false exposes only listed tools; deferred: true keeps tools out of the context until tool_search loads them.

The credential lives in a project secret; configs only reference sec_… ids. MCP tools default to always_ask.

Servers on the machine (stdio)

An MCP server can also run on the session’s machine as a stdio process (connection origin environment). BMA starts the server on the machine with only its configured environment plus server-resolved secrets (secret values never appear in the config), and bridges it to the agent over the executor’s MCP channel. Because it needs a machine, the first use creates the session’s machine.

When a server fails

A server that fails to initialize is dropped from the tool list. The session gets a session.mcp_server_unavailable event with server_key and reason, and the model is told the same. No session.error is emitted, because clients treat session.error as fatal. The tool list of a running session can be changed with POST /v1/sessions/{id} (agent.mcp_servers).

Get started

Concepts

Executor & brains

Remote (URL) servers

Servers on the machine (stdio)

When a server fails

​Remote (URL) servers

​Servers on the machine (stdio)

​When a server fails

Remote (URL) servers

Servers on the machine (stdio)

When a server fails