Claude Code headersHelper: read the Sume API key at connect

Yes. Set headersHelper on the Sume server entry to a command that prints a JSON object such as {"Authorization": "Bearer <key>"}. Claude Code runs it at connect time and merges the output into the request headers, so the key can come from a password manager or secret store instead of a file.

The helper rules come from Claude Code's MCP documentation, read 2026-09-29. Sume accepts an API key as Authorization: Bearer <key> or x-api-key on https://mcp.sume.com/mcp, per MCP OAuth and API keys.

What are the helper's rules?

The page lists a small set of rules. The ones that matter for a Sume key are output format, the time limit, precedence, caching and retry behavior.

What does the Sume entry look like?

Point the helper at an absolute path or a command on PATH, because the working directory depends on where the server was configured. The script below reads the key from an environment variable; swap that line for your secret store's CLI.

{
  "mcpServers": {
    "sume": {
      "type": "http",
      "url": "https://mcp.sume.com/mcp",
      "headersHelper": "/usr/local/bin/sume-mcp-headers"
    }
  }
}

#!/bin/sh
# /usr/local/bin/sume-mcp-headers
printf '{"Authorization":"Bearer %s"}' "$SUME_API_KEY"

Is a project .mcp.json safe to share this way?

A helper is an arbitrary shell command. For a server in a project .mcp.json or at local scope, Claude Code runs it only after you accept the trust dialog for the directory that declares the server. Until then the server connects with its static headers alone. Per the same page, a helper supplied by a repository or plugin runs without credential variables such as ANTHROPIC_API_KEY, so a helper that needs SUME_API_KEY from your environment should be configured at user scope.

What happens when the key is wrong or expired?

If a tool call returns 401 Unauthorized or 403 Forbidden, Claude Code re-runs the helper, reconnects with the fresh headers and retries the call once. Only if that retry also fails does it mark the server as needing authentication in /mcp. Because the helper is the source of the Authorization header, Claude Code does not fall back to OAuth for that server.

That makes the helper the right place to fix a rotated key: change what the script prints, and the next connection or retry picks it up. There is no cache to clear, since the page says the command runs fresh on each connection and Claude Code does not cache the result.

Helper or environment variable?

Use an environment variable in headers when the key is already exported, as with ${SUME_API_KEY} in the headers field. Use a helper when the key must be fetched or refreshed at connect time. An API-key session sees the full hosted tool set including paid tools, so scope who can run the helper. The trade-off with OAuth is in MCP server API key vs OAuth.