Connect via MCP

Gavana’s local stdio MCP lets MCP-capable clients such as Claude, Codex, or Hermes use the broader Canvas API contract directly from a conversation. It is intended for advanced automation; for ChatGPT or a remote OAuth-capable client, start with the smaller hosted MCP instead.

Prerequisites

An Agent Access token with the scopes needed by the tools you will enable, or an existing local CLI login.
Node.js 20 or newer

Steps

Step 1: Configure the Agent Access token


GAVANA_BASE_URL=https://app.gavana.ai
GAVANA_AGENT_TOKEN=<private Agent Access token>

Store the token in the MCP client’s private environment or secret store. Never put a literal token in a shared configuration, repository, or chat message. Existing CRAFTBOARD_BASE_URL and CRAFTBOARD_AGENT_TOKEN variables continue to work as compatibility aliases.

Step 2: Register the MCP server with your client


npx -y @gavana/mcp@0.1.0

The repository contains the package release candidate, but this help center does not treat npm publication as verified. If npx cannot resolve it, use the checked-out source command only when you have repository access:


bun run canvas:mcp

Use gavana mcp install codex --read-only when you want the CLI to register the hosted strict read-only endpoint for Codex instead of configuring a local server.

Step 3: Work with your canvas from the conversation

Once connected, the agent can list canvases, read and change nodes, discover and explicitly run Recipes, run deterministic Image Actions, queue image or video work, and return durable results—subject to its token scopes and local tool configuration. recipe_fork only adds a private editable workflow; recipe_run is the separate tool that executes it. Use run_get, run_wait, and run_cancel for Recipe, image, or Action work. The older job_* tools remain image and Action compatibility aliases; they are never used for Recipe Runs. Action runs do not spend AI credits. The run_get, run_wait, and run_cancel tools require job:manage; include that scope on the Agent Access token for the normal wait-for-result flow.

Reference

The token’s name (set when you created it) is written into node and activity provenance, so canvas review can tell apart callers like Codex · CLI, Claude · MCP, and Hermes · MCP without trusting a caller-supplied label.

Notes

ChatGPT uses Gavana’s separate hosted OAuth MCP endpoint. See Connect Gavana to ChatGPT.
The package and preferred environment variables already use Gavana. The API domain, saved CLI configuration path, and cba_ token prefix remain stable until the full application cutover.
The canvas UI remains available for visual review at any time; using MCP doesn’t require opening it.
Recipe, image, and Action webhooks are intentionally API/CLI-only. Webhook signing secrets are omitted from MCP tool arguments so they cannot enter model-visible conversation or tool logs. Use the CLI’s --webhook-secret-env option or call the API from a trusted backend when you need callbacks.