Command Reference

brainbase mcp

Inspect and authorize the MCP servers attached to an agent — the one bound to the current folder, or the one --agent <id> names. list reports what the cloud holds — whether a server is authorized and until when — while check dials the servers to see whether they respond right now. Both are read-only. connect runs the OAuth authorization for one server from the terminal. See Connecting integrations for how MCP authorization fits into the rest of an agent's wiring.

brainbase mcp list

Show every MCP server configured on the agent with its authorization and health state. Tokens are never returned — only whether one exists and when it lapses.

bash

brainbase mcp list
brainbase mcp list --agent <agent-id>
brainbase mcp list --json

text

✓ linear  remote · authorized · expires in 22h
! notion  remote · needs authorization
✗ sentry  remote · authorization expired — reconnect
! grafana  remote · authorized · unreachable
· filesystem  local · disabled

Run `brainbase mcp connect <name>` to authorize a server.

Each line shows the server name, whether it is reached over the network (remote) or spawned locally (local), whether it is disabled, and then two independent things — because a server can hold a perfectly good token and still be down. A server the agent inherits from an orchestration is marked inherited from <orchestration>. The footer appears only when some server needs authorizing or has expired.

Authorization is whether Brainbase holds credentials for it:

State	Meaning
(none shown)	The server needs no OAuth — a static header, or a local command.
`needs authorization`	OAuth-backed and never authorized.
`authorized`	A live token, with its expiry where one is known.
`authorization expired — reconnect`	The token lapsed, or a refresh failed.

Reachability is what the last connectivity check found, and appears only when that check did not succeed — unreachable, connection error, last check failed to authenticate, last check saw an expired token, last check inconclusive, or last check: <status> for anything newer. grafana above is authorized *and* broken, which is exactly the case a single tick would hide.

Flag	Description
`--agent <id>`	Act on this agent instead of the one linked in this folder. Given with no value, it is an error rather than a fall back to the folder.
`--json`	Emit `{ linked, agent_id, servers[] }` and nothing else. An unlinked folder with no `--agent` emits `{ linked: false, servers: [] }` — no `agent_id`, and no `error` — and exits non-zero.

Server URLs are reduced to origin and path, and local commands to the executable, so a credential carried in a query string or a --token flag does not end up in CI logs. last_error is redacted the same way mcp check redacts it.

The JSON form carries auth (none, oauth_required, oauth_connected, or oauth_expired) plus last_status and oauth_token_expires_at, so a scheduled job can warn before a refresh lease lapses instead of finding out when a tool stops working. Failures print {"error": "…"} on stdout rather than plain text on stderr. The command exits non-zero when the folder is not linked and no --agent is given.

brainbase mcp connect <name>

Authorize an OAuth-backed server from the terminal. The command asks Brainbase for a single-use link bound to you and to that server, prints it, opens it in your browser, and waits while you approve on the provider's consent screen. The tokens are stored by Brainbase, as they are when you authorize in the web app; the terminal never sees them.

bash

brainbase mcp connect notion
brainbase mcp connect notion --agent <agent-id>
brainbase mcp connect notion --no-open     # print the link, don't open it
brainbase mcp connect notion --no-wait     # print the link and exit
brainbase mcp connect notion --json        # {link_id, url, expires_at, server}

text

Open this link to authorize notion:

  https://app.brainbaselabs.com/…

The link works once and expires in 10 minutes.
Opening your browser…
✔ notion authorized. Your agent can use it on its next turn.

Flag	Description
`--agent <id>`	Act on this agent instead of the one linked in this folder.
`--no-open`	Print the link without opening a browser. Implied when there is no terminal, since nobody is at this machine's browser either — hand the link to someone who is.
`--no-wait`	Print the link and exit `0` instead of waiting. Check the outcome later with `mcp list`.
`--json`	Print `{ link_id, url, expires_at, server }` and exit `0` straight away, without opening a browser or waiting. Failures print `{"error": "…"}` on stdout.

The server is looked up before any link is made, so a typo, a server that needs no OAuth, or one the agent cannot authorize is answered without minting a link nobody can use. An unknown name lists the servers the agent does have. Running it against a server that is already authorized is allowed: that is how you replace its grant.

Two kinds of server are refused

A server the agent inherits from an orchestration is refused, because it is the orchestration's to authorize — do that in the web app. A server that does not use OAuth (auth is none in mcp list --json) is refused too, since there is nothing to authorize.

The link works once and expires ten minutes after it is made. Ctrl-C stops the wait but not the link: finishing in the browser afterwards still authorizes the server, until the link expires. If another authorization for the same server starts before you finish, this one is cancelled and the command says so.

Code	Meaning
`0`	The server was authorized — or, with `--json` or `--no-wait`, the link was printed.
`1`	The authorization failed, was declined in the browser, or was superseded by another one; the link expired; the server was refused; or Brainbase stopped answering while the command waited.
`130`	You interrupted the wait with Ctrl-C. The link keeps working until it expires.

brainbase mcp check

Probe every enabled server through the Brainbase proxy and report whether it answers. This runs automatically during sandbox bootstrap, and is the command to reach for when a tool call fails rather than a tool being missing.

bash

brainbase mcp check
brainbase mcp check --json

Flag	Description
`--json`	Emit `{ check_status, servers[] }` on a single line.

The exit code reflects whether the *check ran*, not whether the servers are healthy: 0 whenever the probe completed, even if every server is unhealthy, and 1 only when the check could not run at all. URLs are stripped and known credential shapes are redacted; an opaque value under a name the redactor does not recognise can still appear.