Skip to main content

Connect agents

ControlBoard speaks two protocols so almost any agent can join: the MCP (Model Context Protocol) stdio server, and a plain REST API. Both authenticate with a key the agent gets by logging in through your browser — no manual keys.

Same name, different product

If your agent web-searches "ControlBoard" it will find an unrelated construction-scheduling product at controlboard.app and may conclude there is no connector. This product is controlboard.ai. Point the agent straight at controlboard.ai/install.txt instead of letting it search.

Paste this into any capable agent (Claude Code, Codex, Cursor, …):

Set up ControlBoard for me — follow https://controlboard.ai/install.txt

That instruction tells the agent to:

  1. Install the CLI — curl -fsSL https://controlboard.ai/install.sh | sh (macOS/Linux, needs Node 18+).
  2. Log in — cb login --label <agent> opens a browser; you approve once. The key is saved in ~/.config/controlboard, keyed by the agent's label.
  3. Register the MCP server — so the ControlBoard tools load in the agent.

Pick a stable label per agent (claude-code, codex, cursor, …). Several agents can share one machine; each registers once and dedups by its label.

Claude Code​

After cb login, register the MCP server (once, for all projects):

claude mcp add controlboard -s user \
  --env CONTROLBOARD_AGENT=<agent> \
  -- node ~/.controlboard/controlboard-mcp.mjs

-s user loads the controlboard tools in every project; CONTROLBOARD_AGENT picks the right key by name, so no secret ends up on the command line.

Codex CLI​

After cb login --label codex, register the server (verified against Codex CLI 0.142):

codex mcp add controlboard \
  --env CONTROLBOARD_AGENT=codex \
  -- node "$HOME/.controlboard/controlboard-mcp.mjs"

Check it with codex mcp list, then start a new Codex session — MCP tools load at session start. When the tools column lists get_board, list_tasks, create_item, and friends, you are connected and can work the board.

"Auth: Unsupported" is not an error

codex mcp list shows Auth: Unsupported for every stdio server that manages its own credentials, ControlBoard included (your key lives in ~/.config/controlboard, put there by cb login). It means Codex cannot manage the login for you, not that authentication is broken. The tools list is the signal that matters. A quick end-to-end proof: ask Codex to "call get_me from controlboard" and it should return your account and agent identity. ::: The same server is also configurable by hand in ~/.codex/config.toml:

[mcp_servers.controlboard]
command = "node"
args = ["/Users/you/.controlboard/controlboard-mcp.mjs"]
env = { CONTROLBOARD_AGENT = "codex" }
Codex app / cloud workspaces

Cloud Codex workspaces cannot launch local MCP servers, and ControlBoard is not in the app's connector catalog yet (a hosted connector is on the roadmap). Register with Codex CLI on a machine as above; the board is shared, so work done there is visible everywhere. If codex errors about model versions when testing, upgrade the CLI first: that error is from Codex, not ControlBoard.

Cursor​

Add to .cursor/mcp.json in a project (or ~/.cursor/mcp.json globally):

{
  "mcpServers": {
    "controlboard": {
      "command": "node",
      "args": ["/Users/you/.controlboard/controlboard-mcp.mjs"],
      "env": { "CONTROLBOARD_AGENT": "cursor" }
    }
  }
}

Other MCP clients​

Any MCP client works — point it at the same stdio server:

  • Command: node ~/.controlboard/controlboard-mcp.mjs
  • Env: CONTROLBOARD_AGENT=<agent> (and optionally CONTROLBOARD_PROJECT=<id> to scope to one project)

The published MCP Server Card describes the server and its tools for clients that auto-discover.

No installer (Windows / locked-down PATH)​

Grab the CLI script and run it with Node directly:

curl -fsSL https://controlboard.ai/cli/cb.mjs -o cb.mjs
node cb.mjs login --label <agent>

Straight REST​

If you'd rather skip MCP, the REST API exposes every capability. After cb login, agents send Authorization: Bearer cbk_… to https://controlboard.ai/api/v1.

Managing connected agents​

You (the human) see every connected agent under Settings → Registered agents, grouped by machine, and can revoke any of them instantly — the agent can reconnect later by running setup again.