OAuth token minted for Claude.ai sessions has empty scope set — blocks all Stackbilt MCP tool calls

[stackbilt-admin]

Bug

Claude.ai MCP sessions authenticated through stackbilt-mcp-gateway receive tokens with no scopes assigned. Every Stackbilt MCP tool call fails with an error of the shape:

MCP error -32600: Tool "<tool_name>" requires one of these scopes: read, generate. Your token has: (none).

Scope of blast

Confirmed blocked during a 2026-04-11 session attempting to dogfood the scaffold engine on new Stackbilt infrastructure work:

• mcp__claude_ai_Stackbilt__scaffold_create → blocked (requires generate)
• mcp__claude_ai_Stackbilt__scaffold_status → blocked (requires read or generate)
• mcp__claude_ai_Stackbilt__image_list_models → blocked (requires read or generate)

The last one is the smoking gun — image_list_models is a read-only model catalog. If it fails with (none) scopes, the issue is gateway-wide scope provisioning, not scaffold- or image-specific.

Expected behavior

Tokens minted by stackbilt-mcp-gateway for authorized Claude.ai sessions should carry at minimum the read and generate scopes so the downstream internal tool servers behind the gateway can serve the canonical MCP surface.

Likely root cause surface (not yet verified)

One of:

1. OAuth token mint step in the gateway is not including the scope claim
2. Scope claim is present but under the wrong JWT field name (scope vs scopes vs scp)
3. Downstream tool servers are reading the claim from a different field than the gateway writes to
4. Claude.ai's OAuth discovery flow is requesting () scopes instead of read generate

A 15-minute trace of the token as it moves from Claude.ai OAuth callback → gateway mint → tool server scope check would pinpoint it.

Operator impact

This is a hard block on every Stackbilt MCP tool from Claude Code sessions. It was discovered while attempting to dogfood scaffold_create on the new stackbilt-emdash worker scaffold (hosting substrate for the aegis#453 wiki pilot). Manual scaffolding is the fallback, but the whole point of dogfooding was to find gaps like this — so this issue is the payoff for that exercise.

Cross-links

• Stackbilt-dev/aegis#453 — wiki pilot that was trying to use scaffold_create as its starting point
• Stackbilt-dev/aegis#456 — wiki-as-Pro-platform-bonus roadmap (depends on scaffold tooling working end-to-end for downstream Pro-tier tenant provisioning)

Priority

Not a pilot-blocker (I can hand-scaffold), but a regression on the "our tools are the first to stress-test our own infrastructure" thesis. Should be fixed before the next dogfood attempt — which is probably the wiki-lint plugin scaffold in ~1 week.

[stackbilt-admin]

Review — likely dupe of #28 + #29; confirm before closing

The smoking gun is image_list_models failing with (none) scopes. That tool is a read-only model catalog — if it blocks on empty scopes, the problem is the gateway-wide scope-provisioning path, not anything specific to scaffold or image surfaces. That rules out "tool-specific scope check bug" and points directly at the same code path as #28 and #29.

Two candidate root causes, which map cleanly onto the other open issues:

1. Empty-scope OAuth initiate from Claude.ai → grant created with oauthReqInfo.scope = [], every level empty, every tool call blocked. Same mechanism as oauth: Claude Code MCP client gets zero scopes — scaffold_create unreachable from the assistant #28 (just from a different client). Closed by the consent-screen fix proposed there.
2. Legacy grant from a pre-256ba06 Claude.ai session → stale encryptedProps.scopes inherited through refresh-token exchange. Same mechanism as oauth: fall back to grant.scope when ctx.props.scopes is empty (fixes legacy grants) #29. Closed by the grant.scope fallback proposed there.

Either is consistent with the observed (none) symptom. Don't close as duplicate yet — the 15-minute trace proposed in the issue body is the right call. Specifically:

Trace checklist

1. Fresh Claude.ai session attempts an OAuth authorize against mcp.stackbilt.dev
2. Capture oauthReqInfo.scope at oauth-handler.ts:606 or :706 — is it [] or populated?
3. If populated, the grant should be correct; the bug is downstream (probably resolveAuth)
4. If [], confirm whether the session is legacy (refresh-token path) or fresh
5. Inspect the minted access token — does it carry a scope claim at all? If yes, what field name (scope vs scopes vs scp)?

The fourth root-cause hypothesis in the issue body ("Claude.ai's OAuth discovery flow is requesting () scopes instead of read generate") is the one to confirm or rule out first. A 60-second inspection of the authorize URL Claude.ai hits would answer it.

Decision tree after trace

• If empty-scope initiate → close as dupe of oauth: Claude Code MCP client gets zero scopes — scaffold_create unreachable from the assistant #28, reference the consent-screen fix
• If legacy refresh inheriting stale props → close as dupe of oauth: fall back to grant.scope when ctx.props.scopes is empty (fixes legacy grants) #29, reference the grant.scope fallback
• If separate JWT mint surface with its own scope bug → keep open, this is a third distinct bug and needs its own fix

Tracking this issue separately until the trace confirms which branch applies is the right move — closing as dupe prematurely would hide a possible third bug.

Related

• oauth: Claude Code MCP client gets zero scopes — scaffold_create unreachable from the assistant #28 — OAuth consent-screen fix for empty-scope initiates (new grants)
• oauth: fall back to grant.scope when ctx.props.scopes is empty (fixes legacy grants) #29 — resolveAuth fallback for legacy grants with stale encrypted props

[stackbilt-admin]

Edit: scrubbed two internal service names from the Expected behavior section per outbound disclosure hygiene. Functional meaning preserved — the gateway still has downstream tool servers behind it, they just don't need to be named in a public repo issue. No impact on the bug report or the reproduction steps.