Add documentation for groups

docs/toolhive/guides-cli/client-configuration.mdx

@@ -67,6 +67,12 @@ Example:
 thv client register vscode
 ```
 
+You can register a client with a specific group using the `--group` option:
+
+```bash
+thv client register <CLIENT_NAME> --group <GROUP_NAME>
+```
+
 Run [`thv client register --help`](../reference/cli/thv_client_register.md) for
 the latest list of supported clients.
 
@@ -87,6 +93,12 @@ To remove a client configuration:
 thv client remove <CLIENT_NAME>
 ```
 
+To remove a client configuration from a specific group:
+
+```bash
+thv client remove <CLIENT_NAME> --group <GROUP_NAME>
+```
+
 ## Other clients or tools
 
 If you have other clients or development libraries that ToolHive doesn't

docs/toolhive/guides-cli/group-management.md

@@ -0,0 +1,130 @@
+---
+title: Group MCP servers
+description:
+  How to organize MCP servers into logical groups and configure client access.
+---
+
+This guide explains how to organize your MCP servers into logical groups and
+configure which groups your MCP clients can access. Groups help you organize
+servers by project, environment, or team, and control which tools are available
+to different clients.
+
+## Why use groups?
+
+Groups let you organize MCP servers and control client access:
+
+- **Project isolation**: Keep development and production servers separate
+- **Environment management**: Organize servers by development stage
+- **Client customization**: Configure different tool sets for different clients
+
+:::info What's the default behavior?
+
+All MCP servers are automatically assigned to the `default` group unless you
+specify otherwise. MCP clients configured without a specific group can access
+all servers in the `default` group.
+
+:::
+
+## Create and organize groups
+
+### Create a group
+
+```bash
+thv group create <GROUP_NAME>
+```
+
+For example, to create separate groups for different environments:
+
+```bash
+thv group create development
+thv group create production
+```
+
+### Run servers in a group
+
+When running an MCP server, specify the group using the `--group` flag:
+
+```bash
+thv run --group development fetch
+thv run --group production filesystem --volume /prod/repo:/projects:ro
+```
+
+:::info What's happening?
+
+When you specify a group:
+
+1. The server is assigned to that group and labeled accordingly
+2. The server can only be accessed by clients configured for that group
+
+:::
+
+A single workload can only belong to one group at a time. To run multiple
+instances of the same MCP server in different groups, use a unique name for each
+instance:
+
+```bash
+thv run --group development --name fetch-dev fetch
+thv run --group production --name fetch-prod fetch
+```
+
+## Configure client access to groups
+
+You can configure MCP clients to access specific groups, giving you control over
+which tools are available in different contexts.
+
+### Configure a client for a specific group
+
+When registering a client, you can specify which group it should access:
+
+```bash
+thv client register <CLIENT_NAME> --group development
+```
+
+This configures the client to only access servers in the `development` group.
+
+## Example workflows
+
+### Project-based organization
+
+```bash
+# Create groups for different projects
+thv group create webapp-frontend
+thv group create webapp-backend
+
+# Run project-specific servers
+thv run --group webapp-frontend mcp-react-tools
+thv run --group webapp-backend mcp-database-tools
+
+# Configure clients with appropriate access
+thv client register --client vscode --group webapp-frontend
+thv client register --client cursor --group webapp-backend
+```
+
+## Manage groups
+
+### Remove a group
+
+Remove a group and move its servers to the default group:
+
+```bash
+thv group rm development
+```
+
+Remove a group and delete all its servers:
+
+```bash
+thv group rm development --with-workloads
+```
+
+:::warning
+
+Using `--with-workloads` permanently deletes all servers in the group.
+
+:::
+
+## Related information
+
+- [Client configuration](client-configuration.mdx)
+- [Run MCP servers](run-mcp-servers.mdx)
+- [`thv group` command reference](../reference/cli/thv_group.md)
+- [`thv client` command reference](../reference/cli/thv_client.md)

docs/toolhive/guides-cli/manage-mcp-servers.md

@@ -62,6 +62,12 @@ thv stop <SERVER_NAME>
 This stops the server and the associated proxy process, removes the MCP server's
 entry from your configured clients, but keeps the container for future use.
 
+Add the `--group` flag to stop all servers in a specific group:
+
+```bash
+thv stop --group <GROUP_NAME>
+```
+
 Add the `--all` flag to stop all running servers.
 
 ### Restart a server
@@ -72,6 +78,12 @@ To restart a stopped MCP server and add it back to your configured clients:
 thv restart <SERVER_NAME>
 ```
 
+Add the `--group` flag to restart all servers in a specific group:
+
+```bash
+thv restart --group <GROUP_NAME>
+```
+
 ### Remove a server
 
 To remove an MCP server:
@@ -84,6 +96,12 @@ This removes the container and cleans up the MCP server's entry in your
 configured clients. If the server is still running, it will be stopped as part
 of the removal.
 
+Add the `--group` flag to remove all servers in a specific group:
+
+```bash
+thv rm --group <GROUP_NAME>
+```
+
 :::note
 
 If you use `docker rm` to remove an MCP container that ToolHive created, it

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

@@ -97,6 +97,24 @@ thv run --secret github,target=GITHUB_PERSONAL_ACCESS_TOKEN github
 See [Secrets management](./secrets-management.mdx) to learn how to manage
 secrets in ToolHive.
 
+### Run a server within a group
+
+To run an MCP server within a specific group, use the `--group` option. This
+allows you to organize your servers and manage them collectively.
+
+```bash
+thv run --group <GROUP_NAME> <SERVER>
+```
+
+:::note
+
+The group must exist before you can run a server in it.
+
+:::
+
+See [Group management](./group-management.md) for more details on organizing
+servers into groups and configuring client access.
+
 ### Mount a local file or directory
 
 To enable file system access for an MCP server, you can either use the

sidebars.ts

@@ -67,6 +67,7 @@ const sidebars: SidebarsConfig = {
         'toolhive/guides-cli/registry',
         'toolhive/guides-cli/run-mcp-servers',
         'toolhive/guides-cli/manage-mcp-servers',
+        'toolhive/guides-cli/group-management',
         'toolhive/guides-cli/secrets-management',
         'toolhive/guides-cli/client-configuration',
         {