Claude Code .mcp.json project scope: keep your Sume API key out of git

Do not put a Sume API key in a project-scope .mcp.json. Claude Code's docs say project-scope servers are stored in .mcp.json in the project root and shared with the team through version control. A key typed into a header there is a key in your repository history. Share the server definition, and keep the credential somewhere that does not travel.

The three scopes

Share the server, not the secret

Commit the definition with no credential:

A quick audit helps: search your repository and its history for the header name you used, and look at pull request diffs that touch .mcp.json. Teams often add a server in project scope for convenience and only later notice that a header line carried a live token. Add a pre-commit check that blocks Authorization strings in that file.

claude mcp add --transport http --scope project sume https://mcp.sume.com/mcp

Why OAuth helps here

Sume's hosted endpoint supports OAuth, so each teammate runs /mcp and signs in on Sume's consent page. Read is locked on, and Write is off until the person turns it on. Claude Code's docs say authentication tokens are stored securely and refreshed automatically, and that Clear authentication in the /mcp menu revokes access. Sume's access token lasts one hour and is not refreshed by Sume, so expect a fresh sign-in about hourly during long sessions.

This also means no teammate ever needs the account's API key just to read tools, check balance or inspect jobs.

When you do need a key

Automation that cannot open a browser, such as CI, needs an API key. Sume accepts Authorization: Bearer or x-api-key, but never both. The docs show the --header option for a bearer token, so the key lands in a config file. Put that server in local or user scope on the machine that runs the job, never in the committed file, and scope the key narrowly: API-key sessions see the full tool set, and paid calls need an idempotency_key, with max_spend_usd available as a per-call ceiling.

If a key ever lands in git, rotate it in the Sume dashboard first and clean history second. Rotation is the step that actually ends the exposure.

Because local scope is the default, a plain claude mcp add without --scope keeps the server private to you, which is the safer habit when a credential is involved.