From 9fbf3a80676971a2a4ebfd45ed15e9b3d38ecd1e Mon Sep 17 00:00:00 2001 From: Reynier Ortiz Vega Date: Thu, 9 Apr 2026 19:13:23 -0400 Subject: [PATCH 1/3] Update docs for ToolHive v0.16.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add thv skill builds and thv skill builds remove guide content to skills-management.mdx with example output and CLI reference link - Fix MCPOIDCConfig status column name READY → VALID in auth-k8s.mdx (breaking change in v0.16.0: condition type renamed for consistency) - Document MCPServerEntry CRD in K8s intro with note that controller ships in a future release - Clarify VirtualMCPServer Redis session storage enables cross-pod restore and survives pod restarts Co-Authored-By: Claude Sonnet 4.6 --- .../toolhive/guides-cli/skills-management.mdx | 45 +++++++++++++++++++ docs/toolhive/guides-k8s/auth-k8s.mdx | 2 +- docs/toolhive/guides-k8s/intro.mdx | 30 +++++++++---- .../guides-vmcp/scaling-and-performance.mdx | 8 +++- 4 files changed, 73 insertions(+), 12 deletions(-) diff --git a/docs/toolhive/guides-cli/skills-management.mdx b/docs/toolhive/guides-cli/skills-management.mdx index 0edc0bf1..c0759f83 100644 --- a/docs/toolhive/guides-cli/skills-management.mdx +++ b/docs/toolhive/guides-cli/skills-management.mdx @@ -301,6 +301,50 @@ authenticated before pushing. ::: +## List and remove locally-built skill artifacts + +After building skills locally, you can view and manage the artifacts stored in +your local OCI store. + +### List locally-built artifacts + +```bash +thv skill builds +``` + +This lists all OCI skill artifacts built locally with `thv skill build`. The +output shows the tag, digest, name, and version of each artifact: + +```text +TAG DIGEST NAME VERSION +ghcr.io/my-org/skills/my-skill:v1.0.0 sha256:a1b2c3d4... my-skill 1.0.0 +my-skill:latest sha256:e5f6a7b8... my-skill +``` + +For JSON output: + +```bash +thv skill builds --format json +``` + +### Remove a locally-built artifact + +To remove an artifact from the local OCI store: + +```bash +thv skill builds remove +``` + +For example: + +```bash +thv skill builds remove my-skill:latest +``` + +This removes the artifact and cleans up its blobs from the local store. If +multiple tags share the same digest, the blobs are retained until all tags +pointing to that digest are removed. + ## Next steps - [Configure your AI client](./client-configuration.mdx) to register clients @@ -312,6 +356,7 @@ authenticated before pushing. - [Understanding skills](../concepts/skills.mdx) for a conceptual overview - [`thv skill` command reference](../reference/cli/thv_skill.md) +- [`thv skill builds` command reference](../reference/cli/thv_skill_builds.md) - [`thv serve` command reference](../reference/cli/thv_serve.md) - [Agent Skills specification](https://agentskills.io/specification) diff --git a/docs/toolhive/guides-k8s/auth-k8s.mdx b/docs/toolhive/guides-k8s/auth-k8s.mdx index fc4f71ac..d88567fb 100644 --- a/docs/toolhive/guides-k8s/auth-k8s.mdx +++ b/docs/toolhive/guides-k8s/auth-k8s.mdx @@ -187,7 +187,7 @@ Check the MCPOIDCConfig status: kubectl get mcpoidc -n toolhive-system ``` -The `REFERENCES` column shows which workloads use this config. The `READY` +The `REFERENCES` column shows which workloads use this config. The `VALID` column confirms validation passed. ### Benefits of MCPOIDCConfig diff --git a/docs/toolhive/guides-k8s/intro.mdx b/docs/toolhive/guides-k8s/intro.mdx index f5b5b15d..f0a86c18 100644 --- a/docs/toolhive/guides-k8s/intro.mdx +++ b/docs/toolhive/guides-k8s/intro.mdx @@ -21,9 +21,10 @@ quickly using a local kind cluster. Try it out and The operator introduces new Custom Resource Definitions (CRDs) into your Kubernetes cluster. The primary CRDs for MCP server workloads are `MCPServer`, which represents a single MCP server running in Kubernetes, `MCPRemoteProxy`, -which represents an MCP server running outside the cluster that is proxied by -ToolHive, and `VirtualMCPServer`, which represents a virtual MCP server gateway -that aggregates multiple backend MCP servers. +which represents an MCP server hosted outside the cluster that ToolHive proxies, +`VirtualMCPServer`, which aggregates multiple backend MCP servers behind a +single endpoint, and `MCPServerEntry`, which declares a remote MCP server as a +catalog entry without creating any pods or infrastructure. All ToolHive CRDs are registered under the `toolhive` category, so you can list every ToolHive resource in your cluster with a single command: @@ -67,19 +68,30 @@ or Gateway. To learn how to expose your MCP servers and connect clients, see ## Which resource type should I use? -The operator introduces three resource types for MCP workloads. Choose based on +The operator introduces resource types for MCP workloads. Choose based on where your MCP server runs and how many servers you need to manage: -| Resource | Use when | -| -------------------- | ----------------------------------------------------------------------------------------------------------------- | -| **MCPServer** | Running an MCP server as a container inside your cluster | -| **MCPRemoteProxy** | Connecting to an MCP server hosted outside your cluster (SaaS tools, external APIs, remote endpoints) | -| **VirtualMCPServer** | Aggregating multiple MCPServer and/or MCPRemoteProxy resources behind a single endpoint for a team or application | +| Resource | Use when | +| ----------------------- | ----------------------------------------------------------------------------------------------------------------- | +| **MCPServer** | Running an MCP server as a container inside your cluster | +| **MCPRemoteProxy** | Connecting to an MCP server hosted outside your cluster (SaaS tools, external APIs, remote endpoints) | +| **VirtualMCPServer** | Aggregating multiple MCPServer and/or MCPRemoteProxy resources behind a single endpoint for a team or application | +| **MCPServerEntry** | Declaring a remote MCP server endpoint as a catalog entry without spawning proxy pods (no infrastructure created) | Most teams start with `MCPServer` for container-based servers, add `MCPRemoteProxy` for external SaaS tools, and graduate to `VirtualMCPServer` when managing five or more servers or needing centralized authentication. +:::note + +`MCPServerEntry` is a new resource type added in v0.16.0. The CRD is available +and you can create resources, but the reconciliation controller ships in a +future release. Creating `MCPServerEntry` resources before the controller is +available has no effect — the operator will not reconcile them until the +controller ships. + +::: + The operator also provides shared configuration CRDs that you reference from workload resources: diff --git a/docs/toolhive/guides-vmcp/scaling-and-performance.mdx b/docs/toolhive/guides-vmcp/scaling-and-performance.mdx index c3a7b7c0..9f456b46 100644 --- a/docs/toolhive/guides-vmcp/scaling-and-performance.mdx +++ b/docs/toolhive/guides-vmcp/scaling-and-performance.mdx @@ -67,8 +67,12 @@ kubectl autoscale deployment vmcp- -n \ ### Session storage for multi-replica deployments When running multiple replicas, configure Redis session storage so that sessions -are shared across pods. Without session storage, a request routed to a different -replica than the one that established the session will fail. +are shared across pods and survive pod restarts. Without session storage, a +request routed to a different replica than the one that established the session +will fail, and sessions are lost when pods restart. + +With Redis session storage configured, vMCP stores session state in Redis so +that any replica can resume a session, even after a pod restart or failover. ```yaml title="VirtualMCPServer resource" spec: From 8b522d9cb82b307ced9a65b63e6861d5721b5dad Mon Sep 17 00:00:00 2001 From: Reynier Ortiz Vega Date: Fri, 10 Apr 2026 11:59:54 -0400 Subject: [PATCH 2/3] Address PR review feedback Co-Authored-By: Claude Sonnet 4.6 --- docs/toolhive/guides-cli/skills-management.mdx | 3 +-- docs/toolhive/guides-k8s/intro.mdx | 14 +------------- .../guides-vmcp/scaling-and-performance.mdx | 3 --- 3 files changed, 2 insertions(+), 18 deletions(-) diff --git a/docs/toolhive/guides-cli/skills-management.mdx b/docs/toolhive/guides-cli/skills-management.mdx index c0759f83..47438467 100644 --- a/docs/toolhive/guides-cli/skills-management.mdx +++ b/docs/toolhive/guides-cli/skills-management.mdx @@ -317,7 +317,7 @@ output shows the tag, digest, name, and version of each artifact: ```text TAG DIGEST NAME VERSION -ghcr.io/my-org/skills/my-skill:v1.0.0 sha256:a1b2c3d4... my-skill 1.0.0 +ghcr.io/my-org/skills/my-skill:v1.0.0 sha256:a1b2c3d4... my-skill 1.0.0 my-skill:latest sha256:e5f6a7b8... my-skill ``` @@ -356,7 +356,6 @@ pointing to that digest are removed. - [Understanding skills](../concepts/skills.mdx) for a conceptual overview - [`thv skill` command reference](../reference/cli/thv_skill.md) -- [`thv skill builds` command reference](../reference/cli/thv_skill_builds.md) - [`thv serve` command reference](../reference/cli/thv_serve.md) - [Agent Skills specification](https://agentskills.io/specification) diff --git a/docs/toolhive/guides-k8s/intro.mdx b/docs/toolhive/guides-k8s/intro.mdx index f0a86c18..91a5545a 100644 --- a/docs/toolhive/guides-k8s/intro.mdx +++ b/docs/toolhive/guides-k8s/intro.mdx @@ -23,8 +23,7 @@ Kubernetes cluster. The primary CRDs for MCP server workloads are `MCPServer`, which represents a single MCP server running in Kubernetes, `MCPRemoteProxy`, which represents an MCP server hosted outside the cluster that ToolHive proxies, `VirtualMCPServer`, which aggregates multiple backend MCP servers behind a -single endpoint, and `MCPServerEntry`, which declares a remote MCP server as a -catalog entry without creating any pods or infrastructure. +single endpoint. All ToolHive CRDs are registered under the `toolhive` category, so you can list every ToolHive resource in your cluster with a single command: @@ -76,22 +75,11 @@ where your MCP server runs and how many servers you need to manage: | **MCPServer** | Running an MCP server as a container inside your cluster | | **MCPRemoteProxy** | Connecting to an MCP server hosted outside your cluster (SaaS tools, external APIs, remote endpoints) | | **VirtualMCPServer** | Aggregating multiple MCPServer and/or MCPRemoteProxy resources behind a single endpoint for a team or application | -| **MCPServerEntry** | Declaring a remote MCP server endpoint as a catalog entry without spawning proxy pods (no infrastructure created) | Most teams start with `MCPServer` for container-based servers, add `MCPRemoteProxy` for external SaaS tools, and graduate to `VirtualMCPServer` when managing five or more servers or needing centralized authentication. -:::note - -`MCPServerEntry` is a new resource type added in v0.16.0. The CRD is available -and you can create resources, but the reconciliation controller ships in a -future release. Creating `MCPServerEntry` resources before the controller is -available has no effect — the operator will not reconcile them until the -controller ships. - -::: - The operator also provides shared configuration CRDs that you reference from workload resources: diff --git a/docs/toolhive/guides-vmcp/scaling-and-performance.mdx b/docs/toolhive/guides-vmcp/scaling-and-performance.mdx index 9f456b46..4a039a82 100644 --- a/docs/toolhive/guides-vmcp/scaling-and-performance.mdx +++ b/docs/toolhive/guides-vmcp/scaling-and-performance.mdx @@ -71,9 +71,6 @@ are shared across pods and survive pod restarts. Without session storage, a request routed to a different replica than the one that established the session will fail, and sessions are lost when pods restart. -With Redis session storage configured, vMCP stores session state in Redis so -that any replica can resume a session, even after a pod restart or failover. - ```yaml title="VirtualMCPServer resource" spec: replicas: 3 From 0d7fb9a80ead5a49a0361da07699775583a77d89 Mon Sep 17 00:00:00 2001 From: Reynier Ortiz Vega Date: Mon, 13 Apr 2026 09:29:29 -0400 Subject: [PATCH 3/3] Fix Prettier formatting in intro.mdx --- docs/toolhive/guides-k8s/intro.mdx | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/toolhive/guides-k8s/intro.mdx b/docs/toolhive/guides-k8s/intro.mdx index 91a5545a..30938a36 100644 --- a/docs/toolhive/guides-k8s/intro.mdx +++ b/docs/toolhive/guides-k8s/intro.mdx @@ -67,14 +67,14 @@ or Gateway. To learn how to expose your MCP servers and connect clients, see ## Which resource type should I use? -The operator introduces resource types for MCP workloads. Choose based on -where your MCP server runs and how many servers you need to manage: - -| Resource | Use when | -| ----------------------- | ----------------------------------------------------------------------------------------------------------------- | -| **MCPServer** | Running an MCP server as a container inside your cluster | -| **MCPRemoteProxy** | Connecting to an MCP server hosted outside your cluster (SaaS tools, external APIs, remote endpoints) | -| **VirtualMCPServer** | Aggregating multiple MCPServer and/or MCPRemoteProxy resources behind a single endpoint for a team or application | +The operator introduces resource types for MCP workloads. Choose based on where +your MCP server runs and how many servers you need to manage: + +| Resource | Use when | +| -------------------- | ----------------------------------------------------------------------------------------------------------------- | +| **MCPServer** | Running an MCP server as a container inside your cluster | +| **MCPRemoteProxy** | Connecting to an MCP server hosted outside your cluster (SaaS tools, external APIs, remote endpoints) | +| **VirtualMCPServer** | Aggregating multiple MCPServer and/or MCPRemoteProxy resources behind a single endpoint for a team or application | Most teams start with `MCPServer` for container-based servers, add `MCPRemoteProxy` for external SaaS tools, and graduate to `VirtualMCPServer`