Other Clients

Gavana ships presets for Codex, Claude, Cursor, ChatGPT, and a generic local server. Any other MCP client connects with the same two transports — you just supply the configuration in whatever format that client expects.

Path 1 — Hosted MCP over OAuth

For any client that supports remote MCP over streamable HTTP with OAuth.

Transport:  streamable-http
Endpoint:   https://app.gavana.ai/mcp

The client registers itself dynamically at /oauth/register, sends the user to /oauth/authorize, and exchanges the code at /oauth/token. The flow uses PKCE with S256 and binds to the exact redirect URI the client registered. Gavana’s own CLI uses precisely this flow when you run gavana auth login.

Requested scopes:

Resulting permission surface. The full endpoint exposes 29 tools, three of which charge your connected AI provider: run_canvas_workflow, generate_image_in_canvas, generate_video. See hosted MCP tools.

The normal /mcp connection requests all eight scopes and remains active until you disconnect or revoke it.

Path 2 — Local stdio MCP

For any client that launches a local process. This is the widest tool surface — 57 tools.

Command:  npx
Args:     -y  @gavana.ai/mcp@0.2.0
Env:      GAVANA_BASE_URL=https://app.gavana.ai
          GAVANA_AGENT_TOKEN=<your Personal Access Token>

Get the canonical definition, including the credential-source note, straight from the CLI:

gavana mcp config local

It resolves credentials from the active Gavana CLI profile, or from inherited GAVANA_BASE_URL and GAVANA_AGENT_TOKEN environment variables — so if the client inherits your shell environment and you have already run gavana auth login, you may not need to set anything explicitly.

Resulting permission surface. Exactly the scopes on the token. Tools outside those scopes fail with a permission error rather than succeeding.

Requires Node.js 20 or newer.

Path 3 — The CLI as a shell tool

Any agent that can run shell commands can use the Gavana CLI directly. This is often the better fit for scripted and CI work: one JSON object on stdout, errors and progress on stderr, meaningful exit codes, a built-in --jq selector, and — unlike MCP — webhook support.

gavana canvas list --limit 25 --jq '.canvases[].handle' -r
gavana canvas get canvas:OWNER_UID:CANVAS_ID --output markdown

Shell completion is available for zsh, Bash, and fish:

gavana completion zsh

Path 4 — The Canvas API directly

For your own service, skip MCP entirely and call the Canvas API. It is a documented OpenAPI 3.1 contract with revision-safe writes, idempotency, pagination, and signed webhooks.

Base URL:      https://app.gavana.ai/api/canvas-agent/v1
Authorization: Bearer <Personal Access Token>

A dependency-free JavaScript client ships with the CLI package:

import { createCanvasAgentClient } from "@gavana.ai/cli";
 
const client = createCanvasAgentClient({
    baseUrl: process.env.GAVANA_BASE_URL,
    token: process.env.GAVANA_AGENT_TOKEN,
    surface: "api"
});
 
const result = await client.listCanvases();

If you want to explore endpoints without writing a client, the CLI has a raw passthrough restricted to paths under /api/canvas-agent/v1:

gavana api GET /canvases --field limit=10
gavana api POST /canvases --json '{"title":"Concepts"}'

Which path

Requirements for any path

• HTTPS for remote origins. Plain HTTP is accepted only for localhost, 127.0.0.1, and ::1.
• Node.js 20 or newer for the CLI and the local MCP server.
• A scoped credential. Either browser OAuth, or a Personal Access Token. New Personal Access Tokens default to all eight scopes and Never expiry; narrow them or choose a custom expiry when appropriate.

Compatibility

CRAFTBOARD_BASE_URL, CRAFTBOARD_AGENT_TOKEN, CRAFTBOARD_PROFILE, and CRAFTBOARD_AGENT_CONFIG_FILE remain supported as aliases of their GAVANA_* counterparts. The craftboard and craftboard-canvas commands remain available. Existing configuration at ~/.config/craftboard/agent.json is still read when no Gavana configuration is present.

Give your agent the contract

Whatever the transport, point the agent at the safety contract. If it speaks MCP, it can also fetch Gavana’s own guidance at runtime with guide_search and guide_get, or read the resources under gavana://guides/canvas/v1/.

Related

• Connection overview
• CLI Reference
• MCP authentication
• API quickstarts