Update docs for ToolHive v0.19.0

[reyortiz3]

Summary

• Updates documentation to reflect breaking changes and new features in ToolHive v0.19.0
• All changes verified against source code at the v0.19.0 tag

Changes

Breaking changes documented

• remoteUrl field rename (MCPRemoteProxy, MCPServerEntry): Updated all YAML examples in remote-mcp-proxy.mdx from remoteURL: to remoteUrl: (10 occurrences)
• externalAuthConfigRef enum value: Updated all vMCP authentication examples from deprecated type: external_auth_config_ref to type: externalAuthConfigRef
• --clients flag: Updated skills-management.mdx to reflect that thv skill install now uses --clients (plural, comma-separated) instead of --client

New features documented

• Cursor skills support: Updated client-compatibility.mdx — Cursor skills column ❌ → ✅
• Multi-client skill install: Added "Install to multiple clients at once" section documenting --clients claude-code,cursor and --clients all with atomic rollback behavior
• MCPRemoteProxy telemetry config ref: Updated remote-mcp-proxy.mdx and telemetry-and-metrics.mdx to show telemetryConfigRef on MCPRemoteProxy (inline telemetry: marked deprecated)
• Webhook CLI configuration: New guide guides-cli/webhooks.mdx covering --webhook-config flag, YAML/JSON config format, failure policies, and request/response formats; added to sidebar under Advanced workflows

Needs follow-up (auto-generated files)

• docs/toolhive/reference/cli/thv_skill_install.md — still shows old --client string flag; needs regeneration from CLI source
• docs/toolhive/reference/crd-spec.md — needs regeneration for telemetryConfigRef on MCPRemoteProxy, remoteUrl/externalUrl JSON tag renames, and enforceServers removal from MCPRegistry

Test plan

• npm run prettier — passes (all files)
• npm run eslint — passes (all changed MDX/TS files)
• Site build — blocked by pre-existing mcp-metadata-plugin fetch failure unrelated to these changes

🤖 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 14, 2026 2:48pm

[Copilot]

Pull request overview

Updates ToolHive documentation for v0.19.0, covering new features (webhook authorization, multi-client skill install, shared telemetry refs) and documenting breaking field/flag renames (e.g., remoteUrl, externalAuthConfigRef, --clients).

Changes:

• Add a new CLI guide documenting webhook-based authorization middleware and update the sidebar to include it.
• Update Kubernetes operator docs to use remoteUrl and to prefer telemetryConfigRef (with deprecation notes for inline telemetry).
• Update CLI docs for multi-client skill installation (--clients) and refresh client compatibility (Cursor skills support).

Reviewed changes

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

Show a summary per file

File	Description
sidebars.ts	Adds the new webhooks guide to the “Advanced workflows” sidebar section.
docs/toolhive/reference/client-compatibility.mdx	Updates Cursor to show skills support as supported.
docs/toolhive/guides-vmcp/authentication.mdx	Updates vMCP auth examples to use externalAuthConfigRef enum value.
docs/toolhive/guides-k8s/telemetry-and-metrics.mdx	Documents telemetryConfigRef usage for both MCPServer and MCPRemoteProxy and expands deprecation notice.
docs/toolhive/guides-k8s/remote-mcp-proxy.mdx	Renames remoteURL → remoteUrl across examples and updates telemetry guidance to prefer shared configs.
docs/toolhive/guides-cli/webhooks.mdx	New guide describing webhook authorization configuration, usage, and request/response formats.
docs/toolhive/guides-cli/skills-management.mdx	Updates skill install docs to use --clients and documents installing to multiple clients (incl. Cursor paths).

[reyortiz3]

@claude can you review if the comments were addressed?

[claude]

Claude finished @reyortiz3's task in 55s —— View job

---

Review: were the Copilot comments addressed?

• Read docs/toolhive/guides-cli/webhooks.mdx
• Read docs/toolhive/guides-k8s/remote-mcp-proxy.mdx
• Post findings

---

Comment 1 — webhooks.mdx: HTTP support incorrectly tied to insecure_skip_verify

Status: ❌ Not addressed

The url field description at line 65 still reads:

Plain HTTP is also accepted when tls_config.insecure_skip_verify: true (for development or in-cluster endpoints).

And the insecure_skip_verify row in the TLS table (line 78) says:

Use only for development or in-cluster HTTP endpoints.

The Copilot comment is correct: insecure_skip_verify disables TLS certificate verification for HTTPS connections — it has no effect on plain HTTP URLs. These two things are independent. The docs should be updated to separate them. A suggested fix:

• url: "HTTPS endpoint to call. For local or in-cluster development you may use a plain http:// URL if your webhook service doesn't terminate TLS." (or simply require HTTPS if the API schema does)
• insecure_skip_verify: "Skip TLS certificate verification for HTTPS endpoints. Use only in development or trusted in-cluster environments."

Fix this →

---

Comment 2 — remote-mcp-proxy.mdx: missing insecure: true in inline telemetry example

Status: ✅ Addressed

The inline telemetry example (around line 733–734) now includes insecure: true:

endpoint: otel-collector.monitoring.svc.cluster.local:4318
insecure: true
serviceName: analytics-mcp-proxy

This matches the pattern used in telemetry-and-metrics.mdx and correctly signals that the in-cluster OTLP connection should not expect a TLS certificate.

---

Summary: One of the two review comments was addressed; the webhooks.mdx url/insecure_skip_verify issue remains. The fix is a small, contained change to two table cells in that file.

[reyortiz3]

@claude can you review again if all the changes were fixed?

[claude]

Claude finished @reyortiz3's task in 1m 5s —— View job

---

Re-review: are all changes fixed?

• Read docs/toolhive/guides-cli/webhooks.mdx
• Read docs/toolhive/guides-k8s/remote-mcp-proxy.mdx
• Post findings

---

Both original Copilot review comments have now been addressed.

Comment 1 — webhooks.mdx: HTTP support and insecure_skip_verify

Status: ✅ Addressed (via commit 28fb841)

The fix takes a different approach than originally suggested, but it's a valid resolution. Rather than decoupling HTTP support from insecure_skip_verify, the docs now explicitly document them as coupled behaviors:

• url field (line 65): "HTTPS endpoint to call. Plain HTTP is accepted for in-cluster or development use (see insecure_skip_verify below)."
• insecure_skip_verify (line 78): "Disable TLS certificate verification for HTTPS connections, and also allow plain HTTP endpoint URLs. Use only in development or trusted in-cluster environments."

This resolves the ambiguity — if the ToolHive v0.19.0 implementation actually couples these two behaviors (plain HTTP requires insecure_skip_verify: true), then the documentation is now accurate and complete.

Comment 2 — remote-mcp-proxy.mdx: missing insecure: true

Status: ✅ Still addressed

The inline telemetry example (lines 733–734) still correctly includes insecure: true:

endpoint: otel-collector.monitoring.svc.cluster.local:4318
insecure: true
serviceName: analytics-mcp-proxy

---

Summary: Both review comments are resolved. The PR looks good from a review-comment-coverage standpoint. The remaining follow-up items (auto-generated thv_skill_install.md and crd-spec.md) are noted in the PR description as needing regeneration from source and are out of scope for manual editing.

[danbarr]

Editorial review

Scope: 7 files changed (1 new, 6 modified). Breaking changes (remoteUrl, externalAuthConfigRef, --clients), new features (webhook authorization, multi-client skills, Cursor skills, telemetry config ref on MCPRemoteProxy).

Prior review status: Both Copilot review comments are resolved.

---

Primary issues

1. Missing mutating webhook response format (webhooks.mdx)

The page describes both mutating and validating webhooks, but only documents the response format for validating webhooks. Readers implementing a mutating webhook need to know what the response looks like - does it return the mutated mcp_request? Does it use the same version/uid envelope? A "Mutating webhook response format" section (or at least a note) would fill this gap.

2. Prometheus metrics list sits under the deprecated section (remote-mcp-proxy.mdx)

The metrics list (toolhive_mcp_requests_total, etc.) was moved below the deprecated inline telemetry example (~line 740). This placement could imply the metrics themselves are deprecated, when they apply regardless of how telemetry is configured. Consider moving the list above both telemetry subsections, or into its own sibling subsection under "Telemetry and observability."

---

Secondary issues

Issue	Location	Recommendation
"Target a specific client" says --clients flag "with a comma-separated list" but the example shows one client	skills-management.mdx ~line 116	Change to just "use the --clients flag:" - the comma-separated detail is already in the "Install to multiple clients" section below
Em dashes used throughout	webhooks.mdx lines 12, 30, 32, 138, 139	Rephrase naturally. E.g., line 12: "which decides whether to allow or deny the call, and optionally modify it." Line 30: "Mutating webhooks can transform the request..." Line 138: "fail denies the MCP tool call."

---

What looks good

• remoteURL → remoteUrl rename consistent across all 12 occurrences
• externalAuthConfigRef enum value updated in all 4 places in authentication.mdx
• Telemetry section restructure in remote-mcp-proxy.mdx is well done - promotes the preferred telemetryConfigRef approach and clearly deprecates inline config
• New MCPRemoteProxy telemetry example in telemetry-and-metrics.mdx with matching deprecation notice update
• Multi-client skill install section is clean with good progressive disclosure
• Troubleshooting update adding Cursor paths is well-formatted
• Sidebar placement of webhooks guide is sensible

[reyortiz3]

@claude can you review again if all the comments have been addressed?

[claude]

Claude finished @reyortiz3's task in 1m 8s —— View job

---

Re-review: are all comments addressed?

• Read docs/toolhive/guides-cli/webhooks.mdx
• Read docs/toolhive/guides-k8s/remote-mcp-proxy.mdx
• Read docs/toolhive/guides-cli/skills-management.mdx
• Post findings

---

All comments — both Copilot review comments and danbarr's editorial review — have been addressed.

Copilot review comments

Both previously confirmed resolved. Still resolved.

danbarr's editorial review — Primary issues

1. Missing mutating webhook response format (webhooks.mdx)

Status: ✅ Addressed

A full "Mutating webhook response format" section was added (lines 198–233). It documents:

• Pass-through with no patch (allow + no patch_type)
• Request modification using JSON Patch operations with /mcp_request/ path prefix
• Deny behavior ("allowed": false)

2. Prometheus metrics list under deprecated section (remote-mcp-proxy.mdx)

Status: ✅ Addressed

The metrics list (toolhive_mcp_requests_total, etc.) is now in its own "### Available Prometheus metrics" subsection (lines 711–719), positioned above the "### Inline telemetry configuration (deprecated)" section (line 720+). The metrics no longer appear to be deprecated.

danbarr's editorial review — Secondary issues

3. "Target a specific client" mention of comma-separated list (skills-management.mdx ~line 116)

Status: ✅ Addressed

The section now reads simply "use the --clients flag:" with a single-client example. The comma-separated detail is correctly deferred to the "Install to multiple clients at once" section immediately below.

4. Em dashes in webhooks.mdx (original lines 12, 30, 32, 138, 139)

Status: ✅ Addressed

All em dashes have been rephrased naturally:

• Line 11–12: "...which decides whether to allow or deny the call, and optionally modify it." (matches danbarr's suggestion exactly)
• Line 29–30: "**Mutating webhooks** can transform the request before it reaches the MCP server..." (no em dash)
• Lines 138–142: "\fail` denies the MCP tool call."` followed by plain prose (no em dash)

---

Summary: All editorial and Copilot review comments are fully resolved. The PR is ready for final approval.