Skip to content

Commit 9fbf3a8

Browse files
reyortiz3claude
andcommitted
Update docs for ToolHive v0.16.0
- 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 <noreply@anthropic.com>
1 parent d6355d0 commit 9fbf3a8

4 files changed

Lines changed: 73 additions & 12 deletions

File tree

docs/toolhive/guides-cli/skills-management.mdx

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -301,6 +301,50 @@ authenticated before pushing.
301301

302302
:::
303303

304+
## List and remove locally-built skill artifacts
305+
306+
After building skills locally, you can view and manage the artifacts stored in
307+
your local OCI store.
308+
309+
### List locally-built artifacts
310+
311+
```bash
312+
thv skill builds
313+
```
314+
315+
This lists all OCI skill artifacts built locally with `thv skill build`. The
316+
output shows the tag, digest, name, and version of each artifact:
317+
318+
```text
319+
TAG DIGEST NAME VERSION
320+
ghcr.io/my-org/skills/my-skill:v1.0.0 sha256:a1b2c3d4... my-skill 1.0.0
321+
my-skill:latest sha256:e5f6a7b8... my-skill
322+
```
323+
324+
For JSON output:
325+
326+
```bash
327+
thv skill builds --format json
328+
```
329+
330+
### Remove a locally-built artifact
331+
332+
To remove an artifact from the local OCI store:
333+
334+
```bash
335+
thv skill builds remove <TAG>
336+
```
337+
338+
For example:
339+
340+
```bash
341+
thv skill builds remove my-skill:latest
342+
```
343+
344+
This removes the artifact and cleans up its blobs from the local store. If
345+
multiple tags share the same digest, the blobs are retained until all tags
346+
pointing to that digest are removed.
347+
304348
## Next steps
305349

306350
- [Configure your AI client](./client-configuration.mdx) to register clients
@@ -312,6 +356,7 @@ authenticated before pushing.
312356

313357
- [Understanding skills](../concepts/skills.mdx) for a conceptual overview
314358
- [`thv skill` command reference](../reference/cli/thv_skill.md)
359+
- [`thv skill builds` command reference](../reference/cli/thv_skill_builds.md)
315360
- [`thv serve` command reference](../reference/cli/thv_serve.md)
316361
- [Agent Skills specification](https://agentskills.io/specification)
317362

docs/toolhive/guides-k8s/auth-k8s.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -187,7 +187,7 @@ Check the MCPOIDCConfig status:
187187
kubectl get mcpoidc -n toolhive-system
188188
```
189189

190-
The `REFERENCES` column shows which workloads use this config. The `READY`
190+
The `REFERENCES` column shows which workloads use this config. The `VALID`
191191
column confirms validation passed.
192192

193193
### Benefits of MCPOIDCConfig

docs/toolhive/guides-k8s/intro.mdx

Lines changed: 21 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -21,9 +21,10 @@ quickly using a local kind cluster. Try it out and
2121
The operator introduces new Custom Resource Definitions (CRDs) into your
2222
Kubernetes cluster. The primary CRDs for MCP server workloads are `MCPServer`,
2323
which represents a single MCP server running in Kubernetes, `MCPRemoteProxy`,
24-
which represents an MCP server running outside the cluster that is proxied by
25-
ToolHive, and `VirtualMCPServer`, which represents a virtual MCP server gateway
26-
that aggregates multiple backend MCP servers.
24+
which represents an MCP server hosted outside the cluster that ToolHive proxies,
25+
`VirtualMCPServer`, which aggregates multiple backend MCP servers behind a
26+
single endpoint, and `MCPServerEntry`, which declares a remote MCP server as a
27+
catalog entry without creating any pods or infrastructure.
2728

2829
All ToolHive CRDs are registered under the `toolhive` category, so you can list
2930
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
6768

6869
## Which resource type should I use?
6970

70-
The operator introduces three resource types for MCP workloads. Choose based on
71+
The operator introduces resource types for MCP workloads. Choose based on
7172
where your MCP server runs and how many servers you need to manage:
7273

73-
| Resource | Use when |
74-
| -------------------- | ----------------------------------------------------------------------------------------------------------------- |
75-
| **MCPServer** | Running an MCP server as a container inside your cluster |
76-
| **MCPRemoteProxy** | Connecting to an MCP server hosted outside your cluster (SaaS tools, external APIs, remote endpoints) |
77-
| **VirtualMCPServer** | Aggregating multiple MCPServer and/or MCPRemoteProxy resources behind a single endpoint for a team or application |
74+
| Resource | Use when |
75+
| ----------------------- | ----------------------------------------------------------------------------------------------------------------- |
76+
| **MCPServer** | Running an MCP server as a container inside your cluster |
77+
| **MCPRemoteProxy** | Connecting to an MCP server hosted outside your cluster (SaaS tools, external APIs, remote endpoints) |
78+
| **VirtualMCPServer** | Aggregating multiple MCPServer and/or MCPRemoteProxy resources behind a single endpoint for a team or application |
79+
| **MCPServerEntry** | Declaring a remote MCP server endpoint as a catalog entry without spawning proxy pods (no infrastructure created) |
7880

7981
Most teams start with `MCPServer` for container-based servers, add
8082
`MCPRemoteProxy` for external SaaS tools, and graduate to `VirtualMCPServer`
8183
when managing five or more servers or needing centralized authentication.
8284

85+
:::note
86+
87+
`MCPServerEntry` is a new resource type added in v0.16.0. The CRD is available
88+
and you can create resources, but the reconciliation controller ships in a
89+
future release. Creating `MCPServerEntry` resources before the controller is
90+
available has no effect — the operator will not reconcile them until the
91+
controller ships.
92+
93+
:::
94+
8395
The operator also provides shared configuration CRDs that you reference from
8496
workload resources:
8597

docs/toolhive/guides-vmcp/scaling-and-performance.mdx

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -67,8 +67,12 @@ kubectl autoscale deployment vmcp-<VMCP_NAME> -n <NAMESPACE> \
6767
### Session storage for multi-replica deployments
6868

6969
When running multiple replicas, configure Redis session storage so that sessions
70-
are shared across pods. Without session storage, a request routed to a different
71-
replica than the one that established the session will fail.
70+
are shared across pods and survive pod restarts. Without session storage, a
71+
request routed to a different replica than the one that established the session
72+
will fail, and sessions are lost when pods restart.
73+
74+
With Redis session storage configured, vMCP stores session state in Redis so
75+
that any replica can resume a session, even after a pod restart or failover.
7276

7377
```yaml title="VirtualMCPServer resource"
7478
spec:

0 commit comments

Comments
 (0)