From 24396bbee49d6f0b143f20cfadc80b6c51484d86 Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Wed, 22 Apr 2026 19:05:18 -0400 Subject: [PATCH 01/10] Clarify ToolHive platform overview --- docs/toolhive/guides-cli/index.mdx | 6 ++- docs/toolhive/guides-k8s/index.mdx | 3 ++ docs/toolhive/guides-registry/index.mdx | 5 ++ docs/toolhive/guides-ui/index.mdx | 5 +- docs/toolhive/guides-vmcp/index.mdx | 6 ++- docs/toolhive/index.mdx | 70 +++++++++++++++---------- 6 files changed, 62 insertions(+), 33 deletions(-) diff --git a/docs/toolhive/guides-cli/index.mdx b/docs/toolhive/guides-cli/index.mdx index ddbcade7..17e656b7 100644 --- a/docs/toolhive/guides-cli/index.mdx +++ b/docs/toolhive/guides-cli/index.mdx @@ -15,7 +15,9 @@ provides quick deployment of MCP servers and supports advanced features like custom permissions, network access filtering, and telemetry. It's designed for developers who prefer working in a terminal or need to -integrate MCP server management into scripts or automation workflows. +integrate MCP server management into scripts or automation workflows. If you +want a terminal-first way to run ToolHive locally or embed it in automation, +start here. :::info[Using ToolHive UI?] @@ -32,6 +34,8 @@ both installed. `thv` and run your first MCP server in minutes. - **Already installed?** Jump to [Run MCP servers](./run-mcp-servers.mdx) to start managing servers from the command line. +- **Want to browse the default catalog?** See + [Browse the built-in registry](./registry.mdx). - **Managing agent skills?** See [Manage agent skills](./skills-management.mdx) to install and publish reusable skills. - **Building or automating?** See advanced workflows for [auth](./auth.mdx), diff --git a/docs/toolhive/guides-k8s/index.mdx b/docs/toolhive/guides-k8s/index.mdx index d8aea8db..6a2c80a1 100644 --- a/docs/toolhive/guides-k8s/index.mdx +++ b/docs/toolhive/guides-k8s/index.mdx @@ -26,6 +26,9 @@ Beyond managing MCP servers, the operator can deploy MCPRegistry resources, enabling automatic discovery of cluster-hosted MCP servers. +This is the best starting point when you need ToolHive in a shared, multi-user, +or production-style Kubernetes environment. + ## Where to start - **New to ToolHive on Kubernetes?** Start with the diff --git a/docs/toolhive/guides-registry/index.mdx b/docs/toolhive/guides-registry/index.mdx index b25506e3..9daf8977 100644 --- a/docs/toolhive/guides-registry/index.mdx +++ b/docs/toolhive/guides-registry/index.mdx @@ -24,6 +24,11 @@ yourself. Looking for the built-in registry instead? See ::: +Use the Registry Server when you need to host your own MCP catalog, aggregate +multiple sources, or apply your own authentication and authorization controls. +If you only need to browse the default ToolHive catalog from the UI or CLI, you +do not need to deploy the Registry Server. + ## Where to start - **New to the Registry Server?** Follow the diff --git a/docs/toolhive/guides-ui/index.mdx b/docs/toolhive/guides-ui/index.mdx index a61dcc47..ee3088a0 100644 --- a/docs/toolhive/guides-ui/index.mdx +++ b/docs/toolhive/guides-ui/index.mdx @@ -19,7 +19,8 @@ security and ease of use built in. It's designed for anyone who wants to run MCP servers without needing to understand the complexities of Docker or command-line tools. Whether you're a developer, researcher, or just curious about MCP servers, ToolHive provides a -simple way to get started. +simple way to get started. If you want the lowest-friction first run with +ToolHive on your local machine, start here. - # What is ToolHive? ToolHive is an enterprise-grade open source (Apache 2.0) platform for running @@ -80,6 +65,45 @@ ToolHive Operator. +## ToolHive platform overview + +ToolHive is a platform for running, discovering, securing, and operating MCP +servers. The docs are organized by the part of the platform you're working with, +not just by deployment target. + +- [**ToolHive UI**](./guides-ui/index.mdx), + [**ToolHive CLI**](./guides-cli/index.mdx), and the + [**ToolHive Kubernetes Operator**](./guides-k8s/index.mdx) are the main ways + to run ToolHive. Choose the UI for the lowest-friction local start, the CLI + for terminal-first workflows and automation, or Kubernetes for shared, + multi-user environments. +- [**Virtual MCP Server (vMCP)**](./guides-vmcp/index.mdx) is ToolHive's MCP + gateway. It runs as part of the Kubernetes Operator for cluster deployments, + with a separate local CLI path for testing and evaluation. +- [**ToolHive Registry Server**](./guides-registry/index.mdx) is ToolHive's + registry component for hosting and curating your own catalog of MCP servers or + skills, with its own API and access controls. It can be deployed standalone or + as part of a broader ToolHive platform deployment. +- The **built-in registry** is the default catalog used by the ToolHive UI and + CLI to browse and install MCP servers. It is different from the Registry + Server that you deploy yourself. + +**Choose vMCP if** you need one endpoint that aggregates multiple backend MCP +servers with centralized authentication, routing, or tool optimization. + +**Choose Registry Server if** you need to host and curate your own MCP catalog +instead of browsing the default built-in registry. + +:::enterprise + +Stacklok Enterprise builds on ToolHive with centralized management, identity +provider integrations, hardened images, and platform capabilities for teams +running MCP in production. + +[Learn more about Stacklok Enterprise](./enterprise.mdx) + +::: + ## ToolHive components ToolHive includes everything you need to use MCP servers in production. It's @@ -230,17 +254,5 @@ effectively: Join the Stacklok [Discord community](https://discord.gg/stacklok) to connect with other ToolHive users, ask questions, and share your experiences. -Source code and issue tracking: - -- ToolHive CLI & K8s Operator - - [GitHub repository](https://github.com/stacklok/toolhive) - - [Issue tracker](https://github.com/stacklok/toolhive/issues) -- ToolHive UI - - [GitHub repository](https://github.com/stacklok/toolhive-studio) - - [Issue tracker](https://github.com/stacklok/toolhive-studio/issues) -- ToolHive Registry Server - - [GitHub repository](https://github.com/stacklok/toolhive-registry-server) - - [Issue tracker](https://github.com/stacklok/toolhive-registry-server/issues) -- ToolHive Cloud UI (experimental) - - [GitHub repository](https://github.com/stacklok/toolhive-cloud-ui) - - [Issue tracker](https://github.com/stacklok/toolhive-cloud-ui/issues) +Looking for source code, issue trackers, or contribution guidance? See +[Contributing](./contributing.mdx). From e4538f60a49e4712c561498ae7040bc5a889f79e Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Wed, 22 Apr 2026 19:05:40 -0400 Subject: [PATCH 02/10] Refine docs navigation --- docusaurus.config.ts | 6 +----- sidebars.ts | 49 +++++++++++++++++++++++++++++++++++++++++--- src/css/custom.css | 15 ++++++++++++++ 3 files changed, 62 insertions(+), 8 deletions(-) diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 0387efdb..323c8284 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -241,7 +241,7 @@ const config: Config = { docs: { sidebar: { hideable: false, - autoCollapseCategories: false, + autoCollapseCategories: true, }, }, navbar: { @@ -260,10 +260,6 @@ const config: Config = { label: 'Home', href: '/toolhive', }, - { - label: 'Integrations', - to: 'toolhive/integrations', - }, { label: 'ToolHive UI', to: 'toolhive/guides-ui', diff --git a/sidebars.ts b/sidebars.ts index 089d8ee7..b835a26c 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -21,6 +21,12 @@ const crdSidebar = crdSidebarJson as SidebarItemConfig; const sidebars: SidebarsConfig = { toolhiveSidebar: [ 'toolhive/index', + { + type: 'html', + value: 'Run ToolHive', + className: 'sidebar-title', + defaultStyle: false, + }, { type: 'category', @@ -168,6 +174,13 @@ const sidebars: SidebarsConfig = { ], }, + { + type: 'html', + value: 'Platform services', + className: 'sidebar-title', + defaultStyle: false, + }, + { type: 'category', label: 'Virtual MCP Server', @@ -233,6 +246,13 @@ const sidebars: SidebarsConfig = { ], }, + { + type: 'html', + value: 'Shared guides', + className: 'sidebar-title', + defaultStyle: false, + }, + { type: 'category', label: 'Concepts', @@ -308,9 +328,32 @@ const sidebars: SidebarsConfig = { items: [{ type: 'autogenerated', dirName: 'toolhive/guides-mcp' }], }, - 'toolhive/reference/client-compatibility', - 'toolhive/reference/index', - 'toolhive/reference/authz-policy-reference', + { + type: 'html', + value: 'Reference', + className: 'sidebar-title', + defaultStyle: false, + }, + { + type: 'category', + label: 'Technical reference', + link: { + type: 'doc', + id: 'toolhive/reference/index', + }, + collapsible: false, + collapsed: false, + items: [ + 'toolhive/reference/client-compatibility', + 'toolhive/reference/authz-policy-reference', + ], + }, + { + type: 'html', + value: 'Help', + className: 'sidebar-title', + defaultStyle: false, + }, 'toolhive/faq', 'toolhive/enterprise', 'toolhive/support', diff --git a/src/css/custom.css b/src/css/custom.css index 151fab84..2cbb2de0 100644 --- a/src/css/custom.css +++ b/src/css/custom.css @@ -201,6 +201,21 @@ thead th { color: var(--stacklok-cookie); } +.theme-doc-sidebar-menu .sidebar-title { + margin: 1.35rem 0 0.4rem; + padding: 0 0.75rem; + color: var(--stacklok-sunset); + font-size: 0.72rem; + font-weight: 700; + letter-spacing: 0.08em; + text-transform: uppercase; + pointer-events: none; +} + +html[data-theme='dark'] .theme-doc-sidebar-menu .sidebar-title { + color: var(--stacklok-green-grass); +} + [data-theme='dark'] .pagination-nav__link { background-color: rgba(255, 255, 255, 0.08); } From 0af4cfb4fde7dec0c7040ba6f0d90380d7d14976 Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Wed, 22 Apr 2026 19:06:00 -0400 Subject: [PATCH 03/10] Tighten onboarding quickstarts --- docs/toolhive/guides-cli/quickstart.mdx | 102 ++++++++++++----------- docs/toolhive/guides-cli/registry.mdx | 2 +- docs/toolhive/guides-k8s/quickstart.mdx | 7 +- docs/toolhive/guides-ui/quickstart.mdx | 11 ++- docs/toolhive/guides-ui/registry.mdx | 2 +- docs/toolhive/guides-vmcp/quickstart.mdx | 19 +++-- 6 files changed, 84 insertions(+), 59 deletions(-) diff --git a/docs/toolhive/guides-cli/quickstart.mdx b/docs/toolhive/guides-cli/quickstart.mdx index 0af0e6aa..d355867b 100644 --- a/docs/toolhive/guides-cli/quickstart.mdx +++ b/docs/toolhive/guides-cli/quickstart.mdx @@ -16,7 +16,7 @@ or Cursor. - How to find available MCP servers - How to run an MCP server - How to verify the server is working -- How to use the server with an AI client application +- How to optionally use the server with an AI client application ## Prerequisites @@ -25,8 +25,9 @@ Before starting this tutorial, make sure you have: - [Docker](https://docs.docker.com/get-docker/) or [Podman](https://podman-desktop.io/downloads) or [Colima](https://github.com/abiosoft/colima) installed and running -- A [supported MCP client](../reference/client-compatibility.mdx) like GitHub - Copilot in VS Code, Cursor, Claude Code, and more +- An optional [supported MCP client](../reference/client-compatibility.mdx) like + GitHub Copilot in VS Code, Cursor, Claude Code, and more if you want to test + end-to-end client integration ## Step 1: Install ToolHive @@ -92,44 +93,7 @@ Platform: darwin/arm64 This confirms ToolHive is installed and ready to use. -## Step 2: Register your client - -Next, run the ToolHive client setup command to register your MCP client: - -```bash -thv client setup -``` - -Select one or more clients from the list using the spacebar to toggle selection. -Press Enter to confirm your selection. - -:::info[What's happening?] - -When you run the setup command, ToolHive automatically finds -[supported clients](../reference/client-compatibility.mdx) on your system. When -you register a client, ToolHive automatically configures it to use MCP servers -that you run. This means you don't have to manually configure the client to -connect to the MCP server. - -::: - -Confirm that your client is registered successfully: - -```bash -thv client status -``` - -You should see output similar to this: - -```text -┌────────────────┬───────────┬────────────┐ -│ CLIENT TYPE │ INSTALLED │ REGISTERED │ -├────────────────┼───────────┼────────────┤ -│ vscode │ ✅ Yes │ ❌ No │ -└────────────────┴───────────┴────────────┘ -``` - -## Step 3: Find an MCP server to run +## Step 2: Find an MCP server to run See what MCP servers are available in the registry: @@ -153,8 +117,8 @@ This shows all the MCP servers available in the ToolHive registry. :::info[What's happening?] ToolHive maintains a curated registry of MCP servers that have been verified to -work correctly. The registry includes information about what each server does -and how to use it. +work correctly. This built-in registry is the default catalog that the CLI uses +to help you find and launch servers. ::: @@ -169,7 +133,7 @@ thv registry info fetch This shows you detailed information about the server, including what tools it provides and any configuration options. -## Step 4: Run the Fetch MCP server +## Step 3: Run the Fetch MCP server Now, run the Fetch server: @@ -208,7 +172,7 @@ When you run an MCP server, ToolHive: ::: -## Step 5: Verify the server is running +## Step 4: Verify the server is running Check that the server is running: @@ -233,6 +197,43 @@ running and how they're configured. ::: +## Step 5: Optionally connect an AI client + +If you want ToolHive to configure a supported MCP client for you, register it +now: + +```bash +thv client setup +``` + +Select one or more clients from the list using the spacebar to toggle selection. +Press Enter to confirm your selection. + +Confirm that your client is registered successfully: + +```bash +thv client status +``` + +You should see output similar to this: + +```text +┌────────────────┬───────────┬────────────┐ +│ CLIENT TYPE │ INSTALLED │ REGISTERED │ +├────────────────┼───────────┼────────────┤ +│ vscode │ ✅ Yes │ ✅ Yes │ +└────────────────┴───────────┴────────────┘ +``` + +:::info[What's happening?] + +When you run the setup command, ToolHive automatically finds +[supported clients](../reference/client-compatibility.mdx) on your system. When +you register a client, ToolHive automatically configures it to use MCP servers +that you run. + +::: + ## Step 6: Use the MCP server with your AI client Now that your MCP server is running, you can use it with your AI client @@ -279,12 +280,12 @@ the container, freeing up resources. ::: -## What's next? +## Next steps Congratulations! You've successfully installed ToolHive and run your first MCP server. Here are some next steps to explore: -- Try running other MCP servers from the registry with +- Try running other MCP servers from the built-in registry with [`thv registry list`](../reference/cli/thv_registry_list.md) and [`thv run`](../reference/cli/thv_run.md) - Learn about [secrets management](../guides-cli/secrets-management.mdx) for MCP @@ -309,6 +310,11 @@ production-ready MCP servers, that's where Stacklok Enterprise comes in. ::: +## Related information + +- [Browse the built-in registry](../guides-cli/registry.mdx) +- [Client compatibility](../reference/client-compatibility.mdx) + ## Troubleshooting
@@ -333,7 +339,7 @@ thv run --proxy-port 8081 fetch If your AI client application can't use the server: -- Make sure your client is registered with ToolHive (see Step 2) +- Make sure your client is registered with ToolHive (see Step 5) - Check that your client is supported - Restart your client to pick up the new configuration - Verify the server is running with [`thv list`](../reference/cli/thv_list.md) diff --git a/docs/toolhive/guides-cli/registry.mdx b/docs/toolhive/guides-cli/registry.mdx index b85bdf38..2713512b 100644 --- a/docs/toolhive/guides-cli/registry.mdx +++ b/docs/toolhive/guides-cli/registry.mdx @@ -1,5 +1,5 @@ --- -title: Explore the registry +title: Use the registry description: Search the built-in registry to find, inspect, and run MCP servers with one command. diff --git a/docs/toolhive/guides-k8s/quickstart.mdx b/docs/toolhive/guides-k8s/quickstart.mdx index e137401e..631df6ab 100644 --- a/docs/toolhive/guides-k8s/quickstart.mdx +++ b/docs/toolhive/guides-k8s/quickstart.mdx @@ -426,7 +426,7 @@ This will fully remove the kind cluster and clean up all associated resources. ::: -## What's next? +## Next steps Congratulations! You've successfully deployed the ToolHive operator and created your first MCP server using Kubernetes resources. You now have a working @@ -454,6 +454,11 @@ support - built for teams taking MCP from proof of concept to production. ::: +## Related information + +- [Connect clients to MCP servers](../guides-k8s/connect-clients.mdx) +- [Run MCP servers in Kubernetes](../guides-k8s/run-mcp-k8s.mdx) + ## Troubleshooting
diff --git a/docs/toolhive/guides-ui/quickstart.mdx b/docs/toolhive/guides-ui/quickstart.mdx index 4bf8c363..c6a212ea 100644 --- a/docs/toolhive/guides-ui/quickstart.mdx +++ b/docs/toolhive/guides-ui/quickstart.mdx @@ -51,7 +51,7 @@ For more detailed installation instructions, see the On the initial splash screen, click **Browse registry**, or open the **Registry** page from the top menu bar. This page lists the MCP servers in -ToolHive's built-in registry. +ToolHive's built-in registry, the default catalog that ships with the UI. :::info[What is this?] @@ -119,7 +119,7 @@ specified, then receives and processes the webpage content to create a summary. ::: -## What's next? +## Next steps Congratulations! You've successfully installed ToolHive and run your first MCP server. Here are some next steps to explore: @@ -127,7 +127,7 @@ server. Here are some next steps to explore: - Learn more about MCP concepts in the [MCP primer guide](../concepts/mcp-primer.mdx) - Try [running more MCP servers](../guides-ui/run-mcp-servers.mdx) from the - registry or from custom sources + built-in registry or from custom sources - Learn about [secrets management](../guides-ui/secrets-management.mdx) for MCP servers that require authentication - Learn how to @@ -143,6 +143,11 @@ integration, and hardened images for teams deploying MCP at scale. ::: +## Related information + +- [Browse the built-in registry](../guides-ui/registry.mdx) +- [Client compatibility](../reference/client-compatibility.mdx) + ## Troubleshooting
diff --git a/docs/toolhive/guides-ui/registry.mdx b/docs/toolhive/guides-ui/registry.mdx index f21b0341..ff685939 100644 --- a/docs/toolhive/guides-ui/registry.mdx +++ b/docs/toolhive/guides-ui/registry.mdx @@ -1,5 +1,5 @@ --- -title: Explore the registry +title: Use the registry description: Search built-in or custom registries to find and install MCP servers in the ToolHive desktop app. diff --git a/docs/toolhive/guides-vmcp/quickstart.mdx b/docs/toolhive/guides-vmcp/quickstart.mdx index 2a441d3a..a471363a 100644 --- a/docs/toolhive/guides-vmcp/quickstart.mdx +++ b/docs/toolhive/guides-vmcp/quickstart.mdx @@ -25,7 +25,8 @@ Before starting this tutorial, make sure you have: - A Kubernetes cluster with the ToolHive operator installed (see [Quickstart: Kubernetes Operator](../guides-k8s/quickstart.mdx)) - `kubectl` configured to communicate with your cluster -- An MCP client (Visual Studio Code with Copilot is used in this tutorial) +- An MCP client. Visual Studio Code with GitHub Copilot is used in this + tutorial, but any client that supports remote HTTP MCP servers will work. ## Step 1: Create an MCPGroup @@ -209,7 +210,8 @@ curl http://localhost:4483/health You should see `{"status":"ok"}`. -Add the port-forwarded vMCP endpoint as a remote server in ToolHive: +To have ToolHive manage the vMCP connection and configure your clients for you, +add the port-forwarded endpoint as a remote server with the ToolHive CLI: ```bash thv run http://localhost:4483/mcp --name demo-vmcp @@ -220,6 +222,10 @@ automatically configures your registered MCP clients to connect to it. :::tip +If you're using the ToolHive UI instead, add the same endpoint as a remote MCP +server from the app. For more details, see +[Run MCP servers](../guides-ui/run-mcp-servers.mdx). + If you haven't set up client configuration yet, run `thv client setup` to register your MCP clients. See [Client configuration](../guides-cli/client-configuration.mdx) for more details. @@ -241,18 +247,21 @@ kubectl delete mcpserver fetch osv -n toolhive-system kubectl delete mcpgroup demo-tools -n toolhive-system ``` -## What's next? +## Next steps Congratulations! You've successfully deployed vMCP and aggregated multiple backends into a single endpoint. -Next steps: - - [Configure authentication](../guides-vmcp/authentication.mdx) for production - [Customize tool aggregation](../guides-vmcp/tool-aggregation.mdx) with filtering and overrides - [Understanding Virtual MCP Server](../concepts/vmcp.mdx) +## Related information + +- [Run vMCP locally with the CLI](../guides-vmcp/local-cli.mdx) +- [Client compatibility](../reference/client-compatibility.mdx) + ## Troubleshooting
From 7f0afa4404f3f939da57853a35d0371ef41cb54a Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Thu, 23 Apr 2026 11:12:26 -0400 Subject: [PATCH 04/10] Strengthen platform positioning --- docs/toolhive/guides-cli/index.mdx | 22 ++++++++------ docs/toolhive/guides-k8s/index.mdx | 17 ++++++----- docs/toolhive/guides-registry/index.mdx | 24 ++++++++------- docs/toolhive/guides-registry/intro.mdx | 40 +++++++++++++++++-------- docs/toolhive/guides-ui/index.mdx | 22 +++++++------- docs/toolhive/guides-vmcp/index.mdx | 12 +++++--- docs/toolhive/index.mdx | 19 ++++++------ 7 files changed, 94 insertions(+), 62 deletions(-) diff --git a/docs/toolhive/guides-cli/index.mdx b/docs/toolhive/guides-cli/index.mdx index 17e656b7..aa217948 100644 --- a/docs/toolhive/guides-cli/index.mdx +++ b/docs/toolhive/guides-cli/index.mdx @@ -9,15 +9,19 @@ import DocCardList from '@theme/DocCardList'; ## Introduction -The ToolHive CLI (`thv`) is a command-line tool that allows you to deploy and -manage MCP servers on your local machine or in development environments. It -provides quick deployment of MCP servers and supports advanced features like -custom permissions, network access filtering, and telemetry. - -It's designed for developers who prefer working in a terminal or need to -integrate MCP server management into scripts or automation workflows. If you -want a terminal-first way to run ToolHive locally or embed it in automation, -start here. +The ToolHive CLI (`thv`) gives you a fast, repeatable way to run and manage MCP +servers from the terminal. Use it when you want to script server setup, control +permissions precisely, work in development environments, or automate ToolHive +workflows in shell scripts and CI. + +Within the ToolHive platform, the CLI gives you direct access to the same local +runtime, built-in registry, and client-configuration workflows that power the +UI. If you want a terminal-first way to run ToolHive locally or embed it in +automation, start here. + +The CLI can also connect your local workflows and AI clients to the broader +ToolHive platform. You can use it with MCP servers or gateways managed by the +Kubernetes Operator, and point local workflows at a ToolHive Registry Server. :::info[Using ToolHive UI?] diff --git a/docs/toolhive/guides-k8s/index.mdx b/docs/toolhive/guides-k8s/index.mdx index 6a2c80a1..a740ec44 100644 --- a/docs/toolhive/guides-k8s/index.mdx +++ b/docs/toolhive/guides-k8s/index.mdx @@ -9,8 +9,16 @@ import DocCardList from '@theme/DocCardList'; ## Introduction -The ToolHive Kubernetes Operator manages MCP servers in Kubernetes clusters. You -define MCP servers as Kubernetes custom resources and the operator automates +The ToolHive Kubernetes Operator brings MCP servers into a shared, governable +Kubernetes environment. It solves the gap between trying MCP locally and running +it for teams, with standard deployment workflows, centralized policy control, +and platform-managed connectivity. + +Within the ToolHive platform, the operator is the foundation for multi-user and +production-style deployments. It runs MCP workloads in the cluster and unlocks +capabilities like Virtual MCP Server (vMCP) and Registry Server integrations. + +You define MCP servers as Kubernetes custom resources and the operator automates their deployment, proxying, and lifecycle management. The operator supports several primary resource types: @@ -21,11 +29,6 @@ several primary resource types: - **VirtualMCPServer**: aggregate and optimize multiple servers behind a single endpoint -Beyond managing MCP servers, the operator can deploy -[ToolHive Registry Server](../guides-registry/index.mdx) instances via -MCPRegistry resources, enabling automatic discovery of cluster-hosted MCP -servers. - This is the best starting point when you need ToolHive in a shared, multi-user, or production-style Kubernetes environment. diff --git a/docs/toolhive/guides-registry/index.mdx b/docs/toolhive/guides-registry/index.mdx index 9daf8977..3209da8d 100644 --- a/docs/toolhive/guides-registry/index.mdx +++ b/docs/toolhive/guides-registry/index.mdx @@ -9,25 +9,27 @@ import DocCardList from '@theme/DocCardList'; ## Introduction -The ToolHive Registry Server is an implementation of the official -[Model Context Protocol (MCP) Registry API specification](https://github.com/modelcontextprotocol/registry/blob/main/docs/reference/api/generic-registry-api.md). -It provides a standardized REST API for discovering and accessing MCP servers -from multiple backend sources, including Kubernetes clusters, Git repositories, -API endpoints, and local files. +The ToolHive Registry Server helps you publish and govern a catalog of MCP +servers or skills for your team. Use it when you want a trusted catalog that +improves discoverability, supports publishing workflows, and gives you more +control over what different users can access. + +It can aggregate entries from Kubernetes clusters, Git repositories, API +endpoints, and local files, then expose them through a standard MCP Registry API +for ToolHive and other clients. :::note This section covers the **Registry Server**, a standalone service you deploy yourself. Looking for the built-in registry instead? See -[Explore the registry](../guides-cli/registry.mdx) (CLI) or -[Explore the registry](../guides-ui/registry.mdx) (UI). +[Use the registry](../guides-cli/registry.mdx) (CLI) or +[Use the registry](../guides-ui/registry.mdx) (UI). ::: -Use the Registry Server when you need to host your own MCP catalog, aggregate -multiple sources, or apply your own authentication and authorization controls. -If you only need to browse the default ToolHive catalog from the UI or CLI, you -do not need to deploy the Registry Server. +If you want to host and operate your own catalog, use the Registry Server. If +you only need to browse the default ToolHive catalog from the UI or CLI, you do +not need to deploy it. ## Where to start diff --git a/docs/toolhive/guides-registry/intro.mdx b/docs/toolhive/guides-registry/intro.mdx index 6a65173b..d9d815fa 100644 --- a/docs/toolhive/guides-registry/intro.mdx +++ b/docs/toolhive/guides-registry/intro.mdx @@ -5,22 +5,37 @@ description: Server --- -The ToolHive Registry Server is a standards-compliant implementation of the MCP -Registry API specification. It provides a REST API for discovering and accessing -MCP servers from multiple backend sources. +The ToolHive Registry Server gives you a way to publish, curate, and control a +catalog of MCP servers and skills for your organization. Use it when you want a +trusted catalog for discoverability, team-scoped access, publishing, or +multi-source aggregation. + +It pulls entries from multiple sources, stores them centrally, and exposes them +through a standard MCP Registry API that ToolHive and other clients can consume. :::note[Registry Server vs. built-in registry] -This section covers the **Registry Server**, a standalone service you deploy -yourself for hosting and curating your own MCP server catalog. +This section covers the **Registry Server** for hosting and curating your own +MCP server and skills catalog. ToolHive also ships with a **built-in registry** for browsing and discovering MCP servers from the default catalog. That's a different feature: see -[Explore the registry](../guides-cli/registry.mdx) (CLI) or -[Explore the registry](../guides-ui/registry.mdx) (UI). +[Use the registry](../guides-cli/registry.mdx) (CLI) or +[Use the registry](../guides-ui/registry.mdx) (UI). ::: +## Why use the Registry Server? + +Use the Registry Server when you need to: + +- Curate a private or team-specific catalog instead of relying only on the + default public catalog +- Publish MCP servers or [skills](../concepts/skills.mdx) for internal use +- Aggregate entries from multiple sources behind one registry API +- Apply authentication and authorization policies to registry access +- Surface cluster-hosted workloads to users through a managed catalog + ## Key concepts The Registry Server is built around three core concepts: @@ -38,8 +53,9 @@ The Registry Server is built around three core concepts: ## How the Registry Server works -The Registry server aggregates MCP server metadata from various sources and -exposes it through a standardized API. When you start the server, it: +The Registry Server aggregates MCP server and skills metadata from various +sources and exposes it through a standardized API. When you start the server, +it: 1. Loads configuration from a YAML file 2. Runs database migrations automatically @@ -129,9 +145,9 @@ The server supports five source types: ## Registry Server and the rest of ToolHive -The Registry Server is a standalone service. It is separate from the built-in -catalog that the ToolHive CLI and UI ship with for browsing public MCP servers. -The pieces work together: +The Registry Server is one part of the broader ToolHive platform. It is +different from the built-in catalog that the ToolHive CLI and UI ship with for +browsing public MCP servers, but the pieces work together: - The CLI's [`thv search`](../reference/cli/thv_search.md) and [`thv registry`](../guides-cli/registry.mdx) commands query the built-in diff --git a/docs/toolhive/guides-ui/index.mdx b/docs/toolhive/guides-ui/index.mdx index ee3088a0..dd6bc274 100644 --- a/docs/toolhive/guides-ui/index.mdx +++ b/docs/toolhive/guides-ui/index.mdx @@ -11,16 +11,18 @@ import ThemedImage from '@theme/ThemedImage'; ## Introduction -The ToolHive UI is a desktop application that makes it easy to run and manage -Model Context Protocol (MCP) servers on your local machine. It provides a -user-friendly interface to discover, deploy, and manage MCP servers with -security and ease of use built in. - -It's designed for anyone who wants to run MCP servers without needing to -understand the complexities of Docker or command-line tools. Whether you're a -developer, researcher, or just curious about MCP servers, ToolHive provides a -simple way to get started. If you want the lowest-friction first run with -ToolHive on your local machine, start here. +The ToolHive UI is the fastest way to get from zero to a working MCP setup on +your local machine. It helps you discover servers, run them securely, and +connect your AI clients without juggling Docker commands, config files, or +manual client setup. + +Within the ToolHive platform, the UI gives you a desktop portal for the same +local runtime and built-in registry that the CLI uses. If you want the +lowest-friction first run with ToolHive, start here. + +The UI can also connect your local AI clients to the broader ToolHive platform. +You can use it with MCP servers or gateways managed by the Kubernetes Operator, +and browse catalogs served by a ToolHive Registry Server. Date: Thu, 23 Apr 2026 11:55:59 -0400 Subject: [PATCH 05/10] Address review feedback --- docs/toolhive/guides-cli/index.mdx | 2 +- docs/toolhive/guides-cli/install.mdx | 2 +- docs/toolhive/guides-cli/quickstart.mdx | 18 +++++++++--------- docs/toolhive/guides-ui/quickstart.mdx | 2 +- docs/toolhive/index.mdx | 8 ++++---- docs/toolhive/tutorials/custom-registry.mdx | 2 +- 6 files changed, 17 insertions(+), 17 deletions(-) diff --git a/docs/toolhive/guides-cli/index.mdx b/docs/toolhive/guides-cli/index.mdx index aa217948..5286053f 100644 --- a/docs/toolhive/guides-cli/index.mdx +++ b/docs/toolhive/guides-cli/index.mdx @@ -39,7 +39,7 @@ both installed. - **Already installed?** Jump to [Run MCP servers](./run-mcp-servers.mdx) to start managing servers from the command line. - **Want to browse the default catalog?** See - [Browse the built-in registry](./registry.mdx). + [Use the registry](./registry.mdx). - **Managing agent skills?** See [Manage agent skills](./skills-management.mdx) to install and publish reusable skills. - **Building or automating?** See advanced workflows for [auth](./auth.mdx), diff --git a/docs/toolhive/guides-cli/install.mdx b/docs/toolhive/guides-cli/install.mdx index dd09b767..85d1518b 100644 --- a/docs/toolhive/guides-cli/install.mdx +++ b/docs/toolhive/guides-cli/install.mdx @@ -389,7 +389,7 @@ To uninstall ToolHive: ## Next steps Now that you have ToolHive installed, you can start using it to run and manage -MCP servers. See [Explore the registry](./registry.mdx) and +MCP servers. See [Use the registry](./registry.mdx) and [Run MCP servers](./run-mcp-servers.mdx) to get started. ## Related information diff --git a/docs/toolhive/guides-cli/quickstart.mdx b/docs/toolhive/guides-cli/quickstart.mdx index d355867b..511837fe 100644 --- a/docs/toolhive/guides-cli/quickstart.mdx +++ b/docs/toolhive/guides-cli/quickstart.mdx @@ -16,7 +16,7 @@ or Cursor. - How to find available MCP servers - How to run an MCP server - How to verify the server is working -- How to optionally use the server with an AI client application +- How to use the server with an AI client application ## Prerequisites @@ -25,9 +25,9 @@ Before starting this tutorial, make sure you have: - [Docker](https://docs.docker.com/get-docker/) or [Podman](https://podman-desktop.io/downloads) or [Colima](https://github.com/abiosoft/colima) installed and running -- An optional [supported MCP client](../reference/client-compatibility.mdx) like - GitHub Copilot in VS Code, Cursor, Claude Code, and more if you want to test - end-to-end client integration +- _(Optional)_ A [supported MCP client](../reference/client-compatibility.mdx) + like GitHub Copilot in VS Code, Cursor, Claude Code, and more if you want to + test end-to-end client integration ## Step 1: Install ToolHive @@ -197,10 +197,10 @@ running and how they're configured. ::: -## Step 5: Optionally connect an AI client +## Step 5: Connect an AI client -If you want ToolHive to configure a supported MCP client for you, register it -now: +To see the full payoff of the tutorial, have ToolHive configure a supported MCP +client for you now: ```bash thv client setup @@ -236,7 +236,7 @@ that you run. ## Step 6: Use the MCP server with your AI client -Now that your MCP server is running, you can use it with your AI client +If you completed Step 5, you can now use the MCP server with your AI client application. Open your supported client (VS Code, Cursor, etc.) and ask the AI to fetch content from a website. Note that you might need to restart your client for the changes to take effect. @@ -312,7 +312,7 @@ production-ready MCP servers, that's where Stacklok Enterprise comes in. ## Related information -- [Browse the built-in registry](../guides-cli/registry.mdx) +- [Use the registry](../guides-cli/registry.mdx) - [Client compatibility](../reference/client-compatibility.mdx) ## Troubleshooting diff --git a/docs/toolhive/guides-ui/quickstart.mdx b/docs/toolhive/guides-ui/quickstart.mdx index c6a212ea..0a1ff98a 100644 --- a/docs/toolhive/guides-ui/quickstart.mdx +++ b/docs/toolhive/guides-ui/quickstart.mdx @@ -145,7 +145,7 @@ integration, and hardened images for teams deploying MCP at scale. ## Related information -- [Browse the built-in registry](../guides-ui/registry.mdx) +- [Use the registry](../guides-ui/registry.mdx) - [Client compatibility](../reference/client-compatibility.mdx) ## Troubleshooting diff --git a/docs/toolhive/index.mdx b/docs/toolhive/index.mdx index f23d5f38..216e6d58 100644 --- a/docs/toolhive/index.mdx +++ b/docs/toolhive/index.mdx @@ -105,11 +105,11 @@ running MCP in production. ::: -## ToolHive components +## ToolHive architecture -ToolHive includes everything you need to use MCP servers in production. It's -made up of four key components: the Runtime, Registry Server, Gateway, and -Portal. +The platform overview above is the best place to choose where to start. This +section explains how those product surfaces map to the underlying ToolHive +architecture. From 9c1d38aa3fa54f3d87861e1914e614b444840f4b Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Thu, 23 Apr 2026 11:58:19 -0400 Subject: [PATCH 06/10] Polish onboarding copy --- docs/toolhive/guides-cli/quickstart.mdx | 4 ++-- docs/toolhive/guides-vmcp/index.mdx | 4 ++-- docs/toolhive/index.mdx | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/toolhive/guides-cli/quickstart.mdx b/docs/toolhive/guides-cli/quickstart.mdx index 511837fe..236267a1 100644 --- a/docs/toolhive/guides-cli/quickstart.mdx +++ b/docs/toolhive/guides-cli/quickstart.mdx @@ -26,8 +26,8 @@ Before starting this tutorial, make sure you have: [Podman](https://podman-desktop.io/downloads) or [Colima](https://github.com/abiosoft/colima) installed and running - _(Optional)_ A [supported MCP client](../reference/client-compatibility.mdx) - like GitHub Copilot in VS Code, Cursor, Claude Code, and more if you want to - test end-to-end client integration + such as GitHub Copilot in VS Code, Cursor, or Claude Code. Needed only if you + want to test end-to-end client integration. ## Step 1: Install ToolHive diff --git a/docs/toolhive/guides-vmcp/index.mdx b/docs/toolhive/guides-vmcp/index.mdx index 43067ad0..35fb90e5 100644 --- a/docs/toolhive/guides-vmcp/index.mdx +++ b/docs/toolhive/guides-vmcp/index.mdx @@ -17,8 +17,8 @@ tool access, centralized authentication, and multi-step workflows across multiple MCP backends. For cluster deployments, vMCP runs as part of the ToolHive Kubernetes Operator. -If you only want to evaluate aggregation locally, use the separate -[local CLI path](./local-cli.mdx). +If you only want to evaluate aggregation locally, see +[run vMCP locally with the CLI](./local-cli.mdx). ## Where to start diff --git a/docs/toolhive/index.mdx b/docs/toolhive/index.mdx index 216e6d58..1c4d74b3 100644 --- a/docs/toolhive/index.mdx +++ b/docs/toolhive/index.mdx @@ -2,8 +2,8 @@ title: Introduction hide_title: true description: - ToolHive runs and manages MCP servers with built-in security, available as a - desktop app, CLI, or Kubernetes operator. + ToolHive helps you run, govern, and connect MCP servers across the desktop + app, CLI, Kubernetes Operator, vMCP, and Registry Server. --- import useBaseUrl from '@docusaurus/useBaseUrl'; From e509b12b4e590350f74841ccbe6ad1a146cf8ef2 Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Thu, 23 Apr 2026 15:15:09 -0400 Subject: [PATCH 07/10] Rename platform capabilities section --- sidebars.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sidebars.ts b/sidebars.ts index b835a26c..aa1ae038 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -176,7 +176,7 @@ const sidebars: SidebarsConfig = { { type: 'html', - value: 'Platform services', + value: 'Platform capabilities', className: 'sidebar-title', defaultStyle: false, }, From 231ca29100dd1fd67c20a960a921b8d54a73a7fd Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Thu, 23 Apr 2026 15:17:46 -0400 Subject: [PATCH 08/10] Shorten reference nav labels --- sidebars.ts | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/sidebars.ts b/sidebars.ts index aa1ae038..6881a878 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -345,7 +345,11 @@ const sidebars: SidebarsConfig = { collapsed: false, items: [ 'toolhive/reference/client-compatibility', - 'toolhive/reference/authz-policy-reference', + { + type: 'doc', + id: 'toolhive/reference/authz-policy-reference', + label: 'Authorization policies', + }, ], }, { From e7f8b5130eef757c5840e9d362b4d1d69d22c8e4 Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Thu, 23 Apr 2026 15:21:26 -0400 Subject: [PATCH 09/10] Add authorization policies doc card --- docs/toolhive/reference/index.mdx | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/toolhive/reference/index.mdx b/docs/toolhive/reference/index.mdx index 5f0e8a6e..36227f5a 100644 --- a/docs/toolhive/reference/index.mdx +++ b/docs/toolhive/reference/index.mdx @@ -22,6 +22,16 @@ tutorials, see the individual product sections. }} /> + + Date: Thu, 23 Apr 2026 17:11:19 -0400 Subject: [PATCH 10/10] Add symlink from .claude/skills to .agent/skills --- .agents/skills | 1 + 1 file changed, 1 insertion(+) create mode 120000 .agents/skills diff --git a/.agents/skills b/.agents/skills new file mode 120000 index 00000000..454b8427 --- /dev/null +++ b/.agents/skills @@ -0,0 +1 @@ +../.claude/skills \ No newline at end of file