[Gap]: Document dcrConfig for embedded auth server OAuth2 upstreams

[danbarr]

What needs documentation?

docs/toolhive/guides-k8s/embedded-auth-server-k8s.mdx documents oauth2Config upstream providers with only static clientId/clientSecretRef provisioning (see the GitHub example under "Using an OAuth 2.0 upstream provider"). It doesn't mention dcrConfig, which lets the embedded auth server register itself with the upstream automatically via RFC 7591 Dynamic Client Registration instead of requiring a pre-provisioned client ID/secret. Today dcrConfig is documented only in the CRD reference schema (mcpexternalauthconfig reference), not in this hands-on guide.

Worth covering:

• dcrConfig.discoveryUrl (RFC 8414 discovery) vs dcrConfig.registrationEndpoint (direct, bypassing discovery)
• It's mutually exclusive with clientId/clientSecretRef
• authorizationEndpoint and tokenEndpoint are still required on oauth2Config even when using dcrConfig (CRD-level requirement, easy to miss)
• Optional fields: initialAccessTokenRef, softwareId, softwareStatement
• Operational note for the "Configure session storage" section: DCR-issued credentials are cached in the same store as sessions, so without Redis-backed storage, a pod restart re-registers a new client with the upstream instead of reusing the old one, orphaning the previous registration

Context and references

• Found while rewriting the Notion remote MCP guide: stacklok/docs-website#1004
• Working example now live in docs/toolhive/guides-mcp/notion-remote.mdx (Kubernetes tab), validated end-to-end against a real cluster and Notion's live DCR endpoint

Use case

Upstream OAuth2 providers that only support DCR (no dashboard app registration), like Notion's remote MCP server, have no guidance in the primary embedded-auth-server how-to guide. Readers have to already know dcrConfig exists to find it in the CRD reference.

Additional context

None

[danbarr]

Verified the scope bullets against the toolhive source (v0.40.1 and current main) while reviewing PR #1053. Everything holds except one item:

• softwareId and softwareStatement are accepted by the CRD and plumbed into the run config (cmd/thv-operator/pkg/controllerutil/authserver.go:881-882, pkg/authserver/config.go:477-485), but they're never sent in the registration request. performRegistration (pkg/auth/dcr/resolver.go:800-807) builds the RFC 7591 request with only redirect URIs, client name, auth method, grant/response types, and scope, and oauthproto.DynamicClientRegistrationRequest has no software_statement field at all. The only software_id handling in the codebase is the inbound, client-facing DCR endpoint, which is the opposite direction. Dropping these two from scope until they're actually wired through.
• initialAccessTokenRef is real: sent as a Bearer header on the registration call (resolver.go:784-818).

The rest checked out: exactly-one-of discoveryUrl/registrationEndpoint and the clientId/clientSecretRef mutual exclusion are CEL-enforced, authorizationEndpoint/tokenEndpoint remain required even with discovery (explicit values override discovered ones), and the session-store behavior is as described (pkg/authserver/embeddedauthserver.go:192-201), including the orphaned-registration-on-restart consequence with in-memory storage.