Command Reference

brainbase mcp

Inspect the MCP servers attached to the agent bound to the current folder. Both commands are read-only. They answer different questions: 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. 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 --json

text

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

Authorize OAuth-backed servers in the web app; the CLI cannot run that flow yet.

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.

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
`--json`	Emit `{ linked, agent_id, servers[] }` and nothing else. An unlinked folder 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.

Authorizing still needs the web app

The CLI can report that an OAuth-backed server needs authorizing, but does not yet run the authorization flow itself. Connect those servers in the web app.

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.