Add local mode guide for thv vmcp CLI commands - #787
Conversation
Documents running Virtual MCP Server locally without Kubernetes using `thv vmcp serve`, `thv vmcp init`, and `thv vmcp validate`. Covers quick mode (zero-config, single flag), config file mode, and all major config sections: backends, conflict resolution, incoming/outgoing auth, optimizer tiers, composite tools, and Redis session storage. Includes full CLI flag reference for all three subcommands. Updates the vMCP index page to surface the local mode option and adds the new page to the sidebar after the Kubernetes quickstart.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
There was a problem hiding this comment.
Pull request overview
Adds a new vMCP documentation page describing how to run Virtual MCP Server locally via thv vmcp (serve/init/validate), and updates vMCP navigation to surface this “local mode” path alongside the existing Kubernetes quickstart.
Changes:
- Add a new “Run vMCP locally with the CLI” guide covering quick mode, config mode, and config sections.
- Update the vMCP index page to link to the new local-mode guide.
- Add the new page to the Virtual MCP Server sidebar section after the Kubernetes quickstart.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
| sidebars.ts | Adds the new local-mode guide to the vMCP sidebar ordering. |
| docs/toolhive/guides-vmcp/local-mode.mdx | New local-mode (CLI) guide and config/flag reference content. |
| docs/toolhive/guides-vmcp/index.mdx | Updates the “Where to start” section to include the local-mode option. |
| ``` | ||
|
|
||
| This starts a vMCP server on `127.0.0.1:4483` that aggregates all servers in the | ||
| group `my-group`. The server is accessible only from localhost — quick mode does |
There was a problem hiding this comment.
Avoid using em dashes (—) in docs per repo writing guidelines. Rephrase this sentence using commas/parentheses or split into two sentences.
| group `my-group`. The server is accessible only from localhost — quick mode does | |
| group `my-group`. The server is accessible only from localhost. Quick mode does |
| tokens sent to the LLM on each request and improves tool selection across many | ||
| backends. | ||
|
|
||
| **Tier 1 — keyword search** (no extra dependencies): |
There was a problem hiding this comment.
Avoid using em dashes (—) in headings; the writing guidelines recommend rephrasing or using a hyphenated alternative.
| **Tier 1 — keyword search** (no extra dependencies): | |
| **Tier 1 - keyword search** (no extra dependencies): |
| optimizer: {} | ||
| ``` | ||
|
|
||
| **Tier 2 — semantic search** (requires Docker; starts a TEI container |
There was a problem hiding this comment.
Avoid using em dashes (—) in headings; the writing guidelines recommend rephrasing or using a hyphenated alternative.
| **Tier 2 — semantic search** (requires Docker; starts a TEI container | |
| **Tier 2 - semantic search** (requires Docker; starts a TEI container |
| request. Set `insecureAllowHttp: true` and `jwksAllowPrivateIp: true` only when | ||
| testing against a local OIDC server. | ||
|
|
||
| For the full set of OIDC fields see [Authentication](./authentication.mdx). |
There was a problem hiding this comment.
This says the Authentication page contains the full set of OIDC fields, but that page documents the Kubernetes CRD flow and does not describe the CLI config keys mentioned here (e.g., insecureAllowHttp, jwksAllowPrivateIp). Update the link text or add a dedicated reference for the CLI config fields so readers aren’t sent to a page that doesn’t cover them.
| For the full set of OIDC fields see [Authentication](./authentication.mdx). | |
| For general vMCP authentication and Kubernetes-based OIDC configuration, see | |
| [Authentication](./authentication.mdx). The local CLI configuration supports the | |
| fields shown above, including the local-testing flags. |
| ## thv vmcp validate reference | ||
|
|
||
| ``` | ||
| Usage: | ||
| thv vmcp validate [flags] | ||
|
|
||
| Flags: | ||
| -c, --config string Path to vMCP configuration file (required) | ||
| -h, --help Help for validate | ||
| ``` |
There was a problem hiding this comment.
This page is a how-to guide but it ends without a "Next steps" section. The repo’s doc standards require 1–3 links to the next logical pages so readers know where to go next (for example: Configuration, Authentication, or Optimize tool discovery).
|
Closing as superseded (if needed we can file a follow up) |
Description
Documents running Virtual MCP Server locally without Kubernetes using
thv vmcp serve,thv vmcp init, andthv vmcp validate. Covers quick mode (zero-config, single flag), config file mode, and all major config sections: backends, conflict resolution, incoming/outgoing auth, optimizer tiers, composite tools, and Redis session storage. Includes full CLI flag reference for all three subcommands.Updates the vMCP index page to surface the local mode option and adds the new page to the sidebar after the Kubernetes quickstart.
Type of change
Related issues/PRs
Screenshots
Submitter checklist
Content and formatting
Navigation
sidebars.ts) updated for added, deleted, reordered, or renamed filesvercel.jsonfor moved, renamed, or deleted pages (i.e., if the URL slug changed)Reviewer checklist
Content