How to Connect Claude to Gavana

Connect each Claude installation or device with its own Gavana Personal Access Token (PAT). A PAT is the only Gavana secret Claude needs. It is scoped, expires automatically, and can be revoked from Gavana without changing access on your other devices.

Prerequisites

A Gavana account that can create a Personal Access Token
Node.js 20 or newer (for the local Gavana MCP package)
Claude Code or Claude Desktop

Step 1: Create a Personal Access Token

In Gavana, open the account menu and select Personal Access Tokens. Name the token after the installation or device, such as Claude Code · MacBook Air. Choose only the scopes Claude needs and select the shortest useful expiry.

Gavana starts with canvas:read only. For the normal canvas and generation workflow, add canvas:write, asset:read, image:generate, and job:manage. Read-only review needs only canvas:read.

Gavana shows the PAT once. Copy it somewhere private until you finish the next step. Do not paste it into a conversation, email, shared document, repository, or project .mcp.json file.

Step 2: Connect Claude Code (recommended)

Click Copy Claude Code command in Gavana and paste it into a terminal. The command prompts for the PAT so the secret itself is not written into shell history. It installs a private, user-scoped MCP configuration, which makes Gavana available across your projects without placing credentials in a shared project file.

The command uses Gavana’s published @gavana.ai/mcp package. If npx reports that the package cannot be found, the package has not yet been released to npm; ask your Gavana administrator to publish it before retrying. Do not replace the command with an unverified package or a copied configuration from someone else.

The command has this shape:


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

Paste the PAT only after the prompt appears, then press Return. GAVANA_AGENT_TOKEN is the existing MCP environment-variable name; its value is your one PAT, not a second token.

On Windows, use Copy PowerShell command from Gavana instead. It uses the same PAT, reads it through a masked prompt, and clears the temporary PowerShell variables after Claude Code saves the connection.

Verify the saved server:


claude mcp get gavana

Start Claude Code and run /mcp. Gavana should appear as connected. If Claude reports an authentication error, revoke that PAT in Gavana, create a replacement for this device, and repeat the command.

Step 3: Connect the Claude Desktop chat app (alternative)

In Gavana’s one-time token screen, select Copy Claude Desktop settings. Add the copied gavana server entry to claude_desktop_config.json on this device, then restart the Claude Desktop chat app. If you use the Code tab inside Claude Desktop, use the Claude Code command from Step 2 instead; its MCP configuration is separate.

The settings contain the same PAT from Step 1. Do not create an Agent Access token as well, and do not add the settings to source control or a shared setup document. Claude Desktop’s local MCP settings are for that device only.

Step 4: Use Gavana in Claude

Ask Claude to list your canvases or inspect a specific canvas. Claude can only use the scopes on this PAT. Gavana records the token’s device name in canvas and activity provenance, so you can review which Claude installation changed a canvas.

Keep the connection safe

Use one PAT per Claude installation or device. Never share a PAT between people.
Choose the narrowest scopes and shortest practical expiry.
Revoke the PAT immediately if a device is lost, shared, or no longer trusted.
Removing the MCP server from Claude stops local use, but revoking it in Gavana is the definitive way to stop future requests.
A local MCP server runs through Node.js on your device. Only install the Gavana package from the command shown by Gavana.

About Claude connectors

Gavana also exposes a hosted MCP endpoint with browser OAuth for compatible remote MCP clients. Use the PAT flow above when you want a separate, device-scoped Claude installation with precise Gavana-side revocation. Do not combine a PAT with a second Gavana agent secret for the same installation.