Update docs for ToolHive v0.12.3–v0.13.0

[rdimitrov]

Summary

Catch up documentation with user-facing features shipped in ToolHive v0.12.3 through v0.13.0. Changes were verified against source code at each release tag.

• Multi-upstream auth: Update outdated "single upstream provider" statements in backend-auth concept page and auth-k8s guide to reflect VirtualMCPServer multi-upstream support
• Horizontal scaling: Rewrite scaling guide with new replicas and backendReplicas CRD fields, session storage config, and stdio transport limitations
• forEach steps: Add forEach iteration section to composite tools guide with fields table and example workflow
• Tool annotation overrides: Add annotation overrides section (title, readOnlyHint, destructiveHint, etc.) to tool aggregation guide
• Skills CLI install: Replace "planned for a future release" with working thv skill install documentation (registry and git sources)
• Cross-references: Add scaling link from run-mcp-k8s, Redis cross-reference to scaling guide

Releases covered

Release	Date
v0.12.3	2026-03-19
v0.12.4	2026-03-19
v0.12.5	2026-03-24
v0.13.0	2026-03-26

Excluded (verified as not needing docs)

• Webhook middleware (Phase 1-2 foundation, not user-configurable)
• ResourceLink content type (transparent protocol fix)
• Graceful shutdown (transparent infrastructure)
• --publish flag (not present in CLI at v0.13.0)
• Bug fixes (elicitation templates, runtime config merge)

Test plan

• npm run build passes with no broken links or MDX errors
• Verify YAML examples match CRD field names in auto-generated reference
• Review rendering of new forEach, annotation overrides, and scaling sections
• Confirm cross-references resolve correctly between guides

🤖 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 7, 2026 8:40am

[Copilot]

Pull request overview

Updates the ToolHive documentation to reflect user-facing features shipped in v0.12.3–v0.13.0, aligning guides and concept pages with current CRD/CLI capabilities (scaling, auth, composite workflows, and skills install).

Changes:

• Document tool annotation overrides for aggregated tools (vMCP).
• Rewrite scaling guidance to cover new replicas / backendReplicas fields and session storage requirements.
• Add docs for forEach composite-tool steps and for installing skills via thv skill install (registry + git sources), plus cross-references between guides.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
docs/toolhive/guides-vmcp/tool-aggregation.mdx	Adds annotation override documentation and example configuration.
docs/toolhive/guides-vmcp/scaling-and-performance.mdx	Updates horizontal scaling guidance and adds session storage + MCPServer scaling sections.
docs/toolhive/guides-vmcp/composite-tools.mdx	Documents forEach iteration steps and expands template context table.
docs/toolhive/guides-registry/skills.mdx	Adds CLI-based skill installation instructions and flags table.
docs/toolhive/guides-k8s/run-mcp-k8s.mdx	Adds cross-link to scaling guidance for MCPServer replicas.
docs/toolhive/guides-k8s/redis-session-storage.mdx	Adds scaling-related context and links session storage to horizontal scaling.
docs/toolhive/guides-k8s/auth-k8s.mdx	Updates upstream provider note to reflect multi-upstream support in VirtualMCPServer.
docs/toolhive/concepts/skills.mdx	Updates current status to reflect CLI install support and links to guide.
docs/toolhive/concepts/backend-auth.mdx	Replaces “single upstream” language with multi-upstream (vMCP) + clarifies MCPServer limitations.

[danbarr]

As noted on Copilot's review comment, the new content about scaling MCPServer resources is out of place in the vMCP scaling/performance guide.

It should live with the other MCPServer docs in the main operator section - either as a new guide if the amount of content warrants it, or in the existing "Run MCP servers in Kubernetes" guide.

[rdimitrov]

@danbarr - I think I addressed the feedback so it should be ready for another round 👍

[danbarr]

@danbarr - I think I addressed the feedback so it should be ready for another round 👍

The updated locations of the scaling info make sense to me now. I'll clear my "changes requested" review and leave it to the platform team to do their technical review.

Structural feedback addressed

[yrobla]

Scalability review comment — session storage warning behavior

[yrobla]

Remaining scalability review comments

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.

[danbarr]

Nice work bringing the docs up to date with v0.12.3-v0.13.0. The new scaling, forEach, and annotation overrides sections are well-structured with good examples, and the cross-references form a clear navigation path.

The only blocking issue is the malformed admonition noted inline.

Non-blocking nits

Em dashes - A few lines introduced by this PR use em dashes (— or —). Per our style, these should be hyphens with spaces (-). Spotted in:

• backend-auth.mdx: "chained authentication—where"
• run-mcp-k8s.mdx: "same pod — subject to the same NAT"
• scaling-and-performance.mdx: "same IP — routing every client"
• tool-aggregation.mdx: "optional—only set"
• composite-tools.mdx: "originate from a single pod…" area

Title case - scaling-and-performance.mdx has title: Scaling and Performance in front matter. Should be sentence case: Scaling and performance. (Pre-existing, but since the file is already being touched.)

[danbarr]

Formatting issue, this note won't render right

Suggested change

	:::note The `SessionStorageWarning` condition fires only when
	`spec.replicas > 1`. Scaling only the backend (`backendReplicas > 1`) does not
	trigger a warning, but backend client-IP affinity is still unreliable behind NAT
	or shared egress IPs. :::
	:::note
	The `SessionStorageWarning` condition fires only when `spec.replicas > 1`.
	Scaling only the backend (`backendReplicas > 1`) does not trigger a warning, but
	backend client-IP affinity is still unreliable behind NAT or shared egress IPs.
	:::