Gavana MCP

This source package is ready for a controlled public npm release. The npx command below is the customer command after its matching protected GitLab tag is published.

Use of the published MCP server is subject to the current Gavana Terms of Service. Its customer package license incorporates those terms by reference.

@gavana.ai/mcp exposes Gavana Canvas as a local stdio MCP server. Existing Agent Access tokens and canvases continue to work through the compatibility layer. MCP clients can discover canvases, reusable Elements, and assets, inspect and change canvas graphs, run Recipes and deterministic image Actions, generate images and videos, and observe or cancel asynchronous work.

The server also exposes the versioned Gavana Canvas Agent Guide through MCP resources. Tool-only clients receive the identical guide through guide_search and guide_get. Agents should inspect the relevant guide and current canvas, validate a proposed batch, apply it against the current revision, then validate the result.

For an exact product, garment, logo, or other visual identity, do not rely on a prompt-only image generation. The local server's asset_upload tool accepts a PNG, JPEG, WebP, or GIF file that the user explicitly supplied or selected and returns an asset: handle. Pass that handle, with an identity, construction, texture, fit, or style role when known, to image_edit. asset_upload reads from the local machine, so agents must never use it to inspect unrelated files. Hosted MCP clients should use the hosted image-import flow instead; a local file path is not transferable to a remote server.

Run

Node.js 20 or newer is required.

npx -y @gavana.ai/[email protected]

The server reads either:

• GAVANA_BASE_URL and GAVANA_AGENT_TOKEN, or
• the private CLI configuration at ~/.config/gavana/agent.json.

CRAFTBOARD_BASE_URL, CRAFTBOARD_AGENT_TOKEN, and CRAFTBOARD_AGENT_CONFIG_FILE remain supported as transition aliases. The legacy ~/.config/craftboard/agent.json file is also read when the new config does not exist. Gavana-named variables take precedence.

Use a scoped, revocable Agent Access token. Never put the token directly in a shared command, repository, or chat message.

Limit the local server without changing the token:

GAVANA_MCP_READ_ONLY=true npx -y @gavana.ai/[email protected]
GAVANA_MCP_TOOLSETS=canvas,assets npx -y @gavana.ai/[email protected]
GAVANA_MCP_TOOLS=canvas_list,canvas_get npx -y @gavana.ai/[email protected]
GAVANA_MCP_EXCLUDE_TOOLS=node_delete,job_cancel npx -y @gavana.ai/[email protected]

Available toolsets are canvas, recipes, assets, elements, models, actions, images, videos, runs, and opt-in campaigns. Strict read-only mode registers only tools whose annotations guarantee no mutation, generation, cancellation, or reconciliatory write. Every registered tool publishes an output schema.

Elements

Elements are reusable visual references built from existing image assets, guidelines, or both. Read them with element_list, element_get, and element_history; version-pinned reads use element:<id>@v<n>. Full-access connections can use element_create, element_update, element_update_collections, element_restore, and the collection tools element_collection_list, element_collection_create, and element_collection_update. element_archive and element_collection_delete require confirm: true after the user explicitly confirms the affected Element or collection. Archive is recoverable; this package does not expose permanent Element deletion.

The local image_generate, image_edit, and image_variations tools, plus hosted generate_image_in_canvas, accept up to eight version-pinned Elements through elements. Applying Elements requires element:read; image calls that do not use Elements keep their existing scope requirements.

Local image tools return after Gavana creates the durable Canvas targets and queues the Run. Set wait: true only when the completed asset is needed in the same interaction. Otherwise use run_get or read the Canvas later; the queued response already contains the stable Run and destination handles.

For remote clients, use https://app.gavana.ai/mcp or the strict read-only endpoint https://app.gavana.ai/mcp/readonly. Both use browser OAuth with exact redirect binding and PKCE. The hosted default intentionally exposes a smaller, goal-focused catalog than this local developer server.

Hermes Agent

After this package is published, add it to ~/.hermes/config.yaml:

mcp_servers:
    gavana:
        command: npx
        args: ["-y", "@gavana.ai/[email protected]"]
        env:
            GAVANA_BASE_URL: "https://app.gavana.ai"
            GAVANA_AGENT_TOKEN: "${GAVANA_AGENT_TOKEN}"
        tools:
            resources: true
            prompts: false

Store GAVANA_AGENT_TOKEN in ~/.hermes/.env with mode 0600, then start a new Hermes session or run /reload-mcp. Use hermes mcp configure gavana to review the discovered tools and opt into destructive operations deliberately. Keep guide_search, guide_get, and canvas_validate enabled. They are read-only. If a Hermes release does not load MCP resources, the two guide tools remain the canonical fallback.

Canvas Agent Guide

Resource-capable clients can list and read the stable gavana://guides/canvas/v1/* resources. Tool-only clients should call guide_search before an unfamiliar operation and guide_get for the selected topic. Both paths return the same centrally maintained Markdown and guide version.

canvas_validate audits the current graph without changing it. Pass an optional proposed canvas_apply_batch operation list to run a canonical server-side dry-run and report overlap, full-frame Section containment, fake Section headers, orphan generated outputs, broken lineage, unclear connections, destructive impact, and a structured completionReview. After image or workflow finalization, do not claim Done unless completionReview.doneClaimAllowed is true. Product-fidelity uncertainty is a human-review state, never a reason to start another paid provider call.

Chat-first work

work_prepare creates a durable campaign brief, exactly three directions, and a recommendation without starting paid generation. Follow with work_continue to answer, select one direction, adjust, or acknowledge a changed Canvas with rebase: true. work_execute requires confirm: true and a caller-stable idempotency key; it starts only the selected direction and returns durable progress immediately. Use work_get on full or read-only MCP for a pure snapshot; use write-authorized work_refresh to reconcile provider progress. The snapshot contains the latest durable work; it does not observe or finalize provider jobs.

The package, executable (gavana-mcp), Hermes server id, environment variables, repository, API domain, and CLI path use Gavana. The cba_ token prefix and legacy aliases remain compatibility identifiers.

The source catalog proposal is integrations/hermes/manifest.yaml.