From 70ed1d864ea857d851ea9360b685a57ca3bb34be Mon Sep 17 00:00:00 2001 From: "renovate[bot]" <29139614+renovate[bot]@users.noreply.github.com> Date: Wed, 22 Apr 2026 15:09:58 +0000 Subject: [PATCH 1/8] Update stacklok/toolhive to v0.24.0 Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> --- .github/upstream-projects.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/upstream-projects.yaml b/.github/upstream-projects.yaml index ea5a2048..df8d66f0 100644 --- a/.github/upstream-projects.yaml +++ b/.github/upstream-projects.yaml @@ -35,7 +35,7 @@ projects: - id: toolhive repo: stacklok/toolhive - version: v0.23.1 + version: v0.24.0 # toolhive is a monorepo covering the CLI, the Kubernetes # operator, and the vMCP gateway. It also introduces cross- # cutting features that land in concepts/, integrations/, From 89629bf9244f2122dba6bd3358a9c7fcc4dc7690 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Wed, 22 Apr 2026 15:43:07 +0000 Subject: [PATCH 2/8] Refresh reference assets for toolhive v0.24.0 --- docs/toolhive/reference/cli/thv.md | 1 + docs/toolhive/reference/cli/thv_vmcp.md | 40 +++++++++++++ docs/toolhive/reference/cli/thv_vmcp_init.md | 50 +++++++++++++++++ docs/toolhive/reference/cli/thv_vmcp_serve.md | 56 +++++++++++++++++++ .../reference/cli/thv_vmcp_validate.md | 44 +++++++++++++++ 5 files changed, 191 insertions(+) create mode 100644 docs/toolhive/reference/cli/thv_vmcp.md create mode 100644 docs/toolhive/reference/cli/thv_vmcp_init.md create mode 100644 docs/toolhive/reference/cli/thv_vmcp_serve.md create mode 100644 docs/toolhive/reference/cli/thv_vmcp_validate.md diff --git a/docs/toolhive/reference/cli/thv.md b/docs/toolhive/reference/cli/thv.md index 9f6b4ac6..21660ca8 100644 --- a/docs/toolhive/reference/cli/thv.md +++ b/docs/toolhive/reference/cli/thv.md @@ -57,4 +57,5 @@ thv [flags] * [thv status](thv_status.md) - Show detailed status of an MCP server * [thv stop](thv_stop.md) - Stop one or more MCP servers * [thv version](thv_version.md) - Show the version of ToolHive +* [thv vmcp](thv_vmcp.md) - Run and manage a Virtual MCP Server locally diff --git a/docs/toolhive/reference/cli/thv_vmcp.md b/docs/toolhive/reference/cli/thv_vmcp.md new file mode 100644 index 00000000..d9d0ece7 --- /dev/null +++ b/docs/toolhive/reference/cli/thv_vmcp.md @@ -0,0 +1,40 @@ +--- +title: thv vmcp +hide_title: true +description: Reference for ToolHive CLI command `thv vmcp` +last_update: + author: autogenerated +slug: thv_vmcp +mdx: + format: md +--- + +## thv vmcp + +Run and manage a Virtual MCP Server locally + +### Synopsis + +The vmcp command provides subcommands to run and validate a Virtual MCP +Server (vMCP) locally without Kubernetes. A vMCP aggregates multiple MCP +servers from a ToolHive group into a single unified endpoint. + +### Options + +``` + -h, --help help for vmcp +``` + +### Options inherited from parent commands + +``` + --debug Enable debug mode +``` + +### SEE ALSO + +* [thv](thv.md) - ToolHive (thv) is a lightweight, secure, and fast manager for MCP servers +* [thv vmcp init](thv_vmcp_init.md) - Generate a starter vMCP configuration file +* [thv vmcp serve](thv_vmcp_serve.md) - Start the Virtual MCP Server +* [thv vmcp validate](thv_vmcp_validate.md) - Validate a vMCP configuration file + diff --git a/docs/toolhive/reference/cli/thv_vmcp_init.md b/docs/toolhive/reference/cli/thv_vmcp_init.md new file mode 100644 index 00000000..5f5c420e --- /dev/null +++ b/docs/toolhive/reference/cli/thv_vmcp_init.md @@ -0,0 +1,50 @@ +--- +title: thv vmcp init +hide_title: true +description: Reference for ToolHive CLI command `thv vmcp init` +last_update: + author: autogenerated +slug: thv_vmcp_init +mdx: + format: md +--- + +## thv vmcp init + +Generate a starter vMCP configuration file + +### Synopsis + +Discover running workloads in a ToolHive group and generate a starter +vMCP YAML configuration file pre-populated with one backend entry per +accessible workload. + +The generated file can be reviewed and customized, then passed to +'thv vmcp validate --config' to check it and 'thv vmcp serve --config' +to start the aggregated server. + +If neither --output nor --config is provided, the generated YAML is written to stdout. + +``` +thv vmcp init [flags] +``` + +### Options + +``` + -c, --config string Output file path for the generated config; alias for --output + -g, --group string ToolHive group name to discover workloads from (required) + -h, --help help for init + -o, --output string Output file path for the generated config (default: stdout) +``` + +### Options inherited from parent commands + +``` + --debug Enable debug mode +``` + +### SEE ALSO + +* [thv vmcp](thv_vmcp.md) - Run and manage a Virtual MCP Server locally + diff --git a/docs/toolhive/reference/cli/thv_vmcp_serve.md b/docs/toolhive/reference/cli/thv_vmcp_serve.md new file mode 100644 index 00000000..f20718f6 --- /dev/null +++ b/docs/toolhive/reference/cli/thv_vmcp_serve.md @@ -0,0 +1,56 @@ +--- +title: thv vmcp serve +hide_title: true +description: Reference for ToolHive CLI command `thv vmcp serve` +last_update: + author: autogenerated +slug: thv_vmcp_serve +mdx: + format: md +--- + +## thv vmcp serve + +Start the Virtual MCP Server + +### Synopsis + +Start the Virtual MCP Server to aggregate and proxy multiple MCP servers. + +The server reads the configuration file specified by --config and starts +listening for MCP client connections, aggregating tools, resources, and +prompts from all configured backend MCP servers. + +When --config is omitted, --group enables zero-config quick mode: a minimal +in-memory configuration is generated from the named ToolHive group, so no +configuration file is needed for the common case of aggregating a local group. + +``` +thv vmcp serve [flags] +``` + +### Options + +``` + -c, --config string Path to vMCP configuration file + --embedding-image string TEI container image (Tier 2) (default "ghcr.io/huggingface/text-embeddings-inference:cpu-latest") + --embedding-model string HuggingFace model name for semantic search (Tier 2) (default "BAAI/bge-small-en-v1.5") + --enable-audit Enable audit logging with default configuration + --group string ToolHive group name (zero-config quick mode when --config is omitted) + -h, --help help for serve + --host string Host address to bind to (default "127.0.0.1") + --optimizer Enable FTS5 keyword optimizer (Tier 1): exposes find_tool and call_tool instead of all backend tools + --optimizer-embedding Enable managed TEI semantic optimizer (Tier 2); implies --optimizer + --port int Port to listen on (default 4483) +``` + +### Options inherited from parent commands + +``` + --debug Enable debug mode +``` + +### SEE ALSO + +* [thv vmcp](thv_vmcp.md) - Run and manage a Virtual MCP Server locally + diff --git a/docs/toolhive/reference/cli/thv_vmcp_validate.md b/docs/toolhive/reference/cli/thv_vmcp_validate.md new file mode 100644 index 00000000..0f88282b --- /dev/null +++ b/docs/toolhive/reference/cli/thv_vmcp_validate.md @@ -0,0 +1,44 @@ +--- +title: thv vmcp validate +hide_title: true +description: Reference for ToolHive CLI command `thv vmcp validate` +last_update: + author: autogenerated +slug: thv_vmcp_validate +mdx: + format: md +--- + +## thv vmcp validate + +Validate a vMCP configuration file + +### Synopsis + +Validate the vMCP configuration file for syntax and semantic errors. + +This command checks YAML syntax, required field presence, middleware +configuration correctness, and backend configuration validity. Exits 0 +for valid configurations, non-zero with a descriptive error otherwise. + +``` +thv vmcp validate [flags] +``` + +### Options + +``` + -c, --config string Path to vMCP configuration file (required) + -h, --help help for validate +``` + +### Options inherited from parent commands + +``` + --debug Enable debug mode +``` + +### SEE ALSO + +* [thv vmcp](thv_vmcp.md) - Run and manage a Virtual MCP Server locally + From ffea8d5bd924f9331d46cb07b2d3ba3717eefbce Mon Sep 17 00:00:00 2001 From: "claude[bot]" <41898282+claude[bot]@users.noreply.github.com> Date: Wed, 22 Apr 2026 15:48:21 +0000 Subject: [PATCH 3/8] Add local vMCP CLI guide for toolhive v0.24.0 Document thv vmcp serve/validate/init, which was unhidden in upstream PR #5001. Add a new guide covering quick mode, config-file mode, optimizer tiers, and a comparison to the Kubernetes VirtualMCPServer path. Update vMCP intro, index, and concept pages to surface the local CLI alongside the operator-based deployment. --- SUMMARY.md | 13 ++ docs/toolhive/concepts/vmcp.mdx | 11 +- docs/toolhive/guides-vmcp/index.mdx | 7 +- docs/toolhive/guides-vmcp/intro.mdx | 26 ++- docs/toolhive/guides-vmcp/local-cli.mdx | 273 ++++++++++++++++++++++++ sidebars.ts | 1 + 6 files changed, 320 insertions(+), 11 deletions(-) create mode 100644 SUMMARY.md create mode 100644 docs/toolhive/guides-vmcp/local-cli.mdx diff --git a/SUMMARY.md b/SUMMARY.md new file mode 100644 index 00000000..5ebe9f0d --- /dev/null +++ b/SUMMARY.md @@ -0,0 +1,13 @@ +# Summary of changes + +- Added `docs/toolhive/guides-vmcp/local-cli.mdx`: a new guide for running vMCP + locally via `thv vmcp serve/validate/init`, covering quick mode vs. + config-file mode, optimizer tiers 0-3, `--enable-audit`, full flag tables, and + a comparison to the Kubernetes `VirtualMCPServer` CRD path. +- Updated `docs/toolhive/guides-vmcp/intro.mdx` and + `docs/toolhive/guides-vmcp/index.mdx` so the entry points surface the new + local CLI option alongside the existing Kubernetes deployment. +- Updated `docs/toolhive/concepts/vmcp.mdx` so the concept page acknowledges + both delivery modes (operator CRD and CLI) and links to the local guide. +- Updated `sidebars.ts` to list the new `local-cli` guide under **Virtual MCP + Server**, immediately after the Kubernetes quickstart. diff --git a/docs/toolhive/concepts/vmcp.mdx b/docs/toolhive/concepts/vmcp.mdx index 7a4e79ad..992c805c 100644 --- a/docs/toolhive/concepts/vmcp.mdx +++ b/docs/toolhive/concepts/vmcp.mdx @@ -6,10 +6,11 @@ description: for simpler client configuration. --- -This document explains Virtual MCP Server (vMCP), a feature of the ToolHive -Kubernetes Operator. You'll learn why it exists, when to use it, and how it -simplifies managing multiple MCP servers while enabling powerful multi-system -workflows. +This document explains Virtual MCP Server (vMCP), a ToolHive feature available +both through the [Kubernetes operator](../guides-vmcp/quickstart.mdx) and the +[local CLI](../guides-vmcp/local-cli.mdx). You'll learn why it exists, when to +use it, and how it simplifies managing multiple MCP servers while enabling +powerful multi-system workflows. ## The problem vMCP solves @@ -176,6 +177,8 @@ teams managing multiple MCP servers. - [Try the Quickstart](../guides-vmcp/quickstart.mdx) to deploy your first vMCP on a Kubernetes cluster +- [Run vMCP locally with the CLI](../guides-vmcp/local-cli.mdx) for a quick + evaluation without Kubernetes - [Learn how to deploy vMCP](../guides-vmcp/intro.mdx) for a full overview of configuration and architecture diff --git a/docs/toolhive/guides-vmcp/index.mdx b/docs/toolhive/guides-vmcp/index.mdx index 64675afa..561085c6 100644 --- a/docs/toolhive/guides-vmcp/index.mdx +++ b/docs/toolhive/guides-vmcp/index.mdx @@ -17,8 +17,11 @@ connection. - **Evaluating vMCP?** Read [Understanding Virtual MCP Server](../concepts/vmcp.mdx) for the full picture of what it does and when it's the right fit. -- **Ready to try it?** Follow the [Quickstart](./quickstart.mdx) to deploy your - first vMCP on a Kubernetes cluster. +- **Want to try it on your workstation?** Run + [vMCP locally with the CLI](./local-cli.mdx) to aggregate a local ToolHive + group without a cluster. +- **Ready for Kubernetes?** Follow the [Quickstart](./quickstart.mdx) to deploy + your first vMCP through the operator. - **Already running vMCP?** Jump to [Configuration](./configuration.mdx) or [Authentication](./authentication.mdx). diff --git a/docs/toolhive/guides-vmcp/intro.mdx b/docs/toolhive/guides-vmcp/intro.mdx index 3f1bb088..a549dd95 100644 --- a/docs/toolhive/guides-vmcp/intro.mdx +++ b/docs/toolhive/guides-vmcp/intro.mdx @@ -7,11 +7,25 @@ description: ## What is vMCP? -Virtual MCP Server (vMCP) is a feature of the ToolHive Kubernetes Operator that -acts as an aggregation proxy, consolidating multiple backend MCP servers into a -single unified interface. Instead of configuring clients to connect to each MCP -server individually, you connect once to vMCP and access all backend tools -through a single endpoint. +Virtual MCP Server (vMCP) is a ToolHive feature that acts as an aggregation +proxy, consolidating multiple backend MCP servers into a single unified +interface. Instead of configuring clients to connect to each MCP server +individually, you connect once to vMCP and access all backend tools through a +single endpoint. + +You can run vMCP two ways: + +- **On Kubernetes** through the `VirtualMCPServer` custom resource managed by + the ToolHive operator. This is the recommended option for shared, + multi-tenant, or production deployments. +- **Locally from the CLI** with the `thv vmcp` command, which aggregates a + local [ToolHive group](../concepts/groups.mdx) without a cluster. See + [Run vMCP locally with the CLI](./local-cli.mdx). + +The underlying aggregation, tool routing, and optimizer capabilities are the +same in both modes. The rest of this page focuses on the Kubernetes deployment +model; switch to the local CLI guide if you want to try vMCP on your +workstation first. vMCP supports two types of backends: @@ -110,6 +124,8 @@ guide. - [Try the Quickstart](./quickstart.mdx) to deploy your first vMCP on a Kubernetes cluster +- [Run vMCP locally with the CLI](./local-cli.mdx) to aggregate a local + ToolHive group without Kubernetes - [Configure vMCP servers](./configuration.mdx) to set up groups, backends, and tool aggregation diff --git a/docs/toolhive/guides-vmcp/local-cli.mdx b/docs/toolhive/guides-vmcp/local-cli.mdx new file mode 100644 index 00000000..8dee3eb5 --- /dev/null +++ b/docs/toolhive/guides-vmcp/local-cli.mdx @@ -0,0 +1,273 @@ +--- +title: Run vMCP locally with the CLI +description: + Run Virtual MCP Server locally with the thv vmcp command to aggregate a + ToolHive group without Kubernetes. +--- + +Virtual MCP Server (vMCP) is usually deployed on Kubernetes through the +`VirtualMCPServer` custom resource, but you can also run it locally from the +ToolHive CLI. The `thv vmcp` subcommands aggregate the MCP servers in a local +[ToolHive group](../concepts/groups.mdx) behind a single endpoint, without a +cluster or operator. + +Use this mode for local development, quick evaluation, or any case where you +want vMCP's aggregation, tool routing, and optimizer capabilities without the +operational overhead of Kubernetes. + +## When to use the local CLI + +- You are developing or evaluating vMCP on your workstation. +- You run MCP servers locally with `thv run` and want to expose them through a + single endpoint. +- You want to use the vMCP [optimizer](./optimizer.mdx) to reduce token usage + across a local group. +- You don't yet need the clustered, operator-managed deployment model covered + in the [Quickstart](./quickstart.mdx). + +For production and multi-tenant deployments, use the Kubernetes +[`VirtualMCPServer`](../guides-k8s/quickstart.mdx) resource instead. + +## Prerequisites + +- ToolHive CLI v0.24.0 or later. Check with `thv version`. +- A container runtime (Docker, Podman, or OrbStack) available to ToolHive. +- A ToolHive group with one or more running MCP servers. To create one: + + ```bash + thv group create my-group + thv run --group my-group fetch + thv run --group my-group github + ``` + + See [Manage ToolHive groups](../guides-cli/group-management.mdx) for details. + +## Subcommands at a glance + +The `thv vmcp` command has three subcommands: + +| Subcommand | Purpose | +| ------------------- | ---------------------------------------------------------- | +| `thv vmcp init` | Generate a starter YAML config from a running group | +| `thv vmcp validate` | Validate a YAML config for syntax and semantic errors | +| `thv vmcp serve` | Start the aggregated vMCP server | + +There are two ways to run the server: + +- **Quick mode** uses `thv vmcp serve --group ` to generate an in-memory + config from a group. No YAML file is required. +- **Config-file mode** uses `thv vmcp init` → edit → `thv vmcp validate` → + `thv vmcp serve --config vmcp.yaml` for reproducible or customized setups. + +## Quick mode + +Quick mode is the fastest way to aggregate a local group. Run the server with +just a group name: + +```bash +thv vmcp serve --group my-group +``` + +By default, the server binds to `127.0.0.1:4483`. Point your MCP client at +`http://127.0.0.1:4483` to access all tools from the group through a single +endpoint. + +:::note[Loopback-only] + +Quick mode always uses anonymous authentication, so `thv vmcp serve --group` +only accepts loopback bind addresses (`127.0.0.1`, `::1`, `localhost`, or the +default empty value). Binding to a non-loopback interface is rejected to avoid +exposing an unauthenticated server on the network. To bind to a non-loopback +address, use [config-file mode](#config-file-mode) and configure client +authentication. + +::: + +### Enable the optimizer in quick mode + +Add `--optimizer` or `--optimizer-embedding` to replace the full tool list with +`find_tool` and `call_tool` primitives: + +```bash +# Tier 1: FTS5 keyword search (no external container) +thv vmcp serve --group my-group --optimizer + +# Tier 2: FTS5 + semantic search using a managed TEI container +thv vmcp serve --group my-group --optimizer-embedding +``` + +See [Optimizer tiers](#optimizer-tiers) for the full comparison. + +## Config-file mode + +Config-file mode is recommended when you need to customize backend settings, +authentication, or aggregation rules, or when you want a reproducible setup +checked into version control. + +### Step 1: Generate a starter config + +`thv vmcp init` discovers running workloads in a group and writes a starter +YAML file with one backend entry per accessible workload: + +```bash +thv vmcp init --group my-group --output vmcp.yaml +``` + +Omit `--output` to write the generated YAML to standard output instead. + +The generated file includes inline comments describing each section. A minimal +example looks like this: + +```yaml title="vmcp.yaml" +# Generated by `thv vmcp init`. Review and customize before use. + +name: my-group-vmcp +groupRef: my-group + +incomingAuth: + type: anonymous + +outgoingAuth: + source: inline + +aggregation: + conflictResolution: prefix + conflictResolutionConfig: + prefixFormat: '{workload}_' + +backends: + - name: fetch + url: http://127.0.0.1:12345/sse + transport: sse + - name: github + url: http://127.0.0.1:12346/mcp + transport: streamable-http +``` + +### Step 2: Review and edit + +Customize the generated config. Common edits include: + +- Changing `incomingAuth` from `anonymous` to `oidc` to require authenticated + clients. +- Adding tool filters, renames, or overrides under each backend. +- Configuring the [optimizer](./optimizer.mdx) under an `optimizer` section. + +See [Configure vMCP](./configuration.mdx) for the full schema. + +### Step 3: Validate the config + +```bash +thv vmcp validate --config vmcp.yaml +``` + +Validation checks YAML syntax, required fields, middleware configuration, and +backend settings. It exits `0` on success and non-zero with a descriptive +message otherwise. + +### Step 4: Start the server + +```bash +thv vmcp serve --config vmcp.yaml +``` + +When both `--config` and `--group` are set, `--config` takes precedence. + +## Optimizer tiers + +`thv vmcp serve` supports four tiers of tool optimization. Tier 0 is the +default; tiers 1 through 3 replace the full backend tool list with `find_tool` +and `call_tool` primitives that perform hybrid search against the aggregated +tool set. + +| Tier | Flag or setting | Search | External service | +| ---- | ---------------------------------------------- | ----------------------------- | ----------------------------- | +| 0 | (none) | None - all tools passed through | None | +| 1 | `--optimizer` | FTS5 keyword (in-process) | None | +| 2 | `--optimizer-embedding` | FTS5 + TEI semantic | Managed TEI container | +| 3 | `optimizer.embeddingService` in config YAML | FTS5 + external embedding | User-managed embedding server | + +Tier 2 implies Tier 1: `--optimizer-embedding` also enables the keyword index. +For Tier 2, ToolHive starts and stops a HuggingFace Text Embeddings Inference +(TEI) container named `thv-embedding-` automatically. Customize the model +and image with `--embedding-model` and `--embedding-image`. + +For the conceptual background and tuning parameters, see +[Optimize tool discovery](./optimizer.mdx) and +[Tool optimization](../concepts/tool-optimization.mdx). + +## Enable audit logging + +Add `--enable-audit` to `thv vmcp serve` to turn on audit logging with default +settings when the loaded config doesn't already define an audit section: + +```bash +thv vmcp serve --group my-group --enable-audit +``` + +For audit configuration options, see [Audit logging](./audit-logging.mdx). + +## Command reference + +All `thv vmcp` flags, with their defaults: + +### `thv vmcp serve` + +| Flag | Default | Description | +| ----------------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------- | +| `--config`, `-c` | (empty) | Path to a vMCP configuration file | +| `--group` | (empty) | ToolHive group name for quick mode (used when `--config` is not set) | +| `--host` | `127.0.0.1` | Bind address (quick mode requires a loopback address) | +| `--port` | `4483` | TCP port to listen on | +| `--enable-audit` | `false` | Enable audit logging with default configuration | +| `--optimizer` | `false` | Enable Tier 1 FTS5 keyword optimizer | +| `--optimizer-embedding` | `false` | Enable Tier 2 semantic optimizer (implies `--optimizer`) | +| `--embedding-model` | `BAAI/bge-small-en-v1.5` | HuggingFace model name for the managed TEI container | +| `--embedding-image` | `ghcr.io/huggingface/text-embeddings-inference:cpu-latest` | TEI container image | + +### `thv vmcp init` + +| Flag | Default | Description | +| ----------------- | --------- | --------------------------------------------------------------------------- | +| `--group`, `-g` | (required) | ToolHive group name whose workloads are discovered | +| `--output`, `-o` | stdout | Output file path for the generated config | +| `--config`, `-c` | stdout | Alias for `--output` | + +### `thv vmcp validate` + +| Flag | Default | Description | +| ----------------- | --------- | ----------------------------------------------- | +| `--config`, `-c` | (required) | Path to the vMCP configuration file to validate | + +For full CLI help, run `thv vmcp --help` or see +[`thv vmcp`](../reference/cli/thv_vmcp.md) in the reference. + +## Compared to the Kubernetes deployment + +| Aspect | Local CLI (`thv vmcp`) | Kubernetes (`VirtualMCPServer` CRD) | +| ------------------ | ---------------------------------------------- | ---------------------------------------------- | +| Runtime | Foreground process | Pod managed by the operator | +| Configuration | CLI flags or local YAML file | `VirtualMCPServer` custom resource | +| Backend discovery | Reads ToolHive groups on the local machine | Reads `MCPGroup` resources in the cluster | +| Authentication | Anonymous in quick mode; configurable in files | Full OIDC integration via CRD fields | +| Lifecycle | Tied to the terminal session | Managed declaratively, survives restarts | +| Embedding server | Managed TEI container (Tier 2) | `EmbeddingServer` custom resource | + +The underlying aggregation, tool routing, and optimizer logic are the same. Use +the local CLI for development and single-user workflows; use the Kubernetes +deployment for shared, production, or multi-user environments. + +## Next steps + +- [Configure vMCP](./configuration.mdx) to customize backends, authentication, + and aggregation rules. +- [Optimize tool discovery](./optimizer.mdx) to tune `find_tool` and + `call_tool` for large toolsets. +- [Deploy vMCP on Kubernetes](./quickstart.mdx) when you're ready to move to a + production-grade deployment. + +## Related information + +- [Understanding Virtual MCP Server](../concepts/vmcp.mdx) +- [Manage ToolHive groups](../guides-cli/group-management.mdx) +- [`thv vmcp` CLI reference](../reference/cli/thv_vmcp.md) diff --git a/sidebars.ts b/sidebars.ts index 839f0a50..bbaaa8c4 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -176,6 +176,7 @@ const sidebars: SidebarsConfig = { items: [ 'toolhive/guides-vmcp/intro', 'toolhive/guides-vmcp/quickstart', + 'toolhive/guides-vmcp/local-cli', 'toolhive/guides-vmcp/configuration', 'toolhive/guides-vmcp/backend-discovery', 'toolhive/guides-vmcp/authentication', From 56a121b92a331ab9a3a0b6e21e14adfd930ca81d Mon Sep 17 00:00:00 2001 From: "claude[bot]" <41898282+claude[bot]@users.noreply.github.com> Date: Wed, 22 Apr 2026 15:52:40 +0000 Subject: [PATCH 4/8] Fix vMCP local CLI guide link and tier description Point the "production" cross-link at the vMCP-specific quickstart instead of the general operator quickstart. Also tighten the optimizer-tier intro so Tier 1 (FTS5 keyword only) is not described as hybrid search. Co-authored-by: Radoslav Dimitrov --- docs/toolhive/guides-vmcp/local-cli.mdx | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/toolhive/guides-vmcp/local-cli.mdx b/docs/toolhive/guides-vmcp/local-cli.mdx index 8dee3eb5..1d2d2899 100644 --- a/docs/toolhive/guides-vmcp/local-cli.mdx +++ b/docs/toolhive/guides-vmcp/local-cli.mdx @@ -26,7 +26,7 @@ operational overhead of Kubernetes. in the [Quickstart](./quickstart.mdx). For production and multi-tenant deployments, use the Kubernetes -[`VirtualMCPServer`](../guides-k8s/quickstart.mdx) resource instead. +[`VirtualMCPServer`](./quickstart.mdx) resource instead. ## Prerequisites @@ -177,8 +177,9 @@ When both `--config` and `--group` are set, `--config` takes precedence. `thv vmcp serve` supports four tiers of tool optimization. Tier 0 is the default; tiers 1 through 3 replace the full backend tool list with `find_tool` -and `call_tool` primitives that perform hybrid search against the aggregated -tool set. +and `call_tool` primitives that search the aggregated tool set. Tier 1 uses +FTS5 keyword search only; tiers 2 and 3 add semantic embeddings on top for +hybrid search. | Tier | Flag or setting | Search | External service | | ---- | ---------------------------------------------- | ----------------------------- | ----------------------------- | From 4aaa63f088e9288c0d9b96428196ca16f065044b Mon Sep 17 00:00:00 2001 From: "claude[bot]" <41898282+claude[bot]@users.noreply.github.com> Date: Wed, 22 Apr 2026 15:53:08 +0000 Subject: [PATCH 5/8] Apply prettier and eslint fixups to skill output --- docs/toolhive/guides-vmcp/intro.mdx | 12 ++-- docs/toolhive/guides-vmcp/local-cli.mdx | 94 ++++++++++++------------- 2 files changed, 53 insertions(+), 53 deletions(-) diff --git a/docs/toolhive/guides-vmcp/intro.mdx b/docs/toolhive/guides-vmcp/intro.mdx index a549dd95..066129ab 100644 --- a/docs/toolhive/guides-vmcp/intro.mdx +++ b/docs/toolhive/guides-vmcp/intro.mdx @@ -18,14 +18,14 @@ You can run vMCP two ways: - **On Kubernetes** through the `VirtualMCPServer` custom resource managed by the ToolHive operator. This is the recommended option for shared, multi-tenant, or production deployments. -- **Locally from the CLI** with the `thv vmcp` command, which aggregates a - local [ToolHive group](../concepts/groups.mdx) without a cluster. See +- **Locally from the CLI** with the `thv vmcp` command, which aggregates a local + [ToolHive group](../concepts/groups.mdx) without a cluster. See [Run vMCP locally with the CLI](./local-cli.mdx). The underlying aggregation, tool routing, and optimizer capabilities are the same in both modes. The rest of this page focuses on the Kubernetes deployment -model; switch to the local CLI guide if you want to try vMCP on your -workstation first. +model; switch to the local CLI guide if you want to try vMCP on your workstation +first. vMCP supports two types of backends: @@ -124,8 +124,8 @@ guide. - [Try the Quickstart](./quickstart.mdx) to deploy your first vMCP on a Kubernetes cluster -- [Run vMCP locally with the CLI](./local-cli.mdx) to aggregate a local - ToolHive group without Kubernetes +- [Run vMCP locally with the CLI](./local-cli.mdx) to aggregate a local ToolHive + group without Kubernetes - [Configure vMCP servers](./configuration.mdx) to set up groups, backends, and tool aggregation diff --git a/docs/toolhive/guides-vmcp/local-cli.mdx b/docs/toolhive/guides-vmcp/local-cli.mdx index 1d2d2899..cbd7d7f8 100644 --- a/docs/toolhive/guides-vmcp/local-cli.mdx +++ b/docs/toolhive/guides-vmcp/local-cli.mdx @@ -22,8 +22,8 @@ operational overhead of Kubernetes. single endpoint. - You want to use the vMCP [optimizer](./optimizer.mdx) to reduce token usage across a local group. -- You don't yet need the clustered, operator-managed deployment model covered - in the [Quickstart](./quickstart.mdx). +- You don't yet need the clustered, operator-managed deployment model covered in + the [Quickstart](./quickstart.mdx). For production and multi-tenant deployments, use the Kubernetes [`VirtualMCPServer`](./quickstart.mdx) resource instead. @@ -46,11 +46,11 @@ For production and multi-tenant deployments, use the Kubernetes The `thv vmcp` command has three subcommands: -| Subcommand | Purpose | -| ------------------- | ---------------------------------------------------------- | -| `thv vmcp init` | Generate a starter YAML config from a running group | -| `thv vmcp validate` | Validate a YAML config for syntax and semantic errors | -| `thv vmcp serve` | Start the aggregated vMCP server | +| Subcommand | Purpose | +| ------------------- | ----------------------------------------------------- | +| `thv vmcp init` | Generate a starter YAML config from a running group | +| `thv vmcp validate` | Validate a YAML config for syntax and semantic errors | +| `thv vmcp serve` | Start the aggregated vMCP server | There are two ways to run the server: @@ -106,8 +106,8 @@ checked into version control. ### Step 1: Generate a starter config -`thv vmcp init` discovers running workloads in a group and writes a starter -YAML file with one backend entry per accessible workload: +`thv vmcp init` discovers running workloads in a group and writes a starter YAML +file with one backend entry per accessible workload: ```bash thv vmcp init --group my-group --output vmcp.yaml @@ -177,16 +177,16 @@ When both `--config` and `--group` are set, `--config` takes precedence. `thv vmcp serve` supports four tiers of tool optimization. Tier 0 is the default; tiers 1 through 3 replace the full backend tool list with `find_tool` -and `call_tool` primitives that search the aggregated tool set. Tier 1 uses -FTS5 keyword search only; tiers 2 and 3 add semantic embeddings on top for -hybrid search. +and `call_tool` primitives that search the aggregated tool set. Tier 1 uses FTS5 +keyword search only; tiers 2 and 3 add semantic embeddings on top for hybrid +search. -| Tier | Flag or setting | Search | External service | -| ---- | ---------------------------------------------- | ----------------------------- | ----------------------------- | -| 0 | (none) | None - all tools passed through | None | -| 1 | `--optimizer` | FTS5 keyword (in-process) | None | -| 2 | `--optimizer-embedding` | FTS5 + TEI semantic | Managed TEI container | -| 3 | `optimizer.embeddingService` in config YAML | FTS5 + external embedding | User-managed embedding server | +| Tier | Flag or setting | Search | External service | +| ---- | ------------------------------------------- | ------------------------------- | ----------------------------- | +| 0 | (none) | None - all tools passed through | None | +| 1 | `--optimizer` | FTS5 keyword (in-process) | None | +| 2 | `--optimizer-embedding` | FTS5 + TEI semantic | Managed TEI container | +| 3 | `optimizer.embeddingService` in config YAML | FTS5 + external embedding | User-managed embedding server | Tier 2 implies Tier 1: `--optimizer-embedding` also enables the keyword index. For Tier 2, ToolHive starts and stops a HuggingFace Text Embeddings Inference @@ -214,45 +214,45 @@ All `thv vmcp` flags, with their defaults: ### `thv vmcp serve` -| Flag | Default | Description | -| ----------------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------- | -| `--config`, `-c` | (empty) | Path to a vMCP configuration file | -| `--group` | (empty) | ToolHive group name for quick mode (used when `--config` is not set) | -| `--host` | `127.0.0.1` | Bind address (quick mode requires a loopback address) | -| `--port` | `4483` | TCP port to listen on | -| `--enable-audit` | `false` | Enable audit logging with default configuration | -| `--optimizer` | `false` | Enable Tier 1 FTS5 keyword optimizer | -| `--optimizer-embedding` | `false` | Enable Tier 2 semantic optimizer (implies `--optimizer`) | -| `--embedding-model` | `BAAI/bge-small-en-v1.5` | HuggingFace model name for the managed TEI container | -| `--embedding-image` | `ghcr.io/huggingface/text-embeddings-inference:cpu-latest` | TEI container image | +| Flag | Default | Description | +| ----------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------- | +| `--config`, `-c` | (empty) | Path to a vMCP configuration file | +| `--group` | (empty) | ToolHive group name for quick mode (used when `--config` is not set) | +| `--host` | `127.0.0.1` | Bind address (quick mode requires a loopback address) | +| `--port` | `4483` | TCP port to listen on | +| `--enable-audit` | `false` | Enable audit logging with default configuration | +| `--optimizer` | `false` | Enable Tier 1 FTS5 keyword optimizer | +| `--optimizer-embedding` | `false` | Enable Tier 2 semantic optimizer (implies `--optimizer`) | +| `--embedding-model` | `BAAI/bge-small-en-v1.5` | HuggingFace model name for the managed TEI container | +| `--embedding-image` | `ghcr.io/huggingface/text-embeddings-inference:cpu-latest` | TEI container image | ### `thv vmcp init` -| Flag | Default | Description | -| ----------------- | --------- | --------------------------------------------------------------------------- | -| `--group`, `-g` | (required) | ToolHive group name whose workloads are discovered | -| `--output`, `-o` | stdout | Output file path for the generated config | -| `--config`, `-c` | stdout | Alias for `--output` | +| Flag | Default | Description | +| ---------------- | ---------- | -------------------------------------------------- | +| `--group`, `-g` | (required) | ToolHive group name whose workloads are discovered | +| `--output`, `-o` | stdout | Output file path for the generated config | +| `--config`, `-c` | stdout | Alias for `--output` | ### `thv vmcp validate` -| Flag | Default | Description | -| ----------------- | --------- | ----------------------------------------------- | -| `--config`, `-c` | (required) | Path to the vMCP configuration file to validate | +| Flag | Default | Description | +| ---------------- | ---------- | ----------------------------------------------- | +| `--config`, `-c` | (required) | Path to the vMCP configuration file to validate | For full CLI help, run `thv vmcp --help` or see [`thv vmcp`](../reference/cli/thv_vmcp.md) in the reference. ## Compared to the Kubernetes deployment -| Aspect | Local CLI (`thv vmcp`) | Kubernetes (`VirtualMCPServer` CRD) | -| ------------------ | ---------------------------------------------- | ---------------------------------------------- | -| Runtime | Foreground process | Pod managed by the operator | -| Configuration | CLI flags or local YAML file | `VirtualMCPServer` custom resource | -| Backend discovery | Reads ToolHive groups on the local machine | Reads `MCPGroup` resources in the cluster | -| Authentication | Anonymous in quick mode; configurable in files | Full OIDC integration via CRD fields | -| Lifecycle | Tied to the terminal session | Managed declaratively, survives restarts | -| Embedding server | Managed TEI container (Tier 2) | `EmbeddingServer` custom resource | +| Aspect | Local CLI (`thv vmcp`) | Kubernetes (`VirtualMCPServer` CRD) | +| ----------------- | ---------------------------------------------- | ----------------------------------------- | +| Runtime | Foreground process | Pod managed by the operator | +| Configuration | CLI flags or local YAML file | `VirtualMCPServer` custom resource | +| Backend discovery | Reads ToolHive groups on the local machine | Reads `MCPGroup` resources in the cluster | +| Authentication | Anonymous in quick mode; configurable in files | Full OIDC integration via CRD fields | +| Lifecycle | Tied to the terminal session | Managed declaratively, survives restarts | +| Embedding server | Managed TEI container (Tier 2) | `EmbeddingServer` custom resource | The underlying aggregation, tool routing, and optimizer logic are the same. Use the local CLI for development and single-user workflows; use the Kubernetes @@ -262,8 +262,8 @@ deployment for shared, production, or multi-user environments. - [Configure vMCP](./configuration.mdx) to customize backends, authentication, and aggregation rules. -- [Optimize tool discovery](./optimizer.mdx) to tune `find_tool` and - `call_tool` for large toolsets. +- [Optimize tool discovery](./optimizer.mdx) to tune `find_tool` and `call_tool` + for large toolsets. - [Deploy vMCP on Kubernetes](./quickstart.mdx) when you're ready to move to a production-grade deployment. From 2cf51f64a34136d1ed60c1e20afb4725ae14bd3d Mon Sep 17 00:00:00 2001 From: "claude[bot]" <41898282+claude[bot]@users.noreply.github.com> Date: Wed, 22 Apr 2026 15:53:08 +0000 Subject: [PATCH 6/8] Add upstream-release-docs content for toolhive v0.24.0 --- SUMMARY.md | 13 ------------- 1 file changed, 13 deletions(-) delete mode 100644 SUMMARY.md diff --git a/SUMMARY.md b/SUMMARY.md deleted file mode 100644 index 5ebe9f0d..00000000 --- a/SUMMARY.md +++ /dev/null @@ -1,13 +0,0 @@ -# Summary of changes - -- Added `docs/toolhive/guides-vmcp/local-cli.mdx`: a new guide for running vMCP - locally via `thv vmcp serve/validate/init`, covering quick mode vs. - config-file mode, optimizer tiers 0-3, `--enable-audit`, full flag tables, and - a comparison to the Kubernetes `VirtualMCPServer` CRD path. -- Updated `docs/toolhive/guides-vmcp/intro.mdx` and - `docs/toolhive/guides-vmcp/index.mdx` so the entry points surface the new - local CLI option alongside the existing Kubernetes deployment. -- Updated `docs/toolhive/concepts/vmcp.mdx` so the concept page acknowledges - both delivery modes (operator CRD and CLI) and links to the local guide. -- Updated `sidebars.ts` to list the new `local-cli` guide under **Virtual MCP - Server**, immediately after the Kubernetes quickstart. From 753dd0aefc8943de3c02e2ca509496211388f990 Mon Sep 17 00:00:00 2001 From: "claude[bot]" <41898282+claude[bot]@users.noreply.github.com> Date: Wed, 22 Apr 2026 17:14:41 +0000 Subject: [PATCH 7/8] Reposition local vMCP CLI as secondary workflow Move local-cli sidebar entry to end of vMCP section; reorder index.mdx "Where to start" so K8s quickstart comes before local CLI; reframe intro.mdx to remove implication that local is a first step toward K8s. Co-authored-by: Dan Barr --- docs/toolhive/guides-vmcp/index.mdx | 10 +++++----- docs/toolhive/guides-vmcp/intro.mdx | 4 ++-- sidebars.ts | 2 +- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/toolhive/guides-vmcp/index.mdx b/docs/toolhive/guides-vmcp/index.mdx index 561085c6..6a6fdf29 100644 --- a/docs/toolhive/guides-vmcp/index.mdx +++ b/docs/toolhive/guides-vmcp/index.mdx @@ -17,13 +17,13 @@ connection. - **Evaluating vMCP?** Read [Understanding Virtual MCP Server](../concepts/vmcp.mdx) for the full picture of what it does and when it's the right fit. -- **Want to try it on your workstation?** Run - [vMCP locally with the CLI](./local-cli.mdx) to aggregate a local ToolHive - group without a cluster. -- **Ready for Kubernetes?** Follow the [Quickstart](./quickstart.mdx) to deploy - your first vMCP through the operator. +- **Ready to deploy?** Follow the [Quickstart](./quickstart.mdx) to deploy your + first vMCP through the Kubernetes operator. - **Already running vMCP?** Jump to [Configuration](./configuration.mdx) or [Authentication](./authentication.mdx). +- **Local testing only?** Run + [vMCP locally with the CLI](./local-cli.mdx) to aggregate a local ToolHive + group without a cluster. ## Contents diff --git a/docs/toolhive/guides-vmcp/intro.mdx b/docs/toolhive/guides-vmcp/intro.mdx index 066129ab..08de30af 100644 --- a/docs/toolhive/guides-vmcp/intro.mdx +++ b/docs/toolhive/guides-vmcp/intro.mdx @@ -24,8 +24,8 @@ You can run vMCP two ways: The underlying aggregation, tool routing, and optimizer capabilities are the same in both modes. The rest of this page focuses on the Kubernetes deployment -model; switch to the local CLI guide if you want to try vMCP on your workstation -first. +model. For individual development or local testing without a cluster, see +[Run vMCP locally with the CLI](./local-cli.mdx). vMCP supports two types of backends: diff --git a/sidebars.ts b/sidebars.ts index bbaaa8c4..8557f677 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -176,7 +176,6 @@ const sidebars: SidebarsConfig = { items: [ 'toolhive/guides-vmcp/intro', 'toolhive/guides-vmcp/quickstart', - 'toolhive/guides-vmcp/local-cli', 'toolhive/guides-vmcp/configuration', 'toolhive/guides-vmcp/backend-discovery', 'toolhive/guides-vmcp/authentication', @@ -187,6 +186,7 @@ const sidebars: SidebarsConfig = { 'toolhive/guides-vmcp/telemetry-and-metrics', 'toolhive/guides-vmcp/audit-logging', 'toolhive/guides-vmcp/scaling-and-performance', + 'toolhive/guides-vmcp/local-cli', ], }, From 017a53e7e11abe532ce6a7ef803f9244f87383ed Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Wed, 22 Apr 2026 13:20:49 -0400 Subject: [PATCH 8/8] Fix formatting Signed-off-by: Dan Barr <6922515+danbarr@users.noreply.github.com> --- docs/toolhive/guides-vmcp/index.mdx | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/toolhive/guides-vmcp/index.mdx b/docs/toolhive/guides-vmcp/index.mdx index 6a6fdf29..176294b9 100644 --- a/docs/toolhive/guides-vmcp/index.mdx +++ b/docs/toolhive/guides-vmcp/index.mdx @@ -21,9 +21,8 @@ connection. first vMCP through the Kubernetes operator. - **Already running vMCP?** Jump to [Configuration](./configuration.mdx) or [Authentication](./authentication.mdx). -- **Local testing only?** Run - [vMCP locally with the CLI](./local-cli.mdx) to aggregate a local ToolHive - group without a cluster. +- **Local testing only?** Run [vMCP locally with the CLI](./local-cli.mdx) to + aggregate a local ToolHive group without a cluster. ## Contents