Claude Code .mcp.json oauth.scopes: mcp:read first, mcp:write later

Claude Code lets a project pin the OAuth settings for a remote MCP server. The Claude Code MCP docs describe an oauth block in .mcp.json with clientId, callbackPort, authServerMetadataUrl and scopes, read 2026-10-03. scopes is a space-separated string that takes precedence over scopes the server advertises. Sume's hosted MCP server defines two: mcp:read, which is required and read-only, and mcp:write, which is opt-in, per the Sume OAuth page.

{
  "mcpServers": {
    "sume": {
      "type": "http",
      "url": "https://mcp.sume.com/mcp",
      "oauth": { "scopes": "mcp:read" }
    }
  }
}

Why pin the scope

If the server advertises both scopes and the client requests everything, a user may consent to write access without thinking about it. Pinning mcp:read in the project file means a teammate who clones the repo starts with read tools only. A write or paid tool under mcp:read returns insufficient_scope, which is the expected result and not a bug.

Widening later

The Claude Code changelog for 2.1.288 says a re-authenticate prompt now appears when a server asks for more OAuth scope. That fits the pattern: stay on mcp:read, and when a task needs a create tool, widen the scope on purpose and approve the new consent. The MCP specification changelog lists incremental scope consent via WWW-Authenticate for protocol version 2025-11-25, but the Sume docs do not say whether Sume's server uses that flow, so do not assume it.

Things to check

• Server definitions live in local, project or user scope, so check which scope an entry came from when behavior differs from the project file.
• .mcp.json supports ${VAR} and ${VAR:-default} expansion, but the page warns that some credential variables read as empty in remote url and headers.
• Paid and write tools still need an idempotency_key and honor max_spend_usd when provided.
• mcp:paid does not exist; do not request it.