Claude Code headersHelper for a Sume API key: rotate with no edits

Use headersHelper in .mcp.json when a Sume API key must come from a secrets store. Claude Code runs the helper fresh on each connection and expects a JSON object of string pairs on stdout, so a rotated key takes effect on the next connect. The helper has a 10-second limit, which is the Claude Code docs' figure.

Entry and helper

Point the entry at a script. The script refuses to run if the variable is missing, so a blank bearer never reaches Sume.

# .mcp.json
{
  "mcpServers": {
    "sume": {
      "type": "http",
      "url": "https://mcp.sume.com/mcp",
      "headersHelper": "/opt/bin/sume-headers.sh"
    }
  }
}

# /opt/bin/sume-headers.sh (chmod +x)
#!/bin/sh
: "${SUME_API_KEY:?set SUME_API_KEY}"
printf '{"Authorization":"Bearer %s"}\n' "$SUME_API_KEY"

Where this fits in Sume's auth model

Sume's hosted MCP accepts OAuth tokens or API keys, never one in place of the other. The quickstart's Claude Code path is claude mcp add --transport http sume https://mcp.sume.com/mcp and then claude mcp login sume, which uses OAuth and is the preferred interactive route. A helper is for unattended runs that need write and paid tools, because an API-key session sees the full set.

• OAuth tokens are not API keys. Do not store them in CLI config or forward them to other providers.
• Do not mint API keys for hosted OAuth clients as a workaround.
• If a key shows up in logs or chat history, rotate it in the dashboard.
• Paid and write calls still need idempotency_key.

Rotation check

After rotating, restart the session and ask the agent for mcp_health. Its authenticated.auth_source shows which credential the server saw. If the helper prints an empty value, Sume rejects the request before any tool runs, so a failed connect is the visible symptom.

Walkthrough

Create the key in the dashboard and store it in your secrets manager, not in the repository. Export it in the shell that launches Claude Code, or let the helper read it from the manager's command line tool. Make the script executable and run it once by hand: it should print one JSON line and exit zero. Then start Claude Code and check the server status.

Because the helper runs on every connection, it must be fast and quiet. Anything written to stdout other than the JSON object breaks the parse, so send diagnostics to stderr.

Mistakes to avoid

Do not commit .mcp.json with a literal key in it. Do not echo the key into a shared terminal log while testing. Do not point two projects at one key if you want to know which agent made a paid call; separate keys make rotation and review easier. Finally, remember that the helper only changes how headers are produced. It does not change what the key can do, so paid tools remain callable by anything holding the key.

Teams often ask whether a helper is better than OAuth. For one person at a keyboard, OAuth is simpler and safer, because the grant is read-only by default and the token never touches a script. A helper earns its place in scheduled or headless runs, where nobody can click through a consent page. In that case, keep the key's reach in mind and review the paid tool list in the Sume docs before you hand an agent the key.