Connect Gavana to Claude Code

Claude Code can reach Gavana two ways. Pick one — do not configure both under the same server name.

	Hosted (OAuth)	Local (Personal Access Token)
Transport	HTTP	stdio
Sign-in	Browser	Token you create and paste once
Tools	29 hosted tools	57 local tools
Setup	One CLI command	One shell command
Scope control	All-or-nothing at consent	Per-token, exactly the scopes you pick

Choose hosted for the fastest setup with no secret to manage. Choose local when you want fine-grained scopes, the full tool surface including Image Actions and Recipes, or a read-only agent.

Option A — Hosted MCP over OAuth

Requires the Gavana CLI.


gavana mcp install claude

That runs, on your behalf:


claude mcp add --transport http gavana https://app.gavana.ai/mcp

Start Claude Code and complete the browser sign-in when prompted. Approve the scopes on Gavana’s consent screen.

Resulting permission surface. The full endpoint grants canvas:read, canvas:write, asset:read, element:read, element:write, image:generate, video:generate, and job:manage, so image, workflow, and video generation are reachable and can charge your connected AI provider.

Option B — Local MCP with a Personal Access Token

Create a token

Follow Create an Agent Access Token. Name it for this machine — for example Claude Code · MacBook Air. New tokens default to all eight permissions and Never expiry. Choose a narrower scope set or a custom 1–90 day expiry only when that boundary is deliberate.

Register the server

This command prompts for the token rather than embedding it, so the command itself is safe to leave in shell history. Claude Code stores the value in your private user-scoped MCP configuration.

macOS and Linux (zsh or Bash):


read -rs 'GAVANA_PERSONAL_ACCESS_TOKEN?Paste Personal Access Token: '; printf '\n'; claude mcp add --transport stdio --scope user --env GAVANA_BASE_URL='https://app.gavana.ai' --env GAVANA_AGENT_TOKEN="$GAVANA_PERSONAL_ACCESS_TOKEN" gavana -- npx -y @gavana.ai/mcp@0.2.0; unset GAVANA_PERSONAL_ACCESS_TOKEN

Windows PowerShell:


$secureToken = Read-Host 'Paste Personal Access Token' -AsSecureString; $tokenPointer = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($secureToken); try { $token = [Runtime.InteropServices.Marshal]::PtrToStringBSTR($tokenPointer); claude mcp add --transport stdio --scope user --env GAVANA_BASE_URL='https://app.gavana.ai' --env "GAVANA_AGENT_TOKEN=$token" gavana -- npx -y @gavana.ai/mcp@0.2.0 }; finally { if ($tokenPointer -ne [IntPtr]::Zero) { [Runtime.InteropServices.Marshal]::ZeroFreeBSTR($tokenPointer) }; Remove-Variable token, tokenPointer, secureToken -ErrorAction SilentlyContinue }

Paste the token when prompted and press Return.

Verify the registration


claude mcp get gavana

Confirm inside Claude Code

Start Claude Code and run /mcp. Gavana should appear as connected.

Resulting permission surface. Exactly the scopes on the token you created — nothing more. The local server exposes 57 tools, but a call outside the token’s scopes fails with a permission error rather than succeeding. If the token has no image:generate or video:generate, no generation tool can spend anything.

For a read-only local server, add GAVANA_MCP_READ_ONLY=true to the environment. Scoping the token is the stronger control; use both if you want belt and braces.

Verify it works

Ask Claude Code for something read-only first:


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.

You should see canvas_list then canvas_get, and a report built from real handles.

Disconnect


claude mcp remove gavana

Then revoke the token in Gavana’s Personal Access Tokens screen. Removing the MCP server stops Claude Code from using it; revoking the token stops anything from using it.

Troubleshooting

Symptom	Cause	Fix
Server does not appear in `/mcp`	Registration used a project scope in a different directory	Re-run with `--scope user`
Every call returns a permission error	Token lacks the scope, or is read-only	Check the scopes on the token; create a new one if needed
Waiting for a result always fails	Token lacks `job:manage`	Add `job:manage`, or use `--no-wait` plus a webhook via the CLI
`npx` cannot resolve the package	Package not reachable from this machine	See other clients for the source-run fallback

More: MCP troubleshooting and Agent troubleshooting.