Connect Gavana to Grok
Grok Build — xAI’s terminal CLI — is the supported path. It speaks remote MCP over HTTP, runs the OAuth flow for you on first use, and stores the tokens itself. The grok.com connector surface exists too, but Gavana does not accept it yet; see the Grok 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.
Add the server
The quickest route is the CLI:
grok mcp add --transport http gavana https://app.gavana.ai/mcpAdd --scope project to write the entry into the current project rather than your user configuration.
Or declare it directly in ~/.grok/config.toml:
[mcp_servers.gavana]
url = "https://app.gavana.ai/mcp"No credential goes in this file. Gavana’s hosted endpoints use OAuth, and Grok triggers a browser flow on first use, storing tokens in ~/.grok/mcp_credentials.json. The --header flag exists for servers that authenticate with a static bearer token — Gavana is not one of them, so leave it off.
Two optional fields on the entry are worth knowing:
| Field | Default | What it does |
|---|---|---|
startup_timeout_sec | 30 | How long Grok waits for the server to come up |
tool_timeout_sec | 6000 | Per-tool timeout — generous enough for generation calls |
Sign in and verify
The OAuth flow starts on the first call, so just use a Gavana tool and approve the consent screen when the browser opens.
grok mcp listshows what is configured, and
grok mcp doctor gavanadiagnoses configuration and connectivity — it is the first thing to run when something is wrong. Add --json for machine-readable output.
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.Grok also reads MCP servers from ~/.claude.json, .cursor/mcp.json, and a project .mcp.json. If you have already configured Gavana for Claude Code or Cursor, Grok may pick that entry up on its own — including a local server holding a Personal Access Token. Run grok mcp list before adding anything, so you do not end up with two Gavana servers on different credentials.
The Grok app
Grok’s own connector surface lives at grok.com/connectors — New Connector, then Custom, then the MCP server URL and any required authentication. xAI requires the server to be reachable over the public internet, which Gavana’s hosted endpoints are.
Gavana does not currently support this path. When a request to a hosted Gavana endpoint arrives with an Origin header, that origin must be on Gavana’s browser allowlist or the request is rejected with 403 access_denied. The default allowlist is exactly https://chatgpt.com and https://claude.ai; https://grok.com is not on it, and only Gavana operators can extend the list. Use Grok Build instead.
xAI’s documentation does not state whether a Grok connector reaches the MCP server from xAI’s own infrastructure or from the browser, so we cannot say in advance whether that check would fire. Until grok.com is allowlisted and the path is tested end to end, the CLI is the one to use. Grok Build sends no Origin header, so the allowlist never applies to it.
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
Grok Build 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:
grok mcp add gavana -- npx -y @gavana.ai/mcp@0.2.0The server needs GAVANA_BASE_URL and GAVANA_AGENT_TOKEN in its environment, and 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. GAVANA_MCP_READ_ONLY=true gives a hard read-only server, and GAVANA_MCP_TOOLSETS narrows the catalog; scoping the token is still the stronger control.
A Personal Access Token in a shell command lands in your shell history, and in a config file it is a live credential on disk. Keep either out of any repository. If it leaks, revoke that token immediately and create a new one — see the safety contract.
Disconnect
grok mcp remove gavanaThen revoke the OAuth delegation from Gavana’s Personal Access Tokens screen — revocation takes effect on the next request. Deleting ~/.grok/mcp_credentials.json clears the local tokens but does not revoke them server-side. If you used the local stdio path, revoke the Personal Access Token as well.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| Server not listed | Entry written to a project scope in another directory | Re-add without --scope project, or run from that directory |
| Every call is unauthorized | OAuth not completed | Trigger a Gavana tool and approve the browser prompt |
| Two Gavana servers appear | Grok also read ~/.claude.json or .cursor/mcp.json | Run grok mcp list and remove the one you do not want |
| Connection or tool calls time out | Defaults too tight for this workload | Raise startup_timeout_sec or tool_timeout_sec |
| Generation is refused | Token lacks image:generate or video:generate | Re-authenticate and approve the generation scopes |
403 access_denied from the Grok app | Origin not on Gavana’s allowlist | Use Grok Build; the app connector is not supported |
grok mcp doctor gavana covers most of the above in one command.
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 xAI.