MCP tools

The Model Context Protocol (MCP) is an open protocol for serving tools to AI applications. Brain connects to remote MCP servers over Streamable HTTP with the official MCP Go SDK (pinned in go.mod), so you can give sessions tools from an MCP server you already run. MCP tools go through the same tenant allowlist, input validation, timeout, and output limits as HTTP tools.

What Brain supportsCopy Anchor Link

• Transport: Remote MCP servers over Streamable HTTP, or installed stdio commands through the Go application SDK.
• Authentication: API keys sent as bearer tokens from the environment variable named in token_env.
• Results: Tool calls that return text, images, or structured content.
• Progress: Progress notifications streamed during a call as tool.progress events.

Discover toolsCopy Anchor Link

Run cmd/mcp-tools to turn tools from an MCP server into Brain tool bindings:

go run ./cmd/mcp-tools -url https://YOUR_SERVER/mcp -token-env MCP_API_KEY -tenant local -tools search,fetch

The command connects to the server, reads its tool list, and prints a JSON array with one binding for each named tool. It fails if a named tool doesn't exist or if discovery takes longer than 30 seconds. The output looks like this:

[
  {
    "name": "search",
    "description": "Search the knowledge base.",
    "input_schema": { "type": "object", "properties": { "query": { "type": "string" } }, "required": ["query"] },
    "url": "https://YOUR_SERVER/mcp",
    "mcp_tool": "search",
    "token_env": "MCP_API_KEY",
    "tenants": ["local"],
    "timeout_seconds": 300,
    "max_output_bytes": 1048576
  }
]

Review the descriptions and schemas, then copy the bindings into the tools array of your host config. Bindings are static: a tool's description and schema change only when you edit the config and restart Brain, and discovery never changes the tools of a running session.

Configure an MCP bindingCopy Anchor Link

An MCP binding is a regular tool binding with one extra field, mcp_tool:

• name is the name the model sees. Rename tools to avoid collisions, for example docs_search for a search tool.
• mcp_tool is the tool's name on the MCP server.
• url is the server's MCP endpoint.
• token_env names the environment variable with the server's API key. Brain sends it as a bearer token on every request to the server.

tenants, timeout_seconds, max_output_bytes, and output_schema work as they do for HTTP tools. inspect_session applies to HTTP and SSE tools; Brain rejects a host config that sets it on an MCP binding.

How Brain calls an MCP toolCopy Anchor Link

1. Check the call. Brain confirms that the tool is allowed for the session's tenant and validates the arguments against input_schema.
2. Open an MCP session. Brain starts a new MCP session with the server for this call, over pooled HTTP connections. A separate MCP session per call keeps server-side session state from crossing tenants or calls, at the cost of one initialization round trip per call.
3. Call the tool. Brain sends the arguments and puts the session's identity in _meta["brain.dev/scope"] as tenant_id, session_id, and call_id. The call ID is also the progress token.
4. Stream progress. Each progress notification from the server becomes a live-only tool.progress event.
5. Return the result. Brain converts the result into a tool.result event, returns it to the harness, and closes the MCP session.

Results and errorsCopy Anchor Link

Brain converts MCP results into Brain content blocks:

When a call fails, the tool.result has is_error: true:

Brain sends each MCP call at most once. With an unknown outcome, the model can use another tool to check the resource. Interrupting the session or reaching the timeout cancels the request; whether the work stops on the server depends on the server.

Next stepsCopy Anchor Link