Connect Gavana to Hermes

Hermes Agent — Nous Research’s agent — connects to Gavana over remote MCP with browser OAuth. It handles discovery, dynamic client registration, PKCE, token exchange, and refresh on its own, so the whole configuration is two lines.

Connect with full access

https://app.gavana.ai/mcp

This is the default Gavana connection. It requests all eight permissions and remains active until you disconnect or revoke it.

Add the server

Hermes reads MCP servers from the top-level mcp_servers key in its config.yaml.

Normal connection:


mcp_servers:
  gavana:
    url: "https://app.gavana.ai/mcp"
    auth: oauth

That is the whole entry. auth: oauth is what tells Hermes to run the OAuth 2.1 flow rather than send the request unauthenticated, and Gavana supports dynamic client registration, so there is no client ID or secret to supply.

The key is mcp_servers at the top level of the file — not mcp: with a nested servers:. Hermes reads manual MCP definitions from mcp_servers only, so an entry in the wrong place is silently ignored rather than reported as an error.

MCP support ships with the standard Hermes install; there is nothing extra to add.

Apply and verify

Hermes picks up configuration changes without a restart:


/reload-mcp

Then confirm the tools actually arrived:


Tell me which MCP-backed tools are available right now.

Hermes discovers and registers tools at startup, so a correct entry shows Gavana’s tools in that answer. Follow it with something read-only:


Using Gavana, list my canvases and read the most recently updated one. Report its
handle, revision, node count, and connection count. Do not change anything.

Narrowing what Hermes sees

Hermes supports per-server filtering, so you can expose only the tools you want:

Field	What it does
`tools.include`	Allowlist specific tools
`tools.exclude`	Blocklist specific tools
`tools.resources`	Toggle resource utilities
`tools.prompts`	Toggle prompt utilities

Useful for keeping the agent focused, but treat it as ergonomics rather than a safety boundary — the endpoint you point at is the boundary. A full-endpoint connection with the generation tools excluded is still a full-endpoint connection.

Resulting permission surface

Read-only endpoint

Can	Cannot
List and read canvases	Create, update, move, or delete anything
Validate a canvas graph	Save an image
Preview a canvas or get a review link	Create or run a workflow
Read Gavana’s own agent guidance	Discover video models, or generate an image or a video
	Spend a single credit

Tools exposed: guide_search, guide_get, canvas_list, canvas_get, canvas_validate, get_canvas_image, open_canvas, element_collection_list, element_get, element_history, and element_list — 11 in total. It issues canvas:read and element:read.

find_video_models is absent even though it only reads. It requires video:generate, and this endpoint never issues that scope.

Cost exposure: none.

Full endpoint

Sixteen tools: everything above, plus canvas writes, workflow authoring, and generation. Three of them can charge your connected AI provider — run_canvas_workflow, generate_image_in_canvas, and generate_video. Full schemas: hosted MCP tools.

Cost exposure: real.

The full endpoint’s OAuth consent requests canvas:read, canvas:write, asset:read, element:read, element:write, image:generate, video:generate, and job:manage. There is no partial approval on this path.

The local stdio server

Hermes runs local stdio servers and remote HTTP servers from the same config, so Gavana’s local server is an alternative rather than a different setup. It exposes 57 tools instead of 29 and authenticates with a Personal Access Token rather than OAuth. Use command, args, and env in place of url and auth:


mcp_servers:
  gavana:
    command: "npx"
    args: ["-y", "@gavana.ai/mcp@0.2.0"]
    env:
      GAVANA_BASE_URL: "https://app.gavana.ai"
      GAVANA_AGENT_TOKEN: "PASTE_YOUR_TOKEN_HERE"

Needs Node.js 20 or newer. The real permission surface here is the token’s scopes, not the tool list — a tool called outside them fails with a permission error. Add GAVANA_MCP_READ_ONLY: "true" for a hard read-only server, or GAVANA_MCP_TOOLSETS to narrow the catalog; scoping the token is still the stronger control.

config.yaml now contains a live credential. Keep it out of any repository and out of backups you share. If it leaks, revoke that token immediately and create a new one — see the safety contract.

Elicitation

Hermes supports MCP elicitation, where a server asks the agent to generate text on its behalf, with a configurable timeout that defaults to 300 seconds. Gavana’s hosted tools do not use it — every Gavana tool takes its input from the caller — so the default is fine and there is nothing to configure.

Disconnect

Remove the gavana entry from mcp_servers and run /reload-mcp. Then revoke the OAuth delegation from Gavana’s Personal Access Tokens screen — revocation takes effect on the next request. If you used the local stdio path, revoke the Personal Access Token as well.

Troubleshooting

Symptom	Cause	Fix
Entry ignored entirely	Written under `mcp:` `servers:` instead of top-level `mcp_servers:`	Move it to `mcp_servers:`
Tools do not appear after an edit	Config not reloaded	Run `/reload-mcp`
Every call is unauthorized	`auth: oauth` missing	Add it and reload
Fewer tools than expected	`tools.include` or `tools.exclude` is filtering them	Check the filter on the entry
Generation is refused	Token lacks `image:generate` or `video:generate`	Re-authenticate and approve the generation scopes

More: MCP troubleshooting.

Security notes

The hosted endpoints accept OAuth bearer tokens only. Do not attempt to use a cba_… Personal Access Token there — that is the local MCP and API path.
Webhooks are not available through MCP by design: a signing secret must never enter model-visible tool arguments or tool logs. Use the CLI or the API when you need callbacks.
Generation charges the AI provider connection on your Gavana account, not Nous Research.