Other clients

Gavana is a standard MCP server on both surfaces, so any compliant client works. There are only two things to configure.

Hosted: give it a URL

	Hosted MCP
URL	`https://app.gavana.ai/mcp`
Transport	Streamable HTTP
Auth	OAuth 2.1, authorization code, PKCE `S256`
Client auth	`none` — public client
Scopes requested	all eight
Tools	29

Everything else is discoverable. Your client finds the authorization endpoint, token endpoint, registration endpoint, and supported scopes from Gavana’s published metadata:

https://app.gavana.ai/.well-known/oauth-authorization-server
https://app.gavana.ai/.well-known/oauth-protected-resource/mcp

Dynamic client registration is open at https://app.gavana.ai/oauth/register. Your registration must declare 1–10 exact HTTPS or local-loopback redirect URIs and token_endpoint_auth_method of none. Confidential clients with a secret are rejected — this is a public-client-with-PKCE server.

The endpoint is stateless JSON-RPC over POST. A GET returns 405; that is expected and not a misconfiguration.

ChatGPT

ChatGPT connects as a custom connector. https://chatgpt.com is an allowed browser origin on the hosted endpoint.

gavana mcp config chatgpt returns the endpoint plus this instruction: add the endpoint as a custom MCP connector, then complete Gavana OAuth in the browser. There is no generated config file — the whole setup is the URL and the consent screen.

Open custom connector setup

Your workspace may require an administrator to allow custom connectors first.

Add one Gavana endpoint


https://app.gavana.ai/mcp

The consent screen requests all eight permissions: canvas, asset, Element, image, video, and job access. Read the list before approving.

Two hosted tools are shaped specifically for a ChatGPT-style client. save_image_to_canvas accepts a client-supplied image file directly through its image parameter, so an image ChatGPT just created becomes a durable Gavana node without a public URL. And get_canvas_image returns an inline preview the model can actually look at, alongside a temporary full-resolution link.

Hermes

Hermes reads MCP servers from ~/.hermes/config.yaml:


mcp_servers:
    gavana:
        command: npx
        args: ["-y", "@gavana.ai/mcp@0.2.0"]
        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 rather than accepting all 57 at once.

Keep guide_search, guide_get, and canvas_validate enabled whatever else you cut. All three are read-only and free, and if a Hermes release does not load MCP resources, the two guide tools are the canonical fallback for reading the Canvas Agent Guide.

Local stdio: any client

The local server exposes 57 tools across 10 toolsets. You need Node.js 20 or newer and an Agent Access token.


npx -y @gavana.ai/mcp@0.2.0

It reads either:

GAVANA_BASE_URL and GAVANA_AGENT_TOKEN from the environment, or
the private CLI configuration at ~/.config/gavana/agent.json, written by gavana auth login.

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

The published executable is gavana-mcp. gavana mcp config local prints the whole definition — command, args, environment, and credential source — if you would rather copy it than retype it.

Narrowing the local server

Four environment variables restrict what gets registered, without changing the token:


GAVANA_MCP_READ_ONLY=true npx -y @gavana.ai/mcp@0.2.0
GAVANA_MCP_TOOLSETS=canvas,assets npx -y @gavana.ai/mcp@0.2.0
GAVANA_MCP_TOOLS=canvas_list,canvas_get npx -y @gavana.ai/mcp@0.2.0
GAVANA_MCP_EXCLUDE_TOOLS=node_delete,job_cancel npx -y @gavana.ai/mcp@0.2.0

Toolsets are canvas, recipes, assets, models, actions, images, videos, runs, and the opt-in campaigns. Strict read-only mode registers only tools whose annotations guarantee no mutation, generation, cancellation, or reconciliatory write.

The token’s scopes are the real boundary. Tool filtering narrows what is offered; the scopes decide what can succeed. Use both.

@gavana.ai/mcp is published on the public npm registry at version 0.2.0 and installs the gavana-mcp executable, so npx -y @gavana.ai/mcp@0.2.0 resolves without extra configuration. If npx cannot resolve it, your environment is proxying npm through a private registry that does not mirror the package. Use a hosted endpoint instead, or run from a checked-out application repository with bun run canvas:mcp if you have access.

The Canvas Agent Guide

Resource-capable clients can list and read the stable gavana://guides/canvas/v1/ resources, starting from gavana://guides/canvas/v1/index. Tool-only clients call guide_search and then guide_get. Both paths return identical Markdown and the same guide version, so nothing is lost by having only tools.

Verify any client

Confirm the tool count — 11, 29, or 57.
Call guide_search. It requires no scope, so success isolates transport from permissions.
Call canvas_list. Success confirms the token is delegating the account you expect.

Authentication Local tools reference Hosted tool guide Troubleshooting