Docs · Gemini

Connect Gemini & Code Assist to Clearly.

Three ways, one workspace. Point the Gemini CLI at Clearly’s hosted MCP server for the company brain + canvas as native tools, run the Beehaven CLI so Gemini can build headlessly, or install the Mac app that bundles both. Every path uses the same gemini CLI and the same ~/.gemini login — so your Gemini Code Assist identity (“Log in with Google”) flows through all of them.

Which connection do I want?

They compose — you can run all three at once. MCP gives Gemini 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.	gemini mcp add + /mcp auth (OAuth).	Clearly's hosted relay — Gemini reaches out.
The Mac app	Zero-setup: the daemon the CLI needs, auto-running + signed in. Plus an in-app BYOK Gemini room.	Download the DMG, sign in.	A local daemon it spawns — and your own ~/.gemini (Code Assist) login.
The CLI (Beehaven)	Headless canvas builds, scripting, any OS. Gemini 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 Gemini (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 Gemini runs on your own login. However Gemini authenticates — “Log in with Google” (Code Assist), an AI Studio API key, or Vertex AI — is the same across all three.

Option A · MCP — the company brain as tools

Clearly is an MCP server. Gemini 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.

MCP server URL

https://relay.clearly.sh/mcp

2 · Add it to Gemini

One command, or a config edit. Clearly is a streamable-HTTP server, so use --transport http (settings.json key: httpUrl, not url — url is SSE).

Install the Gemini CLI (if you haven't)

npm install -g @google/gemini-cli

Option 1 — the CLI (recommended)

gemini mcp add --transport http clearly https://relay.clearly.sh/mcp
gemini mcp list                    # confirm it's registered

Option 2 — edit ~/.gemini/settings.json

{
  "mcpServers": {
    "clearly": {
      "httpUrl": "https://relay.clearly.sh/mcp"
    }
  }
}

No OAuth block needed — Clearly advertises its OAuth endpoints, so the CLI auto-discovers them (authProviderType: dynamic_discovery, the default) and tokens land in ~/.gemini/mcp-oauth-tokens.json.

3 · Sign in over OAuth

In a Gemini session. Opens the browser — no token to mint, export, or paste.

/mcp auth clearly          # start the browser OAuth sign-in
/mcp auth                  # (lists any servers still needing auth)

Scopes granted at sign-in

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 Gemini can reach the brain.

Run /mcp in a Gemini session — clearly should list its tools. A quick functional test:

> Map my Clearly workspace's brain using the clearly MCP tools.

If Gemini calls clearly_context_map and gets back brain stats + topics, the connection is live.

What Gemini gains

The headline tools — plus the full ~200-action workspace surface via the catalog. The canvas has its own guide: /docs/canvas-api.

Company brain

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.

Self-prompting

clearly_schedule_wake— Write a prompt for its future self + schedule a wake — one-shot (runAt) or recurring (cron).

Skills

clearly_skill_list— Discover the workspace’s reusable procedures.
clearly_skill_get— Load one skill’s full step-by-step instructions on demand.

The canvas

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.

Everything else

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 Gemini 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.

Downloadhttps://downloads.clearly.sh/hive/Hive-latest-arm64.dmg

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 Gemini session that shells out to one (see the CLI below) — connects immediately. Confirm it:

beehaven status
# → Account: Connected

3 · The in-app Gemini room (BYOK)

The desktop agent surface — Gemini, on your own login, pointed at the canvas. The app auto-installs the gemini CLI if you don't have it.

The app also hosts a floating agent room. The Gemini room runs gemini on your own “Log in with Google” (Gemini Code Assist) session in ~/.gemini — or a Gemini API key — so it bills your own Google account 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.

Code Assist Standard / Enterprise & Workspace accounts need a project set — the Gemini CLI won’t start without GOOGLE_CLOUD_PROJECT. Export it in your shell (e.g. ~/.zshrc) and the app reads it from your login shell. Personal free “Log in with Google” doesn’t need it:

export GOOGLE_CLOUD_PROJECT="your-gcp-project-id"

If the room can’t sign in on its own (a known quirk when the CLI is launched as a subprocess), run gemini once in a terminal, complete “Log in with Google,” then reopen the room — it reuses that ~/.gemini session.

Option C · The Beehaven CLI

One command line for your workspace. Gemini 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 Gemini uses it

Gemini reaches Clearly with its own shell tool — connect once, then build. This is the headless path onto the canvas.

Point Gemini at a workspace, then have it build. Because the canvas verbs run headless, Gemini 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 it

Full 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’s tools never appear — most often the transport. Clearly is streamable HTTP, so use --transport http (or the httpUrl key in settings.json); url is SSE and won’t connect.

Not authenticated / token expired — run /mcp auth clearly in a session to (re-)authenticate.

Missing scope "rpc:write" — the sign-in only granted read. Re-run /mcp auth clearly and approve the write scope.

The Mac app agent room

The Gemini room won’t sign in — run gemini in a terminal, complete “Log in with Google,” then reopen the room; it reuses ~/.gemini.

A Workspace / Code Assist account fails to start — the CLI needs GOOGLE_CLOUD_PROJECT. Export it in your shell and relaunch the app.

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.

← MCP reference Beehaven CLI →