Document baselineClientScopes on MCPExternalAuthConfig embedded auth server

[jhrozek]

Background

PR stacklok/toolhive#5233 added a baselineClientScopes field to the EmbeddedAuthServerConfig portion of the MCPExternalAuthConfig CRD. It fixes the Claude Code DCR scope-narrowing bug: a client that registers with scope: "openid" but later requests offline_access at /oauth/authorize was getting invalid_scope. Operators can now declare a baseline that the embedded auth server unions into every DCR registration, so the client's registered set always covers what it'll later request.

Raised by @tgrunnagle in PR #5233 review F9. Filed here in the docs-website repo because the toolhive PR generated docs/operator/crd-api.md only — user-facing prose belongs here.

What's needed

Add user-facing documentation to the auth/operator guides covering:

• What baselineClientScopes does (and what RFC 7591 §3.2.1 allows).
• The canonical motivating scenario: Claude Code (and other clients that narrow scope at /oauth/register) — without this knob they get invalid_scope at /oauth/authorize.
• When to set it: typically ["offline_access"], occasionally ["openid", "offline_access"]. Should NOT be used to inject privileged scopes.
• Worked example with a complete MCPExternalAuthConfig of type: embeddedAuthServer showing spec.embeddedAuthServer.baselineClientScopes in context.
• Cross-link to the auto-generated CRD reference in toolhive's docs/operator/crd-api.md.

Suggested home

Likely fits under toolhive/guides-k8s/auth-k8s (or wherever the embedded auth server is documented today).

Out of scope

• Code changes — those land in stacklok/toolhive.

References

• Feature PR: stacklok/toolhive#5233
• Original issue: stacklok/toolhive#5224
• Trey's review note: PR #5233 F9