Update docs-website for authServerRef and combined auth patterns

[tgrunnagle]

Description

Document the new authServerRef field on MCPServer and MCPRemoteProxy resources in the docs-website, including the combined embedded auth server + outgoing auth configuration pattern and updated YAML examples. This enables users to understand and adopt the preferred approach for configuring the embedded authorization server alongside outgoing auth types like AWS STS.

Context

RFC-0050 adds an authServerRef field to MCPServerSpec and MCPRemoteProxySpec that separates the embedded authorization server (incoming auth) from externalAuthConfigRef (outgoing auth). This allows the embedded auth server to be configured alongside any outgoing auth type on the same resource. The docs-website currently documents the embedded auth server only via externalAuthConfigRef and does not cover the combined auth pattern. See RFC-0050 for full design details.

Dependencies: Depends on ITEM-003 (CRD types, controller logic, and unit tests) being merged first so that the new field exists in the released operator.
Blocks: None

Acceptance Criteria

• The Kubernetes auth guide (docs/toolhive/guides-k8s/auth-k8s.mdx) documents authServerRef as the preferred way to configure the embedded authorization server, with updated YAML examples using the new field
• The embedded auth server concept page (docs/toolhive/concepts/embedded-auth-server.mdx) mentions the authServerRef field and its relationship to externalAuthConfigRef
• The AWS STS integration tutorial (docs/toolhive/integrations/aws-sts.mdx) includes an example or section showing how to combine the embedded auth server (authServerRef) with AWS STS (externalAuthConfigRef) on an MCPRemoteProxy
• The backend auth concept page (docs/toolhive/concepts/backend-auth.mdx) references the combined auth pattern where the embedded auth server handles incoming auth and a separate outgoing auth type (e.g., AWS STS) handles backend credentials
• Updated YAML examples use the authServerRef field syntax (kind: MCPExternalAuthConfig, name: <config-name>) and show both MCPServer and MCPRemoteProxy usage
• Backward compatibility is documented: existing externalAuthConfigRef with type: embeddedAuthServer continues to work
• All updated pages pass npm run build without errors
• Code reviewed and approved

Technical Approach

Recommended Implementation

Update the existing documentation pages to incorporate the new authServerRef field. The primary changes are:

1. docs/toolhive/guides-k8s/auth-k8s.mdx: Update the "Set up embedded authorization server authentication" section (Approach 5). Change Step 5 to show authServerRef as the preferred configuration path. Add a note that externalAuthConfigRef with type: embeddedAuthServer still works for backward compatibility. Update the YAML example for the MCPServer to use authServerRef instead of externalAuthConfigRef.

2. docs/toolhive/integrations/aws-sts.mdx: Add a new section (or extend Step 4) showing how to combine the embedded auth server with AWS STS on an MCPRemoteProxy. This is the primary use case motivating RFC-0050. Include a complete YAML example with both authServerRef and externalAuthConfigRef on the same resource.

3. docs/toolhive/concepts/embedded-auth-server.mdx: Add a brief section explaining that authServerRef is the preferred field for configuring the embedded auth server on MCPServer and MCPRemoteProxy resources, and that it can be used alongside externalAuthConfigRef for outgoing auth types. Update the MCPServer vs. VirtualMCPServer table to mention authServerRef.

4. docs/toolhive/concepts/backend-auth.mdx: In the "Built-in AWS STS support" subsection or nearby, mention that the embedded auth server can now be combined with AWS STS (or any outgoing auth type) on the same resource using authServerRef.

Patterns & Frameworks

• Follow the Docusaurus conventions documented in the docs-website CLAUDE.md (front matter, admonitions, code block titles, line highlights)
• Follow the docs-website writing style guide: US English, sentence case headings, active voice, second person ("you"), Oxford comma
• Use :::info, :::note, or :::tip admonitions for backward compatibility notes and recommendations
• Use code block titles (e.g., title="mcp-server-auth-server-ref.yaml") and line highlights for new fields

Code Pointers

• docs/toolhive/guides-k8s/auth-k8s.mdx - Primary Kubernetes auth guide; "Set up embedded authorization server authentication" section (around line 455) needs authServerRef updates and new YAML examples
• docs/toolhive/integrations/aws-sts.mdx - AWS STS tutorial; Step 4 "Deploy the MCPRemoteProxy" section needs a combined auth example showing authServerRef + externalAuthConfigRef
• docs/toolhive/concepts/embedded-auth-server.mdx - Concept page; "MCPServer vs. VirtualMCPServer" section and intro need authServerRef mention
• docs/toolhive/concepts/backend-auth.mdx - Backend auth concepts; "Built-in AWS STS support" section needs combined pattern reference
• docs/toolhive/reference/crd-spec.md - Auto-generated CRD reference; will be updated by task crdref-gen in the toolhive repo (no manual edits needed here)

Component Interfaces

The new authServerRef field uses Kubernetes TypedLocalObjectReference:

# New preferred syntax for embedded auth server on MCPServer
spec:
  authServerRef:
    kind: MCPExternalAuthConfig
    name: my-embedded-auth-server

# Combined auth on MCPRemoteProxy (primary use case)
spec:
  authServerRef:
    kind: MCPExternalAuthConfig
    name: my-embedded-auth-server
  externalAuthConfigRef:
    name: my-aws-sts-config

Testing Strategy

Manual Tests

• Run npm run build to verify all pages build without errors
• Run npm run start and visually inspect each updated page
• Verify all internal cross-links resolve correctly
• Verify YAML examples are syntactically valid and use correct field names

Edge Cases

• Ensure backward compatibility notes are clear: users on older operator versions should not be confused by authServerRef references

Out of Scope

• Changes to the auto-generated CRD reference (docs/toolhive/reference/crd-spec.md) -- this is regenerated from the toolhive repo
• Documentation for VirtualMCPServer authServerRef (vMCP uses inline authServerConfig, not authServerRef)
• Deprecation notices for externalAuthConfigRef with type: embeddedAuthServer -- the RFC explicitly does not deprecate the old path

References

• RFC-0050: Dedicated Auth Server Reference for MCP Resources
• Related epic: stacklok/stacklok-epics#256