Connect Gavana to Claude
Claude connects to Gavana as a custom connector over browser OAuth. You never paste a token into Claude.
This page covers the Claude chat product — Claude on the web, Claude Desktop, and Cowork. It does not cover Claude Code, the terminal agent, even when you run it inside the Desktop app. That has its own setup: Connect Gavana to Claude Code. Readers mix these up constantly. If you are typing into a chat box, you are on the right page.
Connect with full access
https://app.gavana.ai/mcp
This is the default Gavana connection. It requests all eight permissions and remains active until you disconnect or revoke it.
Who can add a connector
Custom connectors using remote MCP are available on Free, Pro, Max, Team, and Enterprise plans, across Claude, Claude Desktop, and Cowork.
- Free is limited to one custom connector. Spend it on the endpoint you actually need.
- On Team and Enterprise, only Owners can add a connector. Once an Owner has added it, each member connects to it individually, so Claude only ever reaches what that member’s own Gavana account can reach.
Anthropic publishes click-by-click steps for Pro and Max, and separately for Team and Enterprise. Free is listed as eligible but has no separate written path — follow the Pro and Max steps.
Add the connector — Pro and Max
Open connector settings
Navigate to Customize → Connectors.
Add a custom connector
Click ”+”, then Add custom connector.
Paste the endpoint
https://app.gavana.ai/mcpLeave Advanced settings blank
Advanced settings offers an OAuth Client ID and Client Secret. Gavana supports dynamic client registration, so you do not need either. Skip it.
Click Add, then Connect
Gavana opens a sign-in and consent screen.
Review the requested permissions and approve
The normal full endpoint asks for all eight scopes. Read the list before approving.
Add the connector — Team and Enterprise
An Owner or Primary Owner does this once for the organization.
Open organization connectors
Navigate to Organization settings → Connectors.
Add
Click the Add button, hover over Custom, then select Web.
Paste the endpoint
https://app.gavana.ai/mcpLeave Advanced settings blank — Gavana supports dynamic client registration.
Finish with Add
The connector now appears to members with a Custom label.
Each member then goes to Customize → Connectors, finds the connector in the list, and clicks Connect to authenticate.
Turning it on for a conversation
Use the ”+” button at the lower left of the chat interface, then Connectors. Your configured connectors appear with per-conversation toggles.
To change a connector’s URL, remove it and re-add it with the updated details — there is no in-place edit.
Where the connection comes from
When you add a custom connector, Claude connects to the MCP server from Anthropic’s cloud infrastructure, not from your device. That holds across every Claude client, including Claude Desktop and Cowork: even though those run on your computer, remote connectors are brokered through your Claude account, and the request to Gavana originates from Anthropic’s servers rather than your machine’s network interface.
If you allowlist outbound traffic, or you expected to see this connection in your own network logs, that is why you will not.
Local stdio servers in Claude Desktop are the exception — those are a separate mechanism and do use your local network. They are covered below, and they are not available in Cowork or on the web.
Resulting permission surface — hosted endpoints
Read-only endpoint
| Can | Cannot |
|---|---|
| List and read canvases | Create, update, move, or delete anything |
| Validate a canvas graph | Save an image |
| Preview a canvas or get a review link | Create or run a workflow |
| Read Gavana’s own agent guidance | Discover video models, or generate an image or a video |
| Spend a single credit |
Tools exposed: guide_search, guide_get, canvas_list, canvas_get, canvas_validate, get_canvas_image, open_canvas, element_collection_list, element_get, element_history, and element_list — 11 in total. It issues canvas:read and element:read.
find_video_models is absent even though it only reads. It requires video:generate, and this endpoint never issues that scope.
Cost exposure: none.
Full endpoint
Sixteen tools. Everything above, plus canvas writes, workflow authoring, and generation.
Three of them can charge your connected AI provider: run_canvas_workflow, generate_image_in_canvas, and generate_video. See hosted MCP tools for full schemas.
Cost exposure: real.
The full endpoint’s OAuth consent requests canvas:read, canvas:write, asset:read, element:read, element:write, image:generate, video:generate, and job:manage. There is no partial approval on this path.
Claude Desktop with the local stdio server
Claude Desktop can also launch Gavana’s local MCP server as a child process. That path exposes 57 tools instead of 29, and it authenticates with a Personal Access Token rather than OAuth.
This is Desktop only. Cowork and Claude on the web cannot run local servers.
Prerequisites
- Node.js 20 or newer — the server runs through
npx - A Personal Access Token scoped to what you want Claude to do
Create a token for this device
Name it for the machine — Claude Desktop · Studio iMac. Pick the smallest scope set that does the job:
- Review only:
canvas:read,asset:read - Build structure without spending:
canvas:read,canvas:write,asset:read - Full creative work: add
image:generateandjob:manage
Open the config file
Click the Claude menu in your system menu bar — not the in-window settings — then Settings…, then the Developer tab in the left sidebar, then Edit Config. That opens the existing file, or creates one if there is none.
The file lives at:
macOS ~/Library/Application Support/Claude/claude_desktop_config.json
Windows %APPDATA%\Claude\claude_desktop_config.jsonAdd the Gavana server
{
"mcpServers": {
"gavana": {
"command": "npx",
"args": ["-y", "@gavana.ai/mcp@0.2.0"],
"env": {
"GAVANA_BASE_URL": "https://app.gavana.ai",
"GAVANA_AGENT_TOKEN": "PASTE_YOUR_TOKEN_HERE"
}
}
}
}Replace PASTE_YOUR_TOKEN_HERE with the token value. If the file already has an mcpServers object, add the gavana entry to it rather than replacing the whole file.
Restart Claude Desktop
Quit the app completely and reopen it. The server starts when the app starts.
Verify
Click the Add files, connectors, and more indicator at the bottom left of the conversation input box, hover Connectors, click Manage connectors, and select the server to see its tools.
Then 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.You can generate the same block from the CLI, without the token, using gavana mcp config local. Add "GAVANA_MCP_READ_ONLY": "true" to env for a hard read-only local server.
This configuration file contains a live credential. Never commit it, never screenshot it, never paste its contents into a chat or a support ticket. If it leaks, revoke that token immediately and create a new one — see the safety contract.
What the local server can actually do
The 57 tools cover canvases, nodes, connections, assets, models, providers, Image Actions, Recipes, images, video, and Runs. But the real permission surface is the token’s scopes, not the tool list — a tool called outside them fails with a permission error.
| Token scopes | What Claude Desktop can do | Cost exposure |
|---|---|---|
canvas:read, asset:read | Inspect canvases, read nodes and assets, validate graphs, list Recipes, Actions, and models | None |
Plus canvas:write | Create, update, move, resize, and delete nodes and connections; apply atomic batches; run deterministic Image Actions on existing handles | None |
Plus image:generate | Generate and edit images, upload local files, run any Recipe | Real |
Plus video:generate | Generate video from prompts and frames | Real |
Plus job:manage | Wait for, poll, and cancel Runs and Jobs | None on its own |
Without job:manage, tools that wait for a result will fail at the waiting step. Include it unless you have a specific reason not to.
To narrow the server without changing the token, add either of these alongside the two variables already in env:
"GAVANA_MCP_READ_ONLY": "true",
"GAVANA_MCP_TOOLSETS": "canvas,assets"Scoping the token is still the stronger control.
@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.
Disconnect
For the hosted connector: remove it in Claude to stop new use from that client, and revoke the Gavana OAuth delegation from Gavana’s Personal Access Tokens screen. Revocation takes effect on the next request. Do both if the connection was made from a device or workspace you no longer control.
For the local server: remove the gavana entry from claude_desktop_config.json, restart Claude Desktop, then revoke the token. Removing the entry stops this app; revoking the token stops everything holding that credential.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| No custom connector option | Team or Enterprise plan without Owner rights | An Owner must add it from Organization settings → Connectors |
| Cannot add a second connector | Free plan, one-connector limit | Remove the existing one, or upgrade |
| Connector added but tools never appear | Connector toggled off for this conversation | Use the ”+” button → Connectors and enable it |
| Wrong URL on a connector | Connectors cannot be edited in place | Remove it and re-add with the correct URL |
| Local server never starts | Node.js older than 20, or npx unavailable | Install Node.js 20+ and confirm npx --version |
| Every local call is unauthorized | Token expired, revoked, or mistyped | Create a new token and update the configuration |
| Generation is refused | Token lacks image:generate or video:generate | Create a new token with those scopes |
| Waits time out immediately | Token lacks job:manage | Create a new token including it |
| Local tools appear but do nothing useful | Read-only mode is on | Remove GAVANA_MCP_READ_ONLY if you did want writes |
Claude Desktop writes MCP logs to ~/Library/Logs/Claude on macOS and %APPDATA%\Claude\logs on Windows. mcp.log covers connection failures; mcp-server-gavana.log carries the server’s own stderr.
More: MCP troubleshooting.
Security notes
- The hosted endpoints accept OAuth bearer tokens only. Do not attempt to use a
cba_…Personal Access Token there — that is the local MCP and API path. - Webhooks are not available through MCP by design: a signing secret must never enter model-visible tool arguments or tool logs. Use the CLI or the API when you need callbacks.
- Generation charges the AI provider connection on your Gavana account, not Anthropic.