Remote MCP with an API key: x-api-key or Bearer on Sume?

Either header works. Hosted Sume MCP accepts your Sume API key as Authorization: Bearer <SUME_API_KEY> or as x-api-key: <SUME_API_KEY>, and the session sees the full hosted tool set. Choose the header your client can set from an environment variable without writing the secret into a config file you commit.

A key session is the path for automation that cannot do an interactive OAuth consent, such as a job on a server. It does not skip the other gates: every write or paid call must still carry an idempotency_key, spending is governed by the wallet and admission, and the optional max_spend_usd is enforced only when you send it.

Key session vs OAuth session

The table restates the Sume MCP OAuth page, read 2026-10-09.

Keeping the key out of the wrong places

The credential rules in the docs apply to both credentials. Do not paste a key or token into a prompt, do not store OAuth tokens in CLI config, and do not forward either to third-party providers. If a key appears in logs or chat history, rotate it. Keys are created in the dashboard under API keys.

A related rule runs the other way. An OAuth token is not a Sume API key, and one cannot stand in for the other, so do not mint a key for a hosted OAuth client as a way around a missing scope.

A first-call checklist for a key session

Before the first paid call, spend a minute on four reads and one preview.

• mcp_health confirms the endpoint and the auth source.
• tools_list shows what this session can call; a key session lists the write and paid tools too.
• account_me and balance_get confirm the workspace and the money available.
• generation_admission_preview or dry_run=true previews cost before the first paid submit. The docs recommend it before expensive bursts, not for every single create.

When to prefer OAuth anyway

If a person is at the keyboard, OAuth gives you a smaller blast radius: leave Write off and the session cannot spend. A key session has no such switch, so keep its use to jobs where you have already decided what the agent may buy.

Worked example: a nightly job

Suppose a server job runs at night and needs to list yesterday's jobs and read the balance. It does not need a human consent screen, so a key session fits. Store the key in the job's secret manager, load it into an environment variable, and have the MCP client read that variable into the header. If the job only reads, you still get the full tool set on a key session, so the prompt must say plainly that the job is read-only and must not call paid tools.

If you would rather have a hard guarantee that nothing can be bought, use an OAuth session with Write off for that job. The tools are then not merely discouraged; they are hidden. That difference, between a rule in a prompt and a rule in the connection, is the main reason to choose OAuth even for scheduled work when a person can complete the one-time consent.