Claude Code

Claude Code supports both shapes: the hosted endpoint over streamable HTTP with browser OAuth, and the local stdio server with an Agent Access token.

Hosted

Copy this exactly:


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

Claude Code registers the server and prompts you to authenticate. A browser opens, you sign in to Gavana, and the consent screen asks for all eight scopes.

Permission surface: 29 hosted tools, including Element management, canvas writes, workflow authoring, and generation.

This grants Claude Code the ability to spend money on your provider account. The server’s own instructions tell the model to ask for explicit current-turn approval first and never to auto-retry a failed paid call, but the capability is present.

Let the Gavana CLI do it

If you already have the Gavana CLI installed, it runs the same claude mcp add command for you:


gavana mcp install claude

To see the command without running it:


gavana mcp config claude

That prints the client, transport, endpoint, and the exact command and args it would execute.

Local stdio server

Use this when you need the 57-tool surface: individual node_* and connection_* operations, deterministic image action_* tools, recipe_search and recipe_fork, asset_list, canvas_render, or provider discovery.

You need Node.js 20 or newer and an Agent Access token.

macOS and Linux

This command prompts for the token so it never lands in your shell history:


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

Claude Code stores the value in your private user-scoped MCP configuration. The shell command itself contains no secret, so it is safe to keep in history or share.

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 }

Permission surface: 57 tools, acting with exactly the scopes on the token you pasted. A token with only canvas:read yields a read-only local server no matter which tools are registered — the scopes are the boundary, not the tool list.

Narrow it further

To restrict the local server without changing the token, add environment variables to the same claude mcp add command:


--env GAVANA_MCP_READ_ONLY=true
--env GAVANA_MCP_TOOLSETS=canvas,assets
--env GAVANA_MCP_EXCLUDE_TOOLS=node_delete,job_cancel

GAVANA_MCP_READ_ONLY=true registers only tools whose annotations guarantee no mutation, generation, or cancellation.

Keep guide_search, guide_get, and canvas_validate enabled whatever else you cut. They are read-only, free, and they are how the agent learns the rules and checks its own work.

@gavana.ai/mcp is published on the public npm registry at version 0.2.0, so npx -y @gavana.ai/mcp@0.2.0 resolves without extra configuration. If your environment proxies npm through a private registry that does not mirror it, use a hosted endpoint instead.

Verify

Run /mcp in Claude Code. You should see gavana connected, with 11 tools (hosted read-only), 29 (hosted full), or 57 (local).

Then ask it to list your canvases. If that fails while the server shows as connected, it is an authentication problem — see Troubleshooting.

Switching endpoints later

Remove and re-add. Changing the URL in place leaves the old OAuth grant attached:


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

Authentication Hosted tool guide Inspect before you write Troubleshooting