Connect Codex to Clearly.
Three ways, one workspace. Point OpenAI Codex at Clearly’s hosted MCP server for the company brain + canvas as native tools, run the Beehaven CLI so Codex can build headlessly, or install the Mac app that bundles both and runs Codex on your own login. Codex registers remote MCP servers in its config file, so its MCP setup is a short edit rather than a one-liner — but every path lands on the same workspace.
Which connection do I want?
They compose — you can run all three at once. MCP gives Codex the company brain as tools; the CLI is the most direct route onto the canvas; the Mac app is the no-setup way to get the daemon the CLI needs.
| Path | Best for | Setup | Runs on |
|---|---|---|---|
| MCP (hosted) | Company brain + canvas as native clearly_* tools. Read/write org context, drive compositions. | Add to ~/.codex/config.toml, then codex mcp login (OAuth). | Clearly's hosted relay — Codex reaches out. |
| The Mac app | Zero-setup: the daemon the CLI needs, auto-running + signed in. Plus an in-app BYOK Codex room. | Download the DMG, sign in. | A local daemon it spawns for you — and your own ~/.codex login. |
| The CLI (Beehaven) | Headless canvas builds, scripting, any OS. Codex shells out to `beehaven`. | One-line install + a daemon you own. | A local daemon that holds the relay connection. |
The mental model: MCP and the CLI put Clearly inside Codex (as tools, or as a command it runs). The Mac app is the desktop home — it runs the daemon the CLI depends on, and hosts a room where Codex runs on your own login. MCP needs no daemon; the CLI does; the Mac app is the no-setup way to get one.
Option A · MCP — the company brain as tools
Clearly is an MCP server. Codex connects out to it over OAuth and your company brain + the canvas show up as native tools. Nothing to deploy; the server is hosted at relay.clearly.sh/mcp.
1 · The endpoint
Hosted — there is nothing to run or self-host.
https://relay.clearly.sh/mcp
2 · Register it with Codex
Codex adds REMOTE servers through its config file — `codex mcp add` is for local stdio commands. So write the block, then log in.
npm install -g @openai/codex # or: brew install codex
[mcp_servers.clearly] url = "https://relay.clearly.sh/mcp" auth = "oauth" # OAuth is the default for remote servers
codex mcp login clearly # browser OAuth sign-in codex mcp list # confirm it's registered
Opens the browser — no token to mint, export, or paste. Scopes are granted here; re-run to widen them.
On an older Codex that ignores remote servers, either upgrade, or enable the streamable-HTTP client by adding a features block above the server entry: [features] then experimental_use_rmcp_client = true.
3 · Scopes
Codex requests the scopes Clearly advertises at sign-in. Re-run codex mcp login to change them.
rpc:read · rpc:write · admin
rpc:read — search + read. rpc:write — also write documents, schedule wakes, create boards/tickets. admin — owner-only.
4 · Verify
Confirm Codex can reach the brain. If the first call is slow, bump startup_timeout_sec in the server block.
Start a Codex session and ask it to use the tools:
> Map my Clearly workspace's brain using the clearly MCP tools.
If Codex calls clearly_context_map and gets back brain stats + topics, the connection is live.
What Codex gains
The headline tools — plus the full ~200-action workspace surface via the catalog. The canvas has its own guide: /docs/canvas-api.
clearly_context_search— One ranked search across prompts, docs, decisions + facts — this workspace, or the whole org with scope:"org".clearly_context_write— Write a PRD / decision back so the next agent finds it (private:true keeps it workspace-local).clearly_context_map— Orient: brain stats, recurring topics, and the orgs it can federate across.
clearly_schedule_wake— Write a prompt for its future self + schedule a wake — one-shot (runAt) or recurring (cron).
clearly_skill_list— Discover the workspace’s reusable procedures.clearly_skill_get— Load one skill’s full step-by-step instructions on demand.
clearly_canvas_perceive— SEE a composition — every node, its box + style, the selection, the viewport. Optionally a rendered PNG.clearly_canvas_act— BUILD on it — frames, text, vectors, images, auto-layout, components. One action or a whole batch. Headless.clearly_canvas_catalog— Every canvas verb + its exact args, and which run without a browser tab. Generated, so never stale.
clearly_workspace_catalog— List all ~200 workspace actions, with schemas + examples.clearly_workspace_invoke— Run any workspace action by name.clearly_guide— The Company Brain usage playbook — call it once on connect to learn how to use the rest.
Want the connection to act as a specific agent — gated by that agent’s scope and attributed to it in the activity log — rather than as you? Start the sign-in from the agent’s card in the Agents modal → Connect over MCP. Full reference, identity model and the usage playbook: MCP docs.
Option B · The Mac app
The desktop home for your workspace. It bundles the Beehaven CLI and spawns the daemon for you — so the terminal paths work with zero setup — and hosts an in-app agent room where Codex runs on your own login.
1 · Download & sign in
macOS, Apple-signed. Apple Silicon (also runs Intel via the universal build). Windows isn't built yet.
Open the app and sign in with Google. That’s the whole setup — on launch it spawns the local daemon that holds your relay connection, already authenticated as your account.
2 · The CLI is already set up
The app bundles Beehaven — nothing to install, no beehaven login, no beehaven start.
With the app running, the daemon is up, so any beehaven command — and any Codex session that shells out to one (see the CLI below) — connects immediately. Confirm it:
beehaven status # → Account: Connected
3 · The in-app Codex room (BYOK)
The desktop agent surface — Codex, on your own login, pointed at the canvas.
The app also hosts a floating agent room. The Codex room runs OpenAI Codex on your own ~/.codex login, so it bills your own ChatGPT / OpenAI plan and nothing touches Clearly’s AI pool (“bring your own key”). It runs with network access in ~/Clearly, picks from the models your plan can run (gpt-5-codex, gpt-5.x), and drives the design canvas with the same CLI verbs the terminal uses.
If the room reports it isn’t authenticated, sign Codex in once from a terminal — the room picks the session up (or set OPENAI_API_KEY):
codex login
Option C · The Beehaven CLI
One command line for your workspace. Codex drives Clearly by shelling out to it — connect, then call actions and build on the canvas headlessly (no browser tab).
1 · Install
One line, any OS. Installs the CLI and its daemon. Requires Node.js 20+. On macOS the Mac app already bundles it — skip this.
curl -fsSL https://clearly.sh/install.sh | sh
2 · Sign in & run the daemon
The daemon holds the relay connection and routes every call. The Mac app spawns it; off macOS you own it with start --headless.
beehaven login # browser OAuth sign-in beehaven start --headless # run the daemon yourself — no desktop app needed beehaven status # → Account: Connected
3 · How Codex uses it
Codex reaches Clearly with its own shell tool — connect once, then build. This is the headless path onto the canvas.
Point Codex at a workspace, then have it build. Because the canvas verbs run headless, Codex can lay out a whole page and you open the tab to find it done:
beehaven connect home # pin the target
beehaven call composition-create '{"title":"Landing"}' # capture the id
beehaven call canvas-act @build.json # build a batch of nodes
beehaven call canvas-perceive '{"compositionId":"<id>","format":"text"}' # check itFull command reference: Beehaven CLI. The node shape, the batch format and the headless rules: Canvas API.
Troubleshooting
The handful of things that actually go wrong, and the one-line fix for each.
MCP
clearly isn’t in codex mcp list / its tools never appear — an older Codex ignores remote servers. Upgrade, or add [features] with experimental_use_rmcp_client = true above the server block.
Not authenticated / calls rejected — the OAuth session expired or was never completed. Run codex mcp login clearly.
First call times out — the remote handshake exceeded the 10s default. Add startup_timeout_sec = 30 to the [mcp_servers.clearly] block.
Missing scope "rpc:write" — the sign-in only granted read. Re-run codex mcp login clearly and approve the write scope.
The CLI / daemon
Cannot connect to daemon — nothing owns the local socket. Open the Mac app (it spawns the daemon) or run beehaven start --headless.
Not connected to cloud — the daemon is up but its relay link isn’t. Usually an expired token: beehaven login. If the token is fine (e.g. after sleep), beehaven restart.
The Mac app agent room
The Codex room says it isn’t authed — it needs the Codex login it can’t do from a chat box. Run codex login in a terminal once (or set OPENAI_API_KEY); the room uses that session.