Skip to Content
Personal Access TokensConnect another MCP client

Connect another MCP client

Gavana ships a local stdio MCP package — @gavana.ai/mcp — so MCP-capable clients like Codex or Hermes can call the same canvas operations as the CLI directly from a conversation. For Claude Code and Claude Desktop, use the dedicated Connect Claude flow so every installation has one scoped, expiring Personal Access Token (PAT).

Prerequisites

  • A Personal Access Token with the scopes needed by the tools you will enable. An existing CLI login can be reused but is not required.
  • Node.js 20 or newer

Steps

Step 1: Configure the Personal Access Token

GAVANA_BASE_URL=https://app.gavana.ai
GAVANA_AGENT_TOKEN=<private Personal 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

Register this local stdio command using the client’s MCP configuration:

npx -y @gavana.ai/mcp@0.2.0

The package must first be published by an owner of the gavana.ai npm organization. Repository contributors can use bun run canvas:mcp until that publication is complete.

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 the eight deterministic Image Actions, queue AI image generation, and return durable results — all using the token’s scopes. 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 Personal 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 and Hermes · MCP without trusting a caller-supplied label.

Notes

  • ChatGPT uses Gavana’s separate hosted Streamable HTTP MCP endpoint and OAuth flow. 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.
Connect ClaudeOverview