Update MCP Optimizer tutorial to use K8s/vMCP path

[aponcedeleonch]

Description

Replace the deprecated standalone optimizer tutorial with a
Kubernetes-first walkthrough using VirtualMCPServer and EmbeddingServer
CRDs. The tutorial now walks readers through deploying the optimizer
on Kubernetes via vMCP, which is the recommended path going forward.

Key changes:

• Tutorial rewritten end-to-end for the K8s/vMCP path (MCPGroup,
  EmbeddingServer, VirtualMCPServer)
• Includes the "Moving to vMCP" note from main, adapted to reflect
  the new tutorial scope
• Updated cross-references in the vMCP optimizer guide
• Added clean up section
• Added production exposure guidance (Ingress/Gateway/LoadBalancer)
  with link to configuration docs
• Old standalone/CLI content preserved via link to the UI guide as
  a legacy note

Type of change

• Documentation update

Submitter checklist

Content and formatting

• I have reviewed the content for technical accuracy
• I have reviewed the content for spelling, grammar, and style

🤖 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 16, 2026 1:19pm

[Copilot]

Pull request overview

Updates the MCP Optimizer tutorial to follow the Kubernetes-first deployment path using vMCP (VirtualMCPServer + EmbeddingServer), aligning the docs with the recommended approach going forward.

Changes:

• Rewrites the MCP Optimizer tutorial to deploy on Kubernetes via MCPGroup, EmbeddingServer, and VirtualMCPServer (optimizer enabled).
• Adds production exposure guidance (Ingress/Gateway/LoadBalancer), cleanup steps, and a legacy pointer to the standalone/UI guide.
• Updates the vMCP optimizer guide to point readers to the new end-to-end tutorial.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
docs/toolhive/tutorials/mcp-optimizer.mdx	Full rewrite of the tutorial to use the K8s/vMCP optimizer workflow, with port-forwarding, validation, cleanup, and legacy note.
docs/toolhive/guides-vmcp/optimizer.mdx	Adjusts references to position the tutorial as the end-to-end walkthrough and keeps this doc focused on configuration details.

[danbarr]

Nice rewrite - the K8s/vMCP path is a big improvement over the old standalone tutorial. A few minor items beyond the inline comments:

Missing local workload cleanup - Step 4 runs thv run http://localhost:4483/mcp --name optimizer-vmcp to register a local workload, but the Clean up section only covers kubectl delete commands. Add a step to remove the local workload (e.g., thv rm optimizer-vmcp) before the kubectl deletions.

"What you'll learn" last bullet - "How to verify the optimizer reduces the visible toolset to find_tool and call_tool" reads more as an expected outcome than a learning objective. Consider folding verification into the "connect your AI client" bullet, or rephrasing.

Legacy note placement - The :::note[Legacy: standalone MCP Optimizer] admonition between "Clean up" and "Next steps" breaks the flow slightly. It would fit more naturally as a bullet in "Related information" (where the UI guide is already linked).

"Next steps" lead-in - "Now that you've set up the MCP Optimizer, consider exploring these next steps:" can be trimmed - the heading already tells the reader what this section is.

[aponcedeleonch]

Thanks for the thorough review, Dan! All feedback has been addressed in 51fe27e:

• Missing local workload cleanup - Added thv rm optimizer-vmcp before the kubectl deletions in Clean up.
• "What you'll learn" last bullet - Folded the verification point into the "connect your AI client" bullet.
• Legacy note placement - Removed the admonition between Clean up and Next steps. The existing bullet in Related information now carries the legacy context.
• "Next steps" lead-in - Trimmed the redundant sentence.
• groupRef syntax - Updated all three to the new object form.
• Redundant highlight metastring - Removed.
• ARM64 anchor + workaround - Fixed the anchor to #embeddingserver-resource. Kept the workaround but documented the missing Docker Desktop containerd prerequisite that was causing the kind load failures (see my reply on that thread for details).

[danbarr]

Missed one issue in the vmcp resource

[aponcedeleonch]

Pushed another round addressing the remaining feedback:

• ARM64: Replaced the emulation workaround with the now-published cpu-arm64-latest image (both the guide and the tutorial)
• groupRef at spec level: Moved groupRef from spec.config to spec in all VirtualMCPServer examples (tutorial + guide)
• "What you'll learn" bullet: Shortened the last bullet to drop the outcome-style verification language
• Token savings note: Added a note after the token savings prompt explaining minimal savings are expected with only two backends

Should be ready for another look!

[danbarr]

🚀