Update the custom registry doc with info for the group catalog

docs/toolhive/guides-cli/registry.md

@@ -185,6 +185,179 @@ 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": "devops-toolkit",
+      "description": "Complete DevOps toolkit for development teams",
+      "servers": {
+        "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": "stdio",
+          "env_vars": [
+            {
+              "name": "HEROKU_API_KEY",
+              "description": "Heroku API key",
+              "required": true,
+              "secret": true
+            }
+          ]
+        }
+      }
+    },
+    {
+      "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 `devops-toolkit` group with GitHub and Heroku servers for complete DevOps
+  workflows
+- A `testing-suite` group with a restricted `test-fetch` server
+
+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 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 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
+command.
+
 ## Next steps
 
 See [Run MCP servers](./run-mcp-servers.mdx) to run an MCP server from the

docs/toolhive/guides-cli/run-mcp-servers.mdx

@@ -65,6 +65,27 @@ Use `thv search <NAME>` or `thv registry list` to discover available servers.
 
 :::
 
+### Run registry groups
+
+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 <GROUP_NAME>
+```
+
+For example, to run all servers in a group called `dev-toolkit`:
+
+```bash
+thv group run dev-toolkit
+```
+
+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.
+
 :::info[What's happening?]
 
 When you run an MCP server from the registry, ToolHive handles different server

docs/toolhive/tutorials/custom-registry.mdx

@@ -80,11 +80,49 @@ 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 contains two types of server configurations:
+
+- A standalone MCP server called `my-fetch` in the top-level `servers` section
+- A group called `dev-toolkit` containing a `fetch-tool` server
+
+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.
+
+Your server configurations include everything ToolHive needs to run them:
 
 - A description explaining its purpose
 - The container image to use
@@ -93,6 +131,13 @@ This registry defines a single MCP server called `my-fetch` with:
 - 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.
@@ -190,6 +235,15 @@ thv run my-fetch
 The server should start successfully, demonstrating that your custom registry is
 working correctly.
 
+Next, run the `dev-toolkit` group:
+
+```bash
+thv group run dev-toolkit
+```
+
+This starts all servers in the `dev-toolkit` group (in this case, just the
+`fetch-tool` server).
+
 </TabItem>
 </Tabs>
 
@@ -257,11 +311,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, 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