Connect Gavana to Gemini

Gemini CLI is the supported path. It speaks streamable HTTP, discovers Gavana’s OAuth endpoints on its own, and needs no client ID or secret. The consumer Gemini web app has a custom-connector surface too, but Gavana does not currently accept it — see the web app section below.

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.

Configure Gemini CLI

Gemini CLI reads mcpServers as a top-level key in settings.json. Two scopes:

~/.gemini/settings.json    user scope — every Gemini CLI session
.gemini/settings.json      project scope — this repository only

Normal connection, in either file:

{
  "mcpServers": {
    "gavana": {
      "httpUrl": "https://app.gavana.ai/mcp"
    }
  }
}

That is the whole entry. No oauth block is needed: Gavana supports dynamic client registration, so Gemini CLI discovers the authorization and token endpoints from server metadata and registers itself.

To raise the connect timeout, add timeout in milliseconds:

{
  "mcpServers": {
    "gavana": {
      "httpUrl": "https://app.gavana.ai/mcp",
      "timeout": 30000
    }
  }
}

Or use the one-liner

gemini mcp add writes the normal connection into settings.json for you:

gemini mcp add --scope user --transport http gavana https://app.gavana.ai/mcp

Use --scope project to write into .gemini/settings.json instead. Without --scope, the command defaults to project scope.

gemini mcp list shows what is configured; gemini mcp remove gavana takes it back out.

Authenticate and verify

Changes to mcpServers require a Gemini CLI restart. Restart, then inside the CLI run:

/mcp

You should see gavana with its URL, a CONNECTED status, and the discovered tools.

If the first call comes back 401, that is the OAuth handshake asking to start. Run:

/mcp auth gavana

Gemini CLI opens your browser, you sign in to Gavana and approve the consent screen, and the authorization code is exchanged for tokens automatically. Tokens land in ~/.gemini/mcp-oauth-tokens.json and are refreshed for you.

Then ask for 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.

Resulting permission surface

Read-only endpoint

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.

If you want tighter control than the endpoint choice gives you, Gemini CLI also accepts includeTools and excludeTools arrays on the server entry. Treat that as ergonomics, not a security boundary — the endpoint is the boundary.

The local stdio server

Gemini CLI can also launch Gavana’s local server as a child process, which exposes 57 tools instead of 29 and authenticates with a Personal Access Token rather than OAuth. Use command, args, and env instead of httpUrl:

{
  "mcpServers": {
    "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.

Gemini CLI only shows a stdio server as CONNECTED when the current folder is trusted. Run gemini trust on the folder if /mcp reports it as disconnected.

The Gemini web app

The consumer Gemini web app at gemini.google.com does have a custom MCP connector surface — Connected Apps for Gemini Spark, where you paste an MCP server URL. It carries heavy eligibility gates: you need access to Gemini Spark, you must be 18 or over and in the US, signed in with a personal Google Account (work and school accounts are excluded for now), with Keep Activity on, in English. Custom apps can only be added from the web app, though once added they work in the mobile app too. The path is Settings & help → Connected Apps — or Personal Intelligence → Connected Apps if the first is not there — then Add a custom app.

The vendor surface exists; Gavana’s allowlist does not yet include it. Nothing about the Gemini web app needs to change for this to work — it is a Gavana-side configuration, and this page will be updated if that changes.

CLIs, IDE processes, and server-to-server callers send no Origin header at all, so the allowlist never applies to them. That is why Gemini CLI is unaffected.

Disconnect

Remove the gavana entry from settings.json — or run gemini mcp remove gavana — and restart the CLI. Then revoke the OAuth delegation from Gavana’s Personal Access Tokens screen; revocation takes effect on the next request. Deleting ~/.gemini/mcp-oauth-tokens.json clears the stored tokens locally but does not revoke them server-side.

If you used the local stdio path, revoke the Personal Access Token as well.

Troubleshooting

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 Google.

Related

• Connection overview
• Other clients
• The safety contract
• MCP authentication
• Hosted MCP tools
• Local MCP tools
• Create an Agent Access Token