From 1e857bd8155208d7609ecaea07d05f879062609e Mon Sep 17 00:00:00 2001 From: Radoslav Dimitrov Date: Tue, 16 Sep 2025 14:26:47 +0300 Subject: [PATCH 01/11] Add docs for the group catalog Signed-off-by: Radoslav Dimitrov --- docs/toolhive/tutorials/custom-registry.mdx | 215 +++++++++++++++++++- 1 file changed, 209 insertions(+), 6 deletions(-) diff --git a/docs/toolhive/tutorials/custom-registry.mdx b/docs/toolhive/tutorials/custom-registry.mdx index 53c812bc..3360e5f6 100644 --- a/docs/toolhive/tutorials/custom-registry.mdx +++ b/docs/toolhive/tutorials/custom-registry.mdx @@ -80,11 +80,50 @@ Create a new file called `registry.json` and add the following content: } } } - } + }, + "groups": [ + { + "name": "dev-toolkit", + "description": "Essential MCP servers for development workflows", + "servers": { + "fetch-tool": { + "description": "A web content fetching MCP server for development", + "image": "ghcr.io/stackloklabs/gofetch/server:latest", + "status": "Active", + "tier": "Community", + "transport": "streamable-http", + "args": ["--user-agent", "Mozilla/5.0 (compatible;DevBot/1.0)"], + "tags": ["web", "fetch", "dev"], + "tools": ["fetch"], + "permissions": { + "network": { + "outbound": { + "allow_host": [".github.com", ".stackoverflow.com"], + "allow_port": [80, 443] + } + } + } + } + } + } + ] } ``` -This registry defines a single MCP server called `my-fetch` with: +This registry defines: + +- A single MCP server called `my-fetch` in the top-level `servers` section +- A group called `dev-toolkit` with its own independent server called + `fetch-tool` + +Groups are optional - you can omit the entire `groups` section if you only need +individual servers. Groups are independent entities that contain their own +complete server definitions. The `dev-toolkit` group includes a `fetch-tool` +server that's similar to the top-level `my-fetch` server but with different +configuration (different user agent, different allowed hosts for development +purposes). + +Each server definition includes: - A description explaining its purpose - The container image to use @@ -93,6 +132,9 @@ This registry defines a single MCP server called `my-fetch` with: - Command-line arguments for customization - Network permissions for security +Groups provide an organizational layer that allows you to run multiple related +servers together as a cohesive unit. + ### Step 2: Configure ToolHive to use your registry Configure ToolHive to use your custom registry. @@ -190,6 +232,15 @@ thv run my-fetch The server should start successfully, demonstrating that your custom registry is working correctly. +You can also run the entire group: + +```bash +thv group run dev-toolkit +``` + +This starts all servers in the `dev-toolkit` group (in this case, just the +`fetch-tool` server). + @@ -233,6 +284,156 @@ After updating the file, the new server is immediately available for ToolHive CLI commands. For the UI, navigate to the registry settings and click **Save** to see the new server listed. +## Working with groups + +Groups allow you to organize related MCP servers and run them together as a +cohesive unit. This is particularly useful for: + +- **Team-specific toolkits**: Create groups for different teams (frontend, + backend, DevOps) +- **Workflow-based organization**: Group servers needed for specific workflows + (testing, deployment, monitoring) +- **Environment-specific configurations**: Different server configurations for + development, staging, and production + +### Group structure + +Groups in your registry have the following structure: + +```json +{ + "groups": [ + { + "name": "group-name", + "description": "Description of what this group provides", + "servers": { + "server-name": { + // Complete server definition + } + }, + "remote_servers": { + "remote-server-name": { + // Complete remote server definition + } + } + } + ] +} +``` + +### Key characteristics of groups + +- **Independent server definitions**: Each group contains complete server + configurations, not references to top-level servers +- **Self-contained**: Groups can define servers with the same names as top-level + servers but with different configurations +- **Organizational only**: Groups provide organization but don't affect server + runtime behavior +- **Flexible membership**: Servers can appear in multiple groups with different + configurations + +### Example: Multi-group registry + +Here's a more comprehensive example showing how groups can organize servers for +different purposes: + +```json title='advanced-registry.json' +{ + "$schema": "https://raw.githubusercontent.com/stacklok/toolhive/main/pkg/registry/data/schema.json", + "version": "1.0.0", + "last_updated": "2025-08-15T10:00:00Z", + "servers": { + "production-fetch": { + "description": "Production web content fetching server", + "image": "ghcr.io/stackloklabs/gofetch/server:latest", + "status": "Active", + "tier": "Community", + "transport": "streamable-http", + "permissions": { + "network": { + "outbound": { + "allow_host": [".company.com"], + "allow_port": [443] + } + } + } + } + }, + "groups": [ + { + "name": "frontend-dev", + "description": "Tools for frontend development team", + "servers": { + "dev-fetch": { + "description": "Development web content fetching with broader access", + "image": "ghcr.io/stackloklabs/gofetch/server:latest", + "status": "Active", + "tier": "Community", + "transport": "streamable-http", + "permissions": { + "network": { + "outbound": { + "allow_host": ["*"], + "allow_port": [80, 443] + } + } + } + } + } + }, + { + "name": "testing-suite", + "description": "Servers needed for automated testing workflows", + "servers": { + "test-fetch": { + "description": "Restricted fetch server for testing", + "image": "ghcr.io/stackloklabs/gofetch/server:latest", + "status": "Active", + "tier": "Community", + "transport": "streamable-http", + "args": ["--timeout", "5s"], + "permissions": { + "network": { + "outbound": { + "allow_host": ["test.example.com"], + "allow_port": [443] + } + } + } + } + } + } + ] +} +``` + +This registry provides: + +- A production-ready `production-fetch` server at the top level +- A `frontend-dev` group with a more permissive `dev-fetch` server +- A `testing-suite` group with a restricted `test-fetch` server + +Each server has the same base image but different configurations appropriate for +its use case. + +### Running groups + +You can run entire groups using the group command: + +```bash +# Run all servers in the frontend-dev group +thv group run frontend-dev + +# Run all servers in the testing-suite group +thv group run testing-suite + +# You can also pass environment variables and secrets to group runs +thv group run frontend-dev --env DEV_MODE=true --secret API_KEY=my-secret +``` + +Groups provide a convenient way to start multiple related servers with a single +command. + ## Production considerations While this tutorial uses a local file for simplicity, in production environments @@ -257,11 +458,13 @@ You've successfully: - Created a custom MCP registry following the JSON schema - Configured ToolHive to use your custom registry - Added MCP servers with proper metadata and permissions -- Tested your registry by listing and running servers +- Created groups to organize related servers +- Tested your registry by listing and running both individual servers and groups -You can now maintain your own curated list of MCP servers tailored to your -organization's needs. The registry can include both public servers from -container registries and private servers hosted within your organization. +You can now maintain your own curated list of MCP servers and groups tailored to +your organization's needs. The registry can include both public servers from +container registries and private servers hosted within your organization, +organized into logical groups for different teams or workflows. ## Next steps From e0ae1712a19e9bfa7e70ae104806f1132abca91a Mon Sep 17 00:00:00 2001 From: Radoslav Dimitrov Date: Tue, 16 Sep 2025 14:33:43 +0300 Subject: [PATCH 02/11] Update docs/toolhive/tutorials/custom-registry.mdx Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/toolhive/tutorials/custom-registry.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/toolhive/tutorials/custom-registry.mdx b/docs/toolhive/tutorials/custom-registry.mdx index 3360e5f6..cf2cf779 100644 --- a/docs/toolhive/tutorials/custom-registry.mdx +++ b/docs/toolhive/tutorials/custom-registry.mdx @@ -113,8 +113,7 @@ Create a new file called `registry.json` and add the following content: This registry defines: - A single MCP server called `my-fetch` in the top-level `servers` section -- A group called `dev-toolkit` with its own independent server called - `fetch-tool` +- A group called `dev-toolkit` with its own independent server called `fetch-tool` Groups are optional - you can omit the entire `groups` section if you only need individual servers. Groups are independent entities that contain their own From d5bd4ea0817b8127f91e65428dc5297c42f176ca Mon Sep 17 00:00:00 2001 From: Radoslav Dimitrov Date: Tue, 16 Sep 2025 14:34:25 +0300 Subject: [PATCH 03/11] Update docs/toolhive/tutorials/custom-registry.mdx Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/toolhive/tutorials/custom-registry.mdx | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/toolhive/tutorials/custom-registry.mdx b/docs/toolhive/tutorials/custom-registry.mdx index cf2cf779..8f351c35 100644 --- a/docs/toolhive/tutorials/custom-registry.mdx +++ b/docs/toolhive/tutorials/custom-registry.mdx @@ -460,10 +460,7 @@ You've successfully: - Created groups to organize related servers - Tested your registry by listing and running both individual servers and groups -You can now maintain your own curated list of MCP servers and groups tailored to -your organization's needs. The registry can include both public servers from -container registries and private servers hosted within your organization, -organized into logical groups for different teams or workflows. +You can now maintain your own curated list of MCP servers and groups tailored to your organization's needs, organized into logical groups for different teams or workflows. The registry can include both public servers from container registries and private servers hosted within your organization. ## Next steps From 3fa575d281e79e349cefbdb6557d3a664cbf595e Mon Sep 17 00:00:00 2001 From: Radoslav Dimitrov Date: Tue, 16 Sep 2025 14:38:07 +0300 Subject: [PATCH 04/11] Fix the linter failing Signed-off-by: Radoslav Dimitrov --- docs/toolhive/tutorials/custom-registry.mdx | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/toolhive/tutorials/custom-registry.mdx b/docs/toolhive/tutorials/custom-registry.mdx index 8f351c35..bf0db8fc 100644 --- a/docs/toolhive/tutorials/custom-registry.mdx +++ b/docs/toolhive/tutorials/custom-registry.mdx @@ -113,7 +113,8 @@ Create a new file called `registry.json` and add the following content: This registry defines: - A single MCP server called `my-fetch` in the top-level `servers` section -- A group called `dev-toolkit` with its own independent server called `fetch-tool` +- A group called `dev-toolkit` with its own independent server called + `fetch-tool` Groups are optional - you can omit the entire `groups` section if you only need individual servers. Groups are independent entities that contain their own @@ -460,7 +461,10 @@ You've successfully: - Created groups to organize related servers - Tested your registry by listing and running both individual servers and groups -You can now maintain your own curated list of MCP servers and groups tailored to your organization's needs, organized into logical groups for different teams or workflows. The registry can include both public servers from container registries and private servers hosted within your organization. +You can now maintain your own curated list of MCP servers and groups tailored to +your organization's needs, organized into logical groups for different teams or +workflows. The registry can include both public servers from container +registries and private servers hosted within your organization. ## Next steps From c4ef9d6c46a56e90954d776bcabb6748301b53dc Mon Sep 17 00:00:00 2001 From: Radoslav Dimitrov Date: Tue, 16 Sep 2025 15:18:49 +0300 Subject: [PATCH 05/11] Reorganise groups content and update the docs for running MCP servers Signed-off-by: Radoslav Dimitrov --- docs/toolhive/guides-cli/registry.md | 156 +++++++++++++++++++ docs/toolhive/guides-cli/run-mcp-servers.mdx | 19 +++ docs/toolhive/tutorials/custom-registry.mdx | 150 ------------------ 3 files changed, 175 insertions(+), 150 deletions(-) diff --git a/docs/toolhive/guides-cli/registry.md b/docs/toolhive/guides-cli/registry.md index 5a9150b2..a6b29866 100644 --- a/docs/toolhive/guides-cli/registry.md +++ b/docs/toolhive/guides-cli/registry.md @@ -185,6 +185,162 @@ thv config unset-registry This restores the default behavior of using ToolHive's built-in registry. +## Organize servers with registry groups + +Registry groups allow you to organize related MCP servers and run them together +as a cohesive unit. This is particularly useful for creating team-specific +toolkits, workflow-based server collections, or environment-specific +configurations. + +:::note + +Registry groups are different from [runtime groups](./group-management.md). +Registry groups organize server definitions within registry files, while runtime +groups organize running server instances for access control. + +::: + +### Group structure + +Groups are defined as a top-level array in your custom registry: + +```json +{ + "servers": { + // Individual servers + }, + "groups": [ + { + "name": "group-name", + "description": "Description of what this group provides", + "servers": { + "server-name": { + // Complete server definition + } + }, + "remote_servers": { + "remote-server-name": { + // Complete remote server definition + } + } + } + ] +} +``` + +### Key characteristics + +- **Optional**: Groups are entirely optional. Omit the `groups` section if you + only need individual servers +- **Independent server definitions**: Each group contains complete server + configurations, not references to top-level servers +- **Self-contained**: Groups can define servers with the same names as top-level + servers but with different configurations +- **Flexible membership**: The same server can appear in multiple groups with + different configurations + +### Example: Multi-environment groups + +Here's an example showing how groups can organize servers for different +purposes: + +```json title='registry-with-groups.json' +{ + "$schema": "https://raw.githubusercontent.com/stacklok/toolhive/main/pkg/registry/data/schema.json", + "version": "1.0.0", + "last_updated": "2025-08-15T10:00:00Z", + "servers": { + "production-fetch": { + "description": "Production web content fetching server", + "image": "ghcr.io/stackloklabs/gofetch/server:latest", + "status": "Active", + "tier": "Community", + "transport": "streamable-http", + "permissions": { + "network": { + "outbound": { + "allow_host": [".company.com"], + "allow_port": [443] + } + } + } + } + }, + "groups": [ + { + "name": "frontend-dev", + "description": "Tools for frontend development team", + "servers": { + "dev-fetch": { + "description": "Development web content fetching with broader access", + "image": "ghcr.io/stackloklabs/gofetch/server:latest", + "status": "Active", + "tier": "Community", + "transport": "streamable-http", + "permissions": { + "network": { + "outbound": { + "allow_host": ["*"], + "allow_port": [80, 443] + } + } + } + } + } + }, + { + "name": "testing-suite", + "description": "Servers needed for automated testing workflows", + "servers": { + "test-fetch": { + "description": "Restricted fetch server for testing", + "image": "ghcr.io/stackloklabs/gofetch/server:latest", + "status": "Active", + "tier": "Community", + "transport": "streamable-http", + "args": ["--timeout", "5s"], + "permissions": { + "network": { + "outbound": { + "allow_host": ["test.example.com"], + "allow_port": [443] + } + } + } + } + } + } + ] +} +``` + +This registry provides: + +- A production-ready `production-fetch` server at the top level +- A `frontend-dev` group with a more permissive `dev-fetch` server +- A `testing-suite` group with a restricted `test-fetch` server + +Each server has the same base image but different configurations appropriate for +its use case. + +### Run registry groups + +You can run entire groups using the group command: + +```bash +# Run all servers in the frontend-dev group +thv group run frontend-dev + +# Run all servers in the testing-suite group +thv group run testing-suite + +# You can also pass environment variables and secrets to group runs +thv group run frontend-dev --env DEV_MODE=true --secret API_KEY=my-secret +``` + +Groups provide a convenient way to start multiple related servers with a single +command. + ## Next steps See [Run MCP servers](./run-mcp-servers.mdx) to run an MCP server from the diff --git a/docs/toolhive/guides-cli/run-mcp-servers.mdx b/docs/toolhive/guides-cli/run-mcp-servers.mdx index 7d81af9a..b27c3a83 100644 --- a/docs/toolhive/guides-cli/run-mcp-servers.mdx +++ b/docs/toolhive/guides-cli/run-mcp-servers.mdx @@ -65,6 +65,25 @@ Use `thv search ` or `thv registry list` to discover available servers. ::: +### Run registry groups + +If your custom registry includes groups, you can also run an entire group of +servers: + +```bash +thv group run +``` + +For example, to run all servers in a group called `dev-toolkit`: + +```bash +thv group run dev-toolkit +``` + +This starts all servers defined within the specified registry group. See +[Registry groups](./registry.md#organize-servers-with-registry-groups) for more +information about organizing servers into groups in your custom registry. + :::info[What's happening?] When you run an MCP server from the registry, ToolHive handles different server diff --git a/docs/toolhive/tutorials/custom-registry.mdx b/docs/toolhive/tutorials/custom-registry.mdx index bf0db8fc..4985306d 100644 --- a/docs/toolhive/tutorials/custom-registry.mdx +++ b/docs/toolhive/tutorials/custom-registry.mdx @@ -284,156 +284,6 @@ After updating the file, the new server is immediately available for ToolHive CLI commands. For the UI, navigate to the registry settings and click **Save** to see the new server listed. -## Working with groups - -Groups allow you to organize related MCP servers and run them together as a -cohesive unit. This is particularly useful for: - -- **Team-specific toolkits**: Create groups for different teams (frontend, - backend, DevOps) -- **Workflow-based organization**: Group servers needed for specific workflows - (testing, deployment, monitoring) -- **Environment-specific configurations**: Different server configurations for - development, staging, and production - -### Group structure - -Groups in your registry have the following structure: - -```json -{ - "groups": [ - { - "name": "group-name", - "description": "Description of what this group provides", - "servers": { - "server-name": { - // Complete server definition - } - }, - "remote_servers": { - "remote-server-name": { - // Complete remote server definition - } - } - } - ] -} -``` - -### Key characteristics of groups - -- **Independent server definitions**: Each group contains complete server - configurations, not references to top-level servers -- **Self-contained**: Groups can define servers with the same names as top-level - servers but with different configurations -- **Organizational only**: Groups provide organization but don't affect server - runtime behavior -- **Flexible membership**: Servers can appear in multiple groups with different - configurations - -### Example: Multi-group registry - -Here's a more comprehensive example showing how groups can organize servers for -different purposes: - -```json title='advanced-registry.json' -{ - "$schema": "https://raw.githubusercontent.com/stacklok/toolhive/main/pkg/registry/data/schema.json", - "version": "1.0.0", - "last_updated": "2025-08-15T10:00:00Z", - "servers": { - "production-fetch": { - "description": "Production web content fetching server", - "image": "ghcr.io/stackloklabs/gofetch/server:latest", - "status": "Active", - "tier": "Community", - "transport": "streamable-http", - "permissions": { - "network": { - "outbound": { - "allow_host": [".company.com"], - "allow_port": [443] - } - } - } - } - }, - "groups": [ - { - "name": "frontend-dev", - "description": "Tools for frontend development team", - "servers": { - "dev-fetch": { - "description": "Development web content fetching with broader access", - "image": "ghcr.io/stackloklabs/gofetch/server:latest", - "status": "Active", - "tier": "Community", - "transport": "streamable-http", - "permissions": { - "network": { - "outbound": { - "allow_host": ["*"], - "allow_port": [80, 443] - } - } - } - } - } - }, - { - "name": "testing-suite", - "description": "Servers needed for automated testing workflows", - "servers": { - "test-fetch": { - "description": "Restricted fetch server for testing", - "image": "ghcr.io/stackloklabs/gofetch/server:latest", - "status": "Active", - "tier": "Community", - "transport": "streamable-http", - "args": ["--timeout", "5s"], - "permissions": { - "network": { - "outbound": { - "allow_host": ["test.example.com"], - "allow_port": [443] - } - } - } - } - } - } - ] -} -``` - -This registry provides: - -- A production-ready `production-fetch` server at the top level -- A `frontend-dev` group with a more permissive `dev-fetch` server -- A `testing-suite` group with a restricted `test-fetch` server - -Each server has the same base image but different configurations appropriate for -its use case. - -### Running groups - -You can run entire groups using the group command: - -```bash -# Run all servers in the frontend-dev group -thv group run frontend-dev - -# Run all servers in the testing-suite group -thv group run testing-suite - -# You can also pass environment variables and secrets to group runs -thv group run frontend-dev --env DEV_MODE=true --secret API_KEY=my-secret -``` - -Groups provide a convenient way to start multiple related servers with a single -command. - ## Production considerations While this tutorial uses a local file for simplicity, in production environments From 152469aacd52c546e827e7ebaa1d2ac1c0cf2c5d Mon Sep 17 00:00:00 2001 From: Radoslav Dimitrov Date: Thu, 18 Sep 2025 09:55:48 +0300 Subject: [PATCH 06/11] Update docs/toolhive/tutorials/custom-registry.mdx Co-authored-by: Dan Barr --- docs/toolhive/tutorials/custom-registry.mdx | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/docs/toolhive/tutorials/custom-registry.mdx b/docs/toolhive/tutorials/custom-registry.mdx index 4985306d..95887639 100644 --- a/docs/toolhive/tutorials/custom-registry.mdx +++ b/docs/toolhive/tutorials/custom-registry.mdx @@ -110,20 +110,19 @@ Create a new file called `registry.json` and add the following content: } ``` -This registry defines: +This registry contains two types of server configurations: -- A single MCP server called `my-fetch` in the top-level `servers` section -- A group called `dev-toolkit` with its own independent server called - `fetch-tool` +- A standalone MCP server called `my-fetch` in the top-level `servers` section +- A group called `dev-toolkit` containing a `fetch-tool` server -Groups are optional - you can omit the entire `groups` section if you only need -individual servers. Groups are independent entities that contain their own -complete server definitions. The `dev-toolkit` group includes a `fetch-tool` -server that's similar to the top-level `my-fetch` server but with different -configuration (different user agent, different allowed hosts for development -purposes). +The `dev-toolkit` group demonstrates how you can organize related servers +together. When you run this group later, you'll be able to start multiple +servers as a single unit—perfect for development workflows or team-specific +toolsets. Notice how the `fetch-tool` server has a different user agent and +network permissions than `my-fetch`, showing how you can customize servers +within groups for specific purposes. -Each server definition includes: +Your server configurations include everything ToolHive needs to run them: - A description explaining its purpose - The container image to use From e9f9a9fc3c40e4e2b20222fae230be4612be580a Mon Sep 17 00:00:00 2001 From: Radoslav Dimitrov Date: Thu, 18 Sep 2025 09:55:58 +0300 Subject: [PATCH 07/11] Update docs/toolhive/tutorials/custom-registry.mdx Co-authored-by: Dan Barr --- docs/toolhive/tutorials/custom-registry.mdx | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/toolhive/tutorials/custom-registry.mdx b/docs/toolhive/tutorials/custom-registry.mdx index 95887639..c76ffb4a 100644 --- a/docs/toolhive/tutorials/custom-registry.mdx +++ b/docs/toolhive/tutorials/custom-registry.mdx @@ -131,9 +131,6 @@ Your server configurations include everything ToolHive needs to run them: - Command-line arguments for customization - Network permissions for security -Groups provide an organizational layer that allows you to run multiple related -servers together as a cohesive unit. - ### Step 2: Configure ToolHive to use your registry Configure ToolHive to use your custom registry. From 14ebc1d4176d87baa264fe619aac56fa9b5e8640 Mon Sep 17 00:00:00 2001 From: Radoslav Dimitrov Date: Thu, 18 Sep 2025 09:56:05 +0300 Subject: [PATCH 08/11] Update docs/toolhive/tutorials/custom-registry.mdx Co-authored-by: Dan Barr --- docs/toolhive/tutorials/custom-registry.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/toolhive/tutorials/custom-registry.mdx b/docs/toolhive/tutorials/custom-registry.mdx index c76ffb4a..b04c407e 100644 --- a/docs/toolhive/tutorials/custom-registry.mdx +++ b/docs/toolhive/tutorials/custom-registry.mdx @@ -228,7 +228,7 @@ thv run my-fetch The server should start successfully, demonstrating that your custom registry is working correctly. -You can also run the entire group: +Next, run the `dev-toolkit` group: ```bash thv group run dev-toolkit From 82bf1b1e728cd54ab97b568f70cd66b813a53167 Mon Sep 17 00:00:00 2001 From: Radoslav Dimitrov Date: Thu, 18 Sep 2025 09:56:12 +0300 Subject: [PATCH 09/11] Update docs/toolhive/guides-cli/run-mcp-servers.mdx Co-authored-by: Dan Barr --- docs/toolhive/guides-cli/run-mcp-servers.mdx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/toolhive/guides-cli/run-mcp-servers.mdx b/docs/toolhive/guides-cli/run-mcp-servers.mdx index b27c3a83..d86e0768 100644 --- a/docs/toolhive/guides-cli/run-mcp-servers.mdx +++ b/docs/toolhive/guides-cli/run-mcp-servers.mdx @@ -30,6 +30,7 @@ server that fetches website contents: thv run fetch ``` +<<<<<<< HEAD ### Remote MCP servers Remote MCP servers in the registry don't run as local containers but instead use @@ -67,8 +68,9 @@ Use `thv search ` or `thv registry list` to discover available servers. ### Run registry groups -If your custom registry includes groups, you can also run an entire group of -servers: +If you use a [custom registry](./registry.md#use-a-custom-registry) that +includes groups, you can run multiple related servers together as a unit. This +is useful when you need several servers for a specific workflow or project: ```bash thv group run From 73befffeed461ec85ef2a33c5ae32db3c9649abe Mon Sep 17 00:00:00 2001 From: Radoslav Dimitrov Date: Thu, 18 Sep 2025 09:56:17 +0300 Subject: [PATCH 10/11] Update docs/toolhive/guides-cli/run-mcp-servers.mdx Co-authored-by: Dan Barr --- docs/toolhive/guides-cli/run-mcp-servers.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/toolhive/guides-cli/run-mcp-servers.mdx b/docs/toolhive/guides-cli/run-mcp-servers.mdx index d86e0768..56196d25 100644 --- a/docs/toolhive/guides-cli/run-mcp-servers.mdx +++ b/docs/toolhive/guides-cli/run-mcp-servers.mdx @@ -82,7 +82,8 @@ For example, to run all servers in a group called `dev-toolkit`: thv group run dev-toolkit ``` -This starts all servers defined within the specified registry group. See +Running a group starts all servers defined within that group simultaneously, +saving you from running each server individually. See [Registry groups](./registry.md#organize-servers-with-registry-groups) for more information about organizing servers into groups in your custom registry. From 10c0a59e33eccf5d7f92a88b14d0142a660a580f Mon Sep 17 00:00:00 2001 From: Radoslav Dimitrov Date: Thu, 18 Sep 2025 10:21:07 +0300 Subject: [PATCH 11/11] Update the example servers in the group and address review feedback Signed-off-by: Radoslav Dimitrov --- docs/toolhive/guides-cli/registry.md | 57 +++++++++++++------- docs/toolhive/guides-cli/run-mcp-servers.mdx | 1 - docs/toolhive/tutorials/custom-registry.mdx | 7 +++ 3 files changed, 44 insertions(+), 21 deletions(-) diff --git a/docs/toolhive/guides-cli/registry.md b/docs/toolhive/guides-cli/registry.md index a6b29866..258ab4fc 100644 --- a/docs/toolhive/guides-cli/registry.md +++ b/docs/toolhive/guides-cli/registry.md @@ -268,23 +268,38 @@ purposes: }, "groups": [ { - "name": "frontend-dev", - "description": "Tools for frontend development team", + "name": "devops-toolkit", + "description": "Complete DevOps toolkit for development teams", "servers": { - "dev-fetch": { - "description": "Development web content fetching with broader access", - "image": "ghcr.io/stackloklabs/gofetch/server:latest", + "github": { + "description": "GitHub integration for repository and issue management", + "image": "ghcr.io/github/github-mcp-server:v0.15.0", + "status": "Active", + "tier": "Official", + "transport": "stdio", + "env_vars": [ + { + "name": "GITHUB_PERSONAL_ACCESS_TOKEN", + "description": "GitHub personal access token", + "required": true, + "secret": true + } + ] + }, + "heroku": { + "description": "Heroku platform deployment and management", + "image": "ghcr.io/stacklok/dockyard/npx/heroku-mcp-server:1.0.7", "status": "Active", "tier": "Community", - "transport": "streamable-http", - "permissions": { - "network": { - "outbound": { - "allow_host": ["*"], - "allow_port": [80, 443] - } + "transport": "stdio", + "env_vars": [ + { + "name": "HEROKU_API_KEY", + "description": "Heroku API key", + "required": true, + "secret": true } - } + ] } } }, @@ -317,25 +332,27 @@ purposes: This registry provides: - A production-ready `production-fetch` server at the top level -- A `frontend-dev` group with a more permissive `dev-fetch` server +- A `devops-toolkit` group with GitHub and Heroku servers for complete DevOps + workflows - A `testing-suite` group with a restricted `test-fetch` server -Each server has the same base image but different configurations appropriate for -its use case. +Notice how the `devops-toolkit` group contains multiple servers that work +together—GitHub for repository management and Heroku for +deployment—demonstrating how groups can bundle related functionality. ### Run registry groups You can run entire groups using the group command: ```bash -# Run all servers in the frontend-dev group -thv group run frontend-dev +# Run all servers in the devops-toolkit group (GitHub + Heroku) +thv group run devops-toolkit # Run all servers in the testing-suite group thv group run testing-suite -# You can also pass environment variables and secrets to group runs -thv group run frontend-dev --env DEV_MODE=true --secret API_KEY=my-secret +# You can also pass environment variables and secrets to specific servers in the group +thv group run devops-toolkit --secret github-token,target=github.GITHUB_PERSONAL_ACCESS_TOKEN --secret heroku-key,target=heroku.HEROKU_API_KEY ``` Groups provide a convenient way to start multiple related servers with a single diff --git a/docs/toolhive/guides-cli/run-mcp-servers.mdx b/docs/toolhive/guides-cli/run-mcp-servers.mdx index 56196d25..b52a9868 100644 --- a/docs/toolhive/guides-cli/run-mcp-servers.mdx +++ b/docs/toolhive/guides-cli/run-mcp-servers.mdx @@ -30,7 +30,6 @@ server that fetches website contents: thv run fetch ``` -<<<<<<< HEAD ### Remote MCP servers Remote MCP servers in the registry don't run as local containers but instead use diff --git a/docs/toolhive/tutorials/custom-registry.mdx b/docs/toolhive/tutorials/custom-registry.mdx index b04c407e..27d2bf9a 100644 --- a/docs/toolhive/tutorials/custom-registry.mdx +++ b/docs/toolhive/tutorials/custom-registry.mdx @@ -131,6 +131,13 @@ Your server configurations include everything ToolHive needs to run them: - Command-line arguments for customization - Network permissions for security +:::note + +Registry groups are currently supported in the CLI. UI support for browsing and +managing registry groups may not be immediately available in all versions. + +::: + ### Step 2: Configure ToolHive to use your registry Configure ToolHive to use your custom registry.