Document groups in the UI

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

@@ -15,6 +15,14 @@ click **Manage Clients**. This opens a dialog that lists detected clients with
 on/off toggles. Discovery is dynamic: if you install a new client, ToolHive
 updates the list.
 
+:::tip[Using groups?]
+
+If you organize your MCP servers into groups, you can configure client access
+per group. This lets you control which servers each client can access. See
+[Organize servers with groups](./group-management.mdx) for details.
+
+:::
+
 ### Connect a client
 
 To connect a client to ToolHive:
@@ -74,3 +82,4 @@ for some common examples.
 
 - [Client compatibility](../reference/client-compatibility.mdx)
 - [Run MCP servers](./run-mcp-servers.mdx)
+- [Organize servers with groups](./group-management.mdx)

docs/toolhive/guides-ui/group-management.mdx

@@ -0,0 +1,159 @@
+---
+title: Organize servers with groups
+description:
+  How to organize MCP servers into logical groups and configure client access in
+  the ToolHive UI.
+---
+
+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?]
+
+The `default` group always exists and cannot be deleted. When you add an MCP
+server, the `default` group is preselected in the group field unless you choose
+a different group.
+
+:::
+
+## View and navigate groups
+
+A sidebar appears on the left side of the **MCP Servers** page listing all your
+groups. The active group is highlighted.
+
+To view servers in a different group, click on the group name in the sidebar.
+The **MCP Servers** page updates to show only the servers in that group.
+
+## Create a group
+
+To create a new group:
+
+1. Open the **MCP Servers** page.
+2. Click **Add a group** in the groups sidebar.
+3. Enter a unique name for the group.
+4. Click **Create** to create the group.
+
+Group names are case-sensitive. For example, "Development" and "development" are
+treated as different groups.
+
+:::note
+
+Group names must be unique. If you try to create a group with a name that
+already exists, you'll see an error message.
+
+:::
+
+## Assign servers to groups
+
+When you install or configure an MCP server, you assign it to a group. All
+server types (registry, custom local, and remote) include a **Group** field in
+their configuration forms.
+
+### Assign a server during installation
+
+When installing a new MCP server from the registry or adding a custom server:
+
+1. Fill in the server configuration as usual.
+2. In the **Group** field, select the group where you want to add the server.
+3. If the group doesn't exist yet, you can create it on the fly from the
+   dropdown.
+4. Click **Install server** to add the server to the selected group.
+
+### Move a server to a different group
+
+You cannot directly move a server between groups. Instead, you can copy the
+server to a different group:
+
+1. On the **MCP Servers** page, find the server you want to copy.
+2. Click the menu (︙) on the server card.
+3. Select **Copy server to a group**.
+4. Choose the destination group.
+5. Provide a new name for the server (ToolHive suggests a name based on the
+   format `{serverName}-{groupName}`).
+6. Click **Copy** to duplicate the server configuration to the new group.
+
+This creates a complete copy of the server in the destination group, preserving
+all configuration including secrets, environment variables, and storage volumes.
+The original server remains in its current group.
+
+If you want to remove the original server after copying, you can delete it
+manually from its original group.
+
+## Manage client access per group
+
+You can control which AI clients have access to servers in each group. This lets
+you configure different tool sets for different clients or environments.
+
+To manage client access for a group:
+
+1. Navigate to the group by clicking on its name in the groups sidebar.
+2. Click **Manage Clients** on the group page.
+3. Toggle the switches to enable or disable clients for this group.
+4. Click **Save** to apply your changes.
+
+When you enable a client for a group, ToolHive registers that client to access
+all servers in the group. When you disable a client for a group, ToolHive
+unregisters the client from that group.
+
+:::tip
+
+You can enable the same client for multiple groups. The client will have access
+to servers from all groups where it's enabled.
+
+:::
+
+## Delete a group
+
+To delete a group:
+
+1. Navigate to the group by clicking on its name in the groups sidebar.
+2. Click the group actions menu (⋮) in the header.
+3. Select **Delete group**.
+4. Confirm the deletion in the dialog.
+
+:::warning
+
+Deleting a group permanently removes all servers in that group. This action
+cannot be undone. If you want to preserve the servers, copy them to another
+group before deleting.
+
+:::
+
+You cannot delete the `default` group.
+
+## Example workflows
+
+### Separate development and production servers
+
+1. Create two groups: "development" and "production".
+2. Install your MCP servers, assigning development tools to the "development"
+   group and production tools to the "production" group.
+3. Configure your primary AI client (like GitHub Copilot) to access only the
+   "development" group for day-to-day coding work.
+4. Use a different client or manually configure clients to access the
+   "production" group when needed.
+
+### Project-based organization
+
+1. Create groups for each project: "webapp-frontend", "webapp-backend", and
+   "mobile-app".
+2. Install project-specific MCP servers in each group (for example, React tools
+   in "webapp-frontend", database tools in "webapp-backend").
+3. Configure different AI clients or workspaces to access the appropriate groups
+   for each project.
+
+## Related information
+
+- [Run MCP servers](./run-mcp-servers.mdx)
+- [Client configuration](./client-configuration.mdx)
+- [Secrets management](./secrets-management.mdx)

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

@@ -60,6 +60,11 @@ remaining required information and adjust any optional settings as needed:
    This defaults to the MCP server's name in the registry. If you want to run
    multiple instances of the same MCP server, give each instance a unique name.
 
+1. **Group**: The group where this server will be added. [Optional]\
+   Select an existing group or keep the default. Groups help you organize
+   servers and control client access. See
+   [Organize servers with groups](./group-management.mdx) for details.
+
 1. **Command arguments** (optional):\
    Enter any command-line arguments needed to run the MCP server. These might be
    needed to pass application-specific parameters to the MCP server. Refer to
@@ -117,6 +122,10 @@ The configuration form is pre-filled with defaults from the registry. Enter the
 remaining required information and adjust any optional settings as needed:
 
 1. A unique **name** for the MCP server. [Required]
+1. **Group**: The group where this server will be added. [Optional]\
+   Select an existing group or keep the default. Groups help you organize
+   servers and control client access. See
+   [Organize servers with groups](./group-management.mdx) for details.
 1. The **URL** of the remote MCP server. [Required]
 1. The **transport protocol** that the MCP server uses. [Required]\
    ToolHive supports server-sent events (SSE) and Streamable HTTP (default) for
@@ -233,6 +242,11 @@ On the configuration form, enter:
 
 1. A unique **name** for the MCP server. [Required]
 
+1. **Group**: The group where this server will be added. [Optional]\
+   Select an existing group or keep the default. Groups help you organize
+   servers and control client access. See
+   [Organize servers with groups](./group-management.mdx) for details.
+
 1. The **transport protocol** that the MCP server uses. [Required]\
    ToolHive supports standard input/output (`stdio`), server-sent events (SSE),
    and Streamable HTTP. The protocol must match what the MCP server supports.
@@ -288,6 +302,11 @@ On the configuration form, enter:
 
 1. A unique **name** for the MCP server. [Required]
 
+1. **Group**: The group where this server will be added. [Optional]\
+   Select an existing group or keep the default. Groups help you organize
+   servers and control client access. See
+   [Organize servers with groups](./group-management.mdx) for details.
+
 1. The **transport protocol** that the MCP server uses. [Required]\
    ToolHive supports standard input/output (`stdio`), server-sent events (SSE),
    and Streamable HTTP. The protocol must match what the MCP server supports.
@@ -350,12 +369,16 @@ remote MCP server** in the drop-down menu.
 On the configuration form, enter:
 
 1. A unique **name** for the MCP server. [Required]
-2. The **URL** of the remote MCP server. [Required]
-3. The **transport protocol** that the MCP server uses. [Required]\
+2. **Group**: The group where this server will be added. [Optional]\
+   Select an existing group or keep the default. Groups help you organize
+   servers and control client access. See
+   [Organize servers with groups](./group-management.mdx) for details.
+3. The **URL** of the remote MCP server. [Required]
+4. The **transport protocol** that the MCP server uses. [Required]\
    ToolHive supports server-sent events (SSE) and Streamable HTTP (default) for
    real-time communication. The protocol must match what the MCP server
    supports.
-4. **Authorization method**: Choose how ToolHive should authenticate with the
+5. **Authorization method**: Choose how ToolHive should authenticate with the
    remote server.\
    The default is **Dynamic Client Registration**. For MCP servers that fully
    implement the MCP authorization spec including dynamic client registration
@@ -395,7 +418,7 @@ On the configuration form, enter:
    - **PKCE**: Enable Proof Key for Code Exchange (RFC 7636) for enhanced
      security without requiring a client secret. [Optional]
 
-5. The **callback port** for the authentication redirect. [Required]
+6. The **callback port** for the authentication redirect. [Required]
 
 Click **Install server** to connect to the remote MCP server.
 
@@ -439,6 +462,10 @@ On the **MCP Servers** page, you can manage your installed MCP servers:
   AI clients to connect to the MCP server.
 - **View logs**: Click the menu (︙) on the server card and select **View logs**
   to see the server's output.
+- **Copy server to a group**: Click the menu (︙) on the server card and select
+  **Copy server to a group** to duplicate the server configuration to a
+  different group. See [Organize servers with groups](./group-management.mdx)
+  for details.
 - **Remove server**: Click the menu (︙) on the server card and select **Remove
   server** to stop and remove the MCP server from ToolHive. This deletes the
   container and any associated configuration, so use with caution.

sidebars.ts

@@ -49,6 +49,7 @@ const sidebars: SidebarsConfig = {
         'toolhive/guides-ui/install',
         'toolhive/guides-ui/registry',
         'toolhive/guides-ui/run-mcp-servers',
+        'toolhive/guides-ui/group-management',
         'toolhive/guides-ui/network-isolation',
         'toolhive/guides-ui/secrets-management',
         'toolhive/guides-ui/client-configuration',