Connect Gavana to Codex

Codex is the client Gavana’s CLI installs most directly. One command registers the hosted MCP endpoint and Codex handles the browser sign-in.

Prerequisites

The Gavana CLI
The codex command on your PATH

Install

Register the server

Normal connection:


gavana mcp install codex

What it runs

The CLI executes this for you:


codex mcp add gavana --url https://app.gavana.ai/mcp

Start Codex and complete the Gavana browser sign-in when prompted. Review the scopes on the consent screen before approving.

Verify

Ask for something read-only:


Using Gavana, list my canvases and read the most recently updated one. Report its
handle, revision, node count, and connection count. Do not change anything.

To see the endpoint and transport without registering anything:


gavana mcp config codex

That prints the client, transport, endpoint, and the exact command it would run — useful for review, for a runbook, or for registering by hand.

Resulting permission surface

Normal connection

Codex gets the full 29-tool hosted catalog. The OAuth consent requests canvas:read, canvas:write, asset:read, element:read, element:write, image:generate, video:generate, and job:manage.

Three tools can charge your connected AI provider: run_canvas_workflow, generate_image_in_canvas, and generate_video. Cost exposure: real.

See hosted MCP tools for full schemas.

Want the wider tool surface instead?

The hosted endpoint is deliberately compact. If you want the 57-tool local surface — Image Actions, Recipe forking, node-level operations, connection modes, Run control — register the local stdio server with a scoped Personal Access Token instead:


gavana mcp config local

That prints a configuration block you can adapt to Codex’s MCP configuration. The token’s scopes, not the tool list, define what Codex can do.

Alternative: use the CLI directly

Codex can also just run the Gavana CLI as a shell tool. That gives you deterministic JSON output, exit codes, --jq selection, and webhooks — none of which MCP offers. For scripted or CI work, this is often the better fit:


gavana canvas list --limit 25 --jq '.canvases[].handle' -r

Disconnect

Remove the server from Codex’s MCP configuration, then revoke the Gavana OAuth delegation from the Personal Access Tokens screen. Revocation takes effect on the next request.

Troubleshooting

Symptom	Cause	Fix
`gavana mcp install codex` fails immediately	`codex` is not on `PATH`	Install Codex, or run `gavana mcp config codex` and register by hand
Sign-in never completes	Browser could not reach the loopback callback	Retry; on a headless machine use the local MCP with a token instead
Registered to the wrong environment	A `--base-url` or a profile pointed elsewhere	Re-run with `--base-url https://app.gavana.ai`, or select the right `--profile`
Writes are refused	Token or local filter lacks write scopes	Re-register after deciding you want write access, or remove `GAVANA_MCP_READ_ONLY`