Headless Gemini CLI and MCP auth: use a Sume API key

In a headless environment such as CI, connect the Gemini CLI to Sume's hosted MCP server with an API key sent as Authorization: Bearer <SUME_API_KEY> or x-api-key, not with OAuth. OAuth needs a person to approve a consent page in a browser, and a headless job has nobody to do that.

What the Gemini CLI release notes say

The Gemini CLI releases page lists, in v0.63.0-preview.0 (September 29), "fix(auth): prevent infinite auth loop from file contention, headless keyring, and supervisor state drops". That fix concerns the CLI's own sign-in, not Sume. It does show that interactive auth is a fragile fit for headless runs, which is why an MCP server that answers with an OAuth challenge is a poor target for a client with no browser to complete it.

Why OAuth does not fit a headless run

Sume's hosted MCP sends an OAuth challenge and protected-resource metadata. The client then sends the user to https://mcp.sume.com/oauth/authorize, which continues to a first-party consent page on the MCP host. After sign-in the consent page shows a Read permission that is locked on and a Write toggle that is off by default. That flow is designed for an interactive human.

Use the key without leaking it

Create the key in the Sume dashboard and keep it in your CI secret store. Hand it to the client from the CI secret mechanism rather than writing it into a prompt or a committed file. Sume's guidance is to rotate an API key if it shows up in logs or chat history.

An OAuth access token is not a Sume API key. Do not mint an API key as a way to fake an OAuth client, and do not paste an OAuth token into a prompt.

Bound the spend

An API-key session sees write and paid tools, so a headless agent can start paid generations. The docs give three controls to use before the first paid call:

• dry_run=true preflights the cost without submitting.
• generation_admission_preview shows what admission would decide.
• max_spend_usd caps spend when you pass it. It is enforced only when provided.
• Every write or paid call needs an idempotency_key, so a retried step does not submit twice.

A read-only alternative

If the job only needs to look things up, an OAuth session with mcp:read sees read-only tools only. A mutating tool called without write scope returns insufficient_scope. For a headless job, though, the practical read-only choice is to run the job interactively once and keep the automation on a scoped API key with a spend cap.