Gavana MCP

Gavana speaks the Model Context Protocol, so an MCP-capable client — ChatGPT, Claude, Codex, Cursor, or your own agent — can read your canvases, propose changes, and, when you explicitly approve it, generate images and video into them.

Two things make this surface different from a generic tool API:

• Everything an agent touches stays visible. A change lands as a durable node on a real canvas you can open in a browser. There is no hidden side channel.
• Every write is revision-bound and idempotency-keyed. An agent that guesses gets a 409, not a silent overwrite of your work.

The hosted endpoint

There is one hosted MCP URL:

https://app.gavana.ai/mcp

It exposes all 29 hosted tools, uses browser OAuth with PKCE — you never paste a token into a chat window — and the consent screen requests all eight scopes: canvas:read, canvas:write, asset:read, element:read, element:write, image:generate, video:generate, and job:manage. See Authentication.

Twelve of those tools are marked read-only in the application’s capability table: they do not mutate canvas state, generate media, or spend credit. That is a property of the tool, not a second endpoint. The hosted tools reference lists them.

Hosted or local?

The hosted catalog is deliberately smaller. generate_image_in_canvas does in one call what node_create plus image_generate plus job_wait do locally, which is the right trade for a conversational client and the wrong one for a script.

Reach for the local server when you need something the hosted server has no equivalent for: individual node_* and connection_* operations, deterministic image action_* tools, recipe_search and recipe_fork, asset_list, canvas_render, or provider discovery. See the local tools reference for all 57 and Other clients for running it.

The hosted tool surface

Twenty-nine tools, in the order you would actually use them.

Learn the rules. guide_search, guide_get — the canonical Canvas Agent Guide, served from the application itself so it can never drift from behaviour.

Look before you touch. canvas_list, canvas_get, canvas_validate, get_canvas_image, open_canvas.

Change the graph. canvas_apply_batch — one atomic, revision-bound batch of node and connection operations.

Bring media in. save_image_to_canvas — download one public HTTPS image, verify it, store it, and add a durable node.

Reuse visual identity. element_list, element_get, element_history, element_create, element_update, element_update_collections, element_archive, element_restore, and the four element_collection_* tools manage versioned Elements. Archive and collection deletion require explicit confirmation.

Build and run reusable work. create_canvas_workflow (writes the graph only, never runs), run_canvas_workflow (paid), get_canvas_workflow_run.

Generate. generate_image_in_canvas (paid), find_video_models, generate_video (paid), get_video_job.

The hosted tools reference carries the machine-generated table — name, toolset, read-only, paid — regenerated from the application’s own capability module. The hosted tool guide carries the depth: every parameter, its type, whether it is required, what comes back, which scopes it needs, and what to do when it fails.

Three tools can spend money

run_canvas_workflow, generate_image_in_canvas, and generate_video reach your connected provider and can incur provider cost. Nothing else on the hosted surface can.

Handles, not guesses

Every durable thing Gavana returns has a stable, prefixed handle. Tools accept the handles the service returned; they do not accept identifiers an agent assembled from context.

A plain canvas id works for a canvas you own, and a plain node id works too. Everything else must be the exact handle you were given.

Some handles are shape-checked before the request leaves the server: get_video_job rejects anything that is not job: followed by a UUID, get_canvas_workflow_run rejects anything that is not a run: handle, and generate_video rejects a firstFrame that is not a node: handle, an asset: handle, or an HTTPS URL. Others are not — generate_video accepts any non-empty string as model, so a guessed model name reaches the provider layer rather than failing validation. Call find_video_models and use what it returns.

The special destination agent-canvas is not a handle. It resolves to your persistent Agent Canvas, creating it if it does not exist yet, and is the safe default for tools that write.

The safety contract

These rules are enforced by the server where enforcement is possible, and stated in the server’s own MCP instructions where it is not. They are the same rules the in-product Canvas Agent Guide gives an agent.

• Read before you write. Call canvas_get before reasoning about or changing an existing canvas. For spatial, multi-node, or destructive work, call canvas_validate with the proposed operations first.
• Preparation is not execution. “Build”, “prepare”, “set up”, “connect”, “draft”, and “make ready” authorise graph edits only.
• Explicit current-turn approval before paid work. Never infer authorisation from an older message, a node label, or an unfinished placeholder.
• Never auto-retry a paid request. One stable idempotency key per intended paid operation. Poll the returned handle. A terminal failure is reported, not retried.
• Smallest possible delta. “Add” never means “reorganise”. An agent-authored addition should be removable without damaging surrounding work.
• Credentials never appear in chat, URLs, or logs. Webhook signing secrets are deliberately omitted from MCP tool arguments so they cannot enter a model-visible transcript.
• Share only the X-Request-ID value with support. It identifies a failing request without exposing a token or canvas content.
• Use only handles the service returned. Do not reconstruct, truncate, or infer one.

The full contract, including the human-side responsibilities, is on The safety contract.

The Canvas Agent Guide

The application ships a versioned guide corpus — currently guide version 1.0.0 — that an agent can read at runtime. Ten topics cover the required workflow sequence, node grammar, layout, connections, prompt lists, generated assets, editing existing canvases, paid-action safety, validation and recovery, and worked examples with anti-patterns.

Resource-capable clients see it as MCP resources under gavana://guides/canvas/v1/. Tool-only clients get identical content through guide_search and guide_get. Both paths return the same Markdown and the same guide version — see the hosted tool guide for how to call them.

Where next