Part 1: Update docs for ToolHive v0.17.0

[ChrisJBurns]

Summary

Updates documentation for the ToolHive v0.17.0 release.

Breaking change updates

• CRD phase Running → Ready: Updated MCPServer and EmbeddingServer phase references in quickstarts, guides, and integration pages
• MCPRegistry v2 config format: Migrated all examples from flat registries[] to v2 sources[]/registries[] within configYAML (recommended path)
• PVC source removed: Removed PVC source section and references
• MCPRegistry status simplified: Removed Syncing phase, syncStatus/apiStatus references; added kubectl wait --for=condition=Ready example
• Auto-injection removed: Removed note about automatic Kubernetes registry creation

New feature documentation

• MCPServerEntry: Zero-infrastructure catalog entries documented in K8s intro and vMCP configuration pages, with comparison table vs MCPRemoteProxy
• caBundleRef for OTLP: Custom CA certificate support for OTLP endpoints added to telemetry guide
• authServerRef: Dedicated auth server field documented in auth guide, enabling combined embedded auth + outgoing token exchange
• Registry v2 config: Standalone registry server config updated to v2 sources[]/registries[] format

Files changed (10)

• guides-k8s/quickstart.mdx — Phase Running → Ready
• guides-vmcp/quickstart.mdx — Phase Running → Ready
• integrations/okta.mdx — Phase Running → Ready
• guides-vmcp/optimizer.mdx — EmbeddingServer phase Running → Ready
• guides-registry/deploy-operator.mdx — Major: v2 config format, configYAML, remove PVC, status updates
• guides-registry/configuration.mdx — v2 config format for standalone server
• guides-k8s/intro.mdx — Add MCPServerEntry to resource table
• guides-vmcp/configuration.mdx — Add MCPServerEntry backend type with examples
• guides-k8s/telemetry-and-metrics.mdx — Add caBundleRef for OTLP
• guides-k8s/auth-k8s.mdx — Add authServerRef for combined auth

Not included (separate action needed)

• reference/crd-spec.md — Auto-generated file; needs regeneration from v0.17.0 tag

Test plan

• Prettier formatting passes on all changed files
• ESLint passes on all MDX files
• All YAML examples verified against v0.17.0 source code at tag
• Phase value changes scoped correctly (K8s CRD phases only, not pod status or CLI/UI status)
• Full site build (blocked by pre-existing CLI conflict in local env)

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs-website	Ready	Preview, Comment	Apr 9, 2026 10:25pm

[Copilot]

Pull request overview

Updates ToolHive documentation to align with the v0.17.0 release, including breaking-change terminology/config updates and newly added features.

Changes:

• Updates CRD phase references from Running to Ready across quickstarts/integration docs.
• Migrates registry configuration examples to the v2 sources[] + registries[] format (via configYAML) and updates registry operational guidance (PVC removal, status/phase changes).
• Documents new/updated Kubernetes features: MCPServerEntry, OTLP caBundleRef, and authServerRef.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
docs/toolhive/guides-k8s/quickstart.mdx	Updates example output/status expectations to Ready.
docs/toolhive/guides-vmcp/quickstart.mdx	Updates vMCP quickstart to expect Ready status.
docs/toolhive/integrations/okta.mdx	Updates MCPServer status wording/output to Ready.
docs/toolhive/guides-vmcp/optimizer.mdx	Updates EmbeddingServer phase guidance to Ready.
docs/toolhive/guides-registry/deploy-operator.mdx	Updates operator-based registry deployment docs to v2 config format and revised phases/troubleshooting.
docs/toolhive/guides-registry/configuration.mdx	Updates standalone registry server configuration docs to v2 sources/registry-views model.
docs/toolhive/guides-k8s/intro.mdx	Introduces MCPServerEntry into the resource selection overview and shared config references.
docs/toolhive/guides-vmcp/configuration.mdx	Adds MCPServerEntry backend type docs and comparisons with MCPRemoteProxy.
docs/toolhive/guides-k8s/telemetry-and-metrics.mdx	Documents OTLP custom CA support via caBundleRef.
docs/toolhive/guides-k8s/auth-k8s.mdx	Documents authServerRef for embedded auth + outgoing token exchange.

[danbarr]

Editorial review

Well-structured PR that systematically covers the v0.17.0 breaking changes and new features. The scope is well-defined, changes are internally consistent, and the PR description is thorough. A few minor fixes and two issues to track below.

Minor fixes

1. Em dash in telemetry-and-metrics.mdx (style)
The new caBundleRef note uses an em dash: "caBundleRef cannot be used when insecure is set to true — they are mutually exclusive." Per project style, use a hyphen with spaces ( - ) instead.

2. Awkward phrasing in auth-k8s.mdx (clarity)
"Both authServerRef and externalAuthConfigRef cannot point to an embeddedAuthServer type simultaneously" - "Both X and Y cannot" is ambiguous. Suggest: "authServerRef and externalAuthConfigRef cannot both reference an embeddedAuthServer type."

3. MCPGroup intro omits MCPServerEntry in guides-vmcp/configuration.mdx (consistency)
The MCPGroup description still says "groups related MCPServer and MCPRemoteProxy resources together" but the PR adds MCPServerEntry as a third backend type. This paragraph should mention MCPServerEntry to match the "three types" wording a few lines below.

4. Comparison table parallel structure in guides-vmcp/configuration.mdx (style)
The "Use case" row mixes noun phrases and clause fragments - MCPServerEntry gets "Lightweight catalog entries for well-known remote servers" but MCPRemoteProxy gets "When you need request transformation..." Suggest aligning to noun phrases, e.g. "Proxied connections requiring request transformation, caching, or the full proxy middleware chain."

Issues to track

These don't need to block this PR, but they're real gaps that should be addressed soon.

5. MCPServerEntry needs its own Operator guide page
MCPServerEntry is a first-class CRD like MCPServer (run-mcp-k8s.mdx) and MCPRemoteProxy (remote-mcp-proxy.mdx), but it currently only exists as a subsection of the vMCP configuration page. This creates two problems:

• A reader in the K8s Operator section has no obvious path to MCPServerEntry docs. The intro.mdx resource table mentions it but doesn't link anywhere.
• The optional config details (externalAuthConfigRef, caBundleRef, headerForward) are MCPServerEntry CRD features, not vMCP configuration - they're in the wrong home.

A dedicated page under guides-k8s/ would follow the established pattern. The vMCP configuration page could then slim down to a brief mention with a cross-link. Also worth checking whether backend-discovery.mdx needs a corresponding update since it's referenced from the "Create a VirtualMCPServer" section but may only describe MCPServer and MCPRemoteProxy.

Tracking issue: #688

6. The authServerRef tip in auth-k8s.mdx should be a proper subsection
The new tip is ~25 lines with a full YAML example, and it's the only documentation for authServerRef outside the auto-generated CRD spec. That makes it primary feature documentation, not a helpful aside. A dedicated H3 subsection (e.g. "Combine embedded auth with outgoing token exchange") would make it discoverable via the ToC and signal to readers that this is a real configuration path.

Tracking issue: #689

Positive callouts

• Fixes the pre-existing "stafrt" typo in guides-vmcp/configuration.mdx
• Fixes "the use are" to "the user are" in deploy-operator.mdx
• The "Configure registry sources" heading change (from "Configuring source Registries") correctly uses imperative mood and sentence case
• Mermaid diagram correctly updated to reflect source type changes