Connect an Agent

Gavana offers three ways to connect an AI client. They differ in how the client authenticates, how many tools it gets, and how much it can spend.

The three transports

	Hosted MCP	Local MCP	CLI
Endpoint or command	`https://app.gavana.ai/mcp`	`npx -y @gavana.ai/mcp@0.2.0`	`gavana`
Authentication	Browser OAuth	Personal Access Token	Browser OAuth or token
Tool count	29 hosted tools	57 local tools	23 command groups
Runs on	Gavana’s servers	Your machine	Your machine
Webhooks	Not available by design	Not available by design	Available
Best for	Chat clients — ChatGPT, Claude, any OAuth-capable MCP client	Coding agents that launch local processes	Scripting, CI, and shell composition

Pick your client

ChatGPTHosted OAuth ClaudeHosted or local Claude CodeHosted or local CodexHosted OAuth CursorHosted or local GeminiGemini CLI AntigravityHosted OAuth OpenClawHosted OAuth HermesHosted OAuth GrokGrok Build CLI Other clientsAny MCP client

Hosted MCP

A remote MCP server that Gavana runs. Your client connects over HTTP and signs in through a browser — no token is ever pasted into the client.

Normal endpoint:


https://app.gavana.ai/mcp            full catalog

The full endpoint exposes 29 tools, including complete Element CRUD and collection management. Important execution tools include:

Tool	Side effect
`canvas_apply_batch`	Writes canvas state
`save_image_to_canvas`	Writes a durable image node
`create_canvas_workflow`	Writes a workflow card — never generates
`run_canvas_workflow`	May incur provider cost
`get_canvas_workflow_run`	Reads run state
`find_video_models`	Reads — but gated behind `video:generate`
`generate_image_in_canvas`	May incur provider cost
`generate_video`	May incur provider cost
`get_video_job`	Reads job state
`element_create`, `element_update`, `element_restore`	Writes the Element library
`element_archive`, `element_collection_delete`	Requires explicit confirmation

Full schemas: hosted MCP tools.

The OAuth consent screen names the exact scopes being requested. The normal full endpoint requests all eight — canvas:read, canvas:write, asset:read, element:read, element:write, image:generate, video:generate, and job:manage — and remains active until you disconnect or revoke it.

Local MCP

A stdio MCP server that runs on your machine and talks to the Canvas API using a Personal Access Token you supply. It exposes the widest tool surface — 57 tools covering Elements, Image Actions, Recipes, connections, and Runs.


npx -y @gavana.ai/mcp@0.2.0

It needs two environment variables in the client’s private configuration:


GAVANA_BASE_URL=https://app.gavana.ai
GAVANA_AGENT_TOKEN=<your Personal Access Token>

The CLI can print a ready-made client configuration:


gavana mcp config local

Full tool list: local MCP tools.

CLI

A JSON-first command-line client. Best when you want deterministic, scriptable behaviour, or when you need webhooks — which MCP deliberately does not offer, because a signing secret must never enter model-visible tool arguments.


gavana auth login  # browser OAuth, full scopes

See Install the CLI and the CLI Reference.

What each path can spend

This is the question worth answering before you connect anything.

Connection	Can read	Can write canvas	Can spend credits
Hosted full MCP	Yes	Yes	Yes
Local MCP, full token	Yes	Yes	Yes
CLI, default login	Yes	Yes	Yes
CLI or API, custom token	Whatever the token’s scopes allow

Deterministic Image Actions are the useful middle ground: they write to the canvas and transform images without spending AI credits.

A sensible order

Connect the normal workspace

Use /mcp, or a new Personal Access Token with its default eight permissions and Never expiry. The agent can then use the full Gavana workflow.

Inspect first, then write

Let the agent read canvases before it changes them. See Inspect a canvas read-only. For a local server, a narrower Personal Access Token or GAVANA_MCP_READ_ONLY=true can enforce that boundary.

Approve paid work in the current request

Generation remains a separate decision: the agent must have explicit current-turn approval before it spends provider credit.

Compatibility

CRAFTBOARD_BASE_URL and CRAFTBOARD_AGENT_TOKEN still work as aliases for the GAVANA_* variables, and the craftboard and craftboard-canvas commands remain available alongside gavana.