Reorganise groups content and update the docs for running MCP servers

Signed-off-by: Radoslav Dimitrov <[email protected]>

Author: rdimitrov

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

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

@@ -65,6 +65,25 @@ Use `thv search <NAME>` 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 <GROUP_NAME>
+```
+
+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

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