Install overview

Every Gavana MCP setup is one of two shapes.

Hosted, over streamable HTTP. You give your client a URL, approve a browser OAuth consent screen, and you are done. Nothing to install, no token to handle, no Node.js required. This is what you want unless you have a specific reason otherwise.

Local, over stdio. Your client runs npx -y @gavana.ai/mcp@0.2.0 on your machine and authenticates with an Agent Access token or a saved CLI profile. You get 57 tools instead of 29, including node-level graph operations, deterministic Actions, and Recipe Library search.

Pick a page

Client	Hosted OAuth	Local stdio	`gavana mcp` helper
Claude Code	Yes	Yes	`gavana mcp install claude`
Claude web & desktop	Yes	Desktop only	—
Cursor	Yes	Yes	`gavana mcp config cursor`
VS Code	Yes	Yes	—
Codex	Yes	Yes	`gavana mcp install codex`
ChatGPT and everything else	Yes	Yes	`gavana mcp config chatgpt` \| `local`

The hosted URL

Every hosted install on this site uses one URL:


https://app.gavana.ai/mcp

It registers all 29 hosted tools and the consent screen requests all eight scopes. Three of those tools — run_canvas_workflow, generate_image_in_canvas, and generate_video — can charge your connected provider. The OAuth details are on Authentication.

To narrow a local stdio server without changing the token, set GAVANA_MCP_READ_ONLY=true — that is a local-process filter, not a second hosted URL.

The `gavana mcp` helper

If you already have the Gavana CLI, it will register a hosted endpoint for you or print the exact config block to paste:


gavana mcp install codex
gavana mcp install claude
gavana mcp config cursor|chatgpt|local

Two commands, and they do different things:

install actually runs your client’s own CLI to register the server. It supports codex and claude only.
config prints the configuration — a JSON block, a command, or instructions — without changing anything. Use it for cursor, chatgpt, and local. It also works for codex and claude if you would rather see the command than have it run.

The hosted helpers write https://app.gavana.ai/mcp. For the local client, gavana mcp config local prints a stdio definition; add GAVANA_MCP_READ_ONLY=true yourself if you want the local process to register only non-mutating tools.

Passing any other client name is a usage error. The supported set is codex, claude, cursor, chatgpt, and local (also spelled stdio).

What the local server needs

Node.js 20 or newer.
An Agent Access token with the scopes the tools you enable actually need, or an existing CLI login.

You can narrow the local server without touching the token, using environment variables:


GAVANA_MCP_READ_ONLY=true      # register only tools that cannot mutate, generate, or cancel
GAVANA_MCP_TOOLSETS=canvas,assets
GAVANA_MCP_TOOLS=canvas_list,canvas_get
GAVANA_MCP_EXCLUDE_TOOLS=node_delete,job_cancel

The toolsets are canvas, recipes, assets, elements, models, actions, images, videos, runs, and the opt-in campaigns.

@gavana.ai/mcp is published on the public npm registry at version 0.2.0 and installs the gavana-mcp executable, so npx -y @gavana.ai/mcp@0.2.0 resolves without extra configuration. If npx cannot resolve it, your environment is proxying npm through a private registry that does not mirror the package. Use a hosted endpoint instead, or run from a checked-out application repository with bun run canvas:mcp if you have access.

After you connect

Whatever client you use, verify the same three things:

Tool count. 29 means the hosted endpoint. 57 means a local stdio server.
A read works. Ask the agent to list your canvases. If that fails, it is an auth problem, not a config problem — see Troubleshooting.
The guide loads. Ask it to call guide_search. That tool needs no scope at all, so it succeeds even on the narrowest connection and confirms the transport is healthy.

Then work through Inspect before you write once, so the read-first habit is established before anything writes.