Connect Claude Code to Clearly.
Three ways, one workspace. Point Claude Code at Clearly’s hosted MCP server for the company brain + canvas as native tools, run the Beehaven CLI so Claude can build headlessly, or install the Mac app that bundles both and signs you in. Pick by what you want Claude to do — most people want MCP.
Which connection do I want?
They compose — you can run all three at once. Start with MCP; add the others when you need a local daemon or the desktop agent room.
| Path | Best for | Setup | Runs on |
|---|---|---|---|
| MCP (hosted) | Company brain + canvas as native clearly_* tools. Read/write org context, drive compositions. | OAuth sign-in. Nothing to install or run. | Clearly's hosted relay — your Claude Code reaches out. |
| The Mac app | Zero-setup: the daemon the CLI needs, auto-running + signed in. Plus an in-app BYOK agent room. | Download the DMG, sign in. | A local daemon it spawns for you — and your own ~/.claude login. |
| The CLI (Beehaven) | Headless canvas builds, scripting, any OS. Claude 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 Claude Code (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 an agent room where Claude 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 recommended path
Clearly is an MCP server. Claude Code 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 · Install & sign in
OAuth browser sign-in on first connect — no token to mint, export, or paste. The plugin path also ships Clearly's skills.
/plugin marketplace add clearly-sh/clearly-plugin /plugin install clearly@clearly # then: /mcp → select clearly → Authenticate (opens a browser sign-in)
claude mcp add --transport http clearly https://relay.clearly.sh/mcp claude mcp login clearly # opens the browser for OAuth sign-in
On the plugin path, /clearly:init walks you through the sign-in and verification in one step. Sign out or revoke anytime with claude mcp logout clearly.
3 · Scopes
Granted at sign-in. Ask for only what the session needs; re-authenticate to widen.
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 the server is live and Claude can actually reach the brain.
Run /mcp in Claude Code — clearly should appear as Authenticated with ~48 tools. A quick functional test:
> Map my Clearly workspace's brain using the clearly MCP.
If Claude calls clearly_context_map and gets back brain stats + topics, the connection is live.
What Claude Code 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 below work with zero setup — and hosts an in-app agent room where Claude 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 Claude Code that shells out to one (see the CLI below) — connects immediately. Confirm it:
beehaven status # → Account: Connected
3 · The in-app agent room (BYOK)
The desktop agent surface — Claude, on your own login, pointed at the canvas.
The app also hosts a floating agent room. The Claude room runs the Claude Code you already have — it uses your ~/.claude login, so it bills your own Claude subscription and nothing touches Clearly’s AI pool (“bring your own key”). It works in ~/Clearly and drives the design canvas with the same CLI verbs the terminal uses.
If the room reports it isn’t authenticated, sign the CLI in once from a terminal — the room picks the session up:
claude login
Option C · The Beehaven CLI
One command line for your workspace. Claude Code 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 Claude Code uses it
Claude reaches Clearly with its own Bash tool — connect once, then build. This is the headless path onto the canvas.
Point Claude at a workspace, then have it build. Because the canvas verbs run headless, Claude 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 shows in /mcp but unauthenticated — the plugin wires the endpoint; you still have to sign in. Select clearly → Authenticate.
Missing scope "rpc:write" — the sign-in only granted read. Run claude mcp logout clearly, then re-authenticate and approve the write scope.
Not authenticated / calls rejected — the session expired or was revoked. Re-authenticate with claude mcp login clearly.
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 Claude room says it isn’t authed — it needs the Claude Code login it can’t do from a chat box. Run claude login in a terminal once; the room uses that session.