From d4da525accb6624cbafa69fd6042aeb7fb4fa5f9 Mon Sep 17 00:00:00 2001 From: Daniel Kantor Date: Wed, 8 Oct 2025 20:11:18 +0200 Subject: [PATCH 1/9] document groups in the UI --- .../guides-ui/client-configuration.mdx | 9 + docs/toolhive/guides-ui/group-management.mdx | 162 ++++++++++++++++++ docs/toolhive/guides-ui/run-mcp-servers.mdx | 35 +++- sidebars.ts | 1 + 4 files changed, 203 insertions(+), 4 deletions(-) create mode 100644 docs/toolhive/guides-ui/group-management.mdx diff --git a/docs/toolhive/guides-ui/client-configuration.mdx b/docs/toolhive/guides-ui/client-configuration.mdx index 08d26393..aa2d3c47 100644 --- a/docs/toolhive/guides-ui/client-configuration.mdx +++ b/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) diff --git a/docs/toolhive/guides-ui/group-management.mdx b/docs/toolhive/guides-ui/group-management.mdx new file mode 100644 index 00000000..695d3d10 --- /dev/null +++ b/docs/toolhive/guides-ui/group-management.mdx @@ -0,0 +1,162 @@ +--- +title: Organize servers with groups +description: + How to organize MCP servers into logical groups and configure client access in + the ToolHive UI. +--- + +Groups help you organize your MCP servers and control which clients can access +them. You can separate servers by project, environment, or team, and configure +different tool sets for different AI clients. + +## Why use groups? + +Groups provide organizational structure and access control for your MCP servers: + +- **Project isolation**: Keep development and production servers separate. +- **Environment management**: Organize servers by development stage (dev, + staging, production). +- **Client customization**: Configure different tool sets for different AI + clients. +- **Team collaboration**: Share specific server groups with team members. + +:::info[What's the default behavior?] + +All MCP servers are automatically assigned to the **default** group unless you +specify otherwise. The default group always exists and cannot be deleted. When +you connect AI clients without specifying a group, they access servers in the +default group. + +::: + +## View and navigate groups + +When the groups feature is enabled, 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 configures that client to access +all running servers in the group. When you disable a client, ToolHive removes +the group's servers from that client's configuration. + +:::tip + +You can enable the same client for multiple groups. The client will have access +to servers from all enabled groups. + +::: + +## 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) diff --git a/docs/toolhive/guides-ui/run-mcp-servers.mdx b/docs/toolhive/guides-ui/run-mcp-servers.mdx index e5c0561d..0069eeac 100644 --- a/docs/toolhive/guides-ui/run-mcp-servers.mdx +++ b/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. diff --git a/sidebars.ts b/sidebars.ts index b0f2e50d..50910ae8 100644 --- a/sidebars.ts +++ b/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', From ab374ea7dd6e6be03cb8785371ae14bd7df104f1 Mon Sep 17 00:00:00 2001 From: Daniel Kantor Date: Thu, 9 Oct 2025 15:54:43 +0200 Subject: [PATCH 2/9] wording fixes --- docs/toolhive/guides-ui/group-management.mdx | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/toolhive/guides-ui/group-management.mdx b/docs/toolhive/guides-ui/group-management.mdx index 695d3d10..1b8ee5e1 100644 --- a/docs/toolhive/guides-ui/group-management.mdx +++ b/docs/toolhive/guides-ui/group-management.mdx @@ -22,10 +22,10 @@ Groups provide organizational structure and access control for your MCP servers: :::info[What's the default behavior?] -All MCP servers are automatically assigned to the **default** group unless you -specify otherwise. The default group always exists and cannot be deleted. When +All MCP servers are automatically assigned to the `default` group unless you +specify otherwise. The `default` group always exists and cannot be deleted. When you connect AI clients without specifying a group, they access servers in the -default group. +`default` group. ::: @@ -104,14 +104,14 @@ To manage client access for a group: 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 configures that client to access -all running servers in the group. When you disable a client, ToolHive removes -the group's servers from that client's configuration. +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 enabled groups. +to servers from all groups where it's enabled. ::: @@ -132,7 +132,7 @@ group before deleting. ::: -You cannot delete the default group. +You cannot delete the `default` group. ## Example workflows From 1c0f2cce0dd64999b1f43742cf912ceae4dfa721 Mon Sep 17 00:00:00 2001 From: Daniel Kantor Date: Thu, 9 Oct 2025 16:04:42 +0200 Subject: [PATCH 3/9] make it more similar to cli --- docs/toolhive/guides-ui/group-management.mdx | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/docs/toolhive/guides-ui/group-management.mdx b/docs/toolhive/guides-ui/group-management.mdx index 1b8ee5e1..857bd631 100644 --- a/docs/toolhive/guides-ui/group-management.mdx +++ b/docs/toolhive/guides-ui/group-management.mdx @@ -5,20 +5,18 @@ description: the ToolHive UI. --- -Groups help you organize your MCP servers and control which clients can access -them. You can separate servers by project, environment, or team, and configure -different tool sets for different AI clients. +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 provide organizational structure and access control for your MCP servers: +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 (dev, - staging, production). -- **Client customization**: Configure different tool sets for different AI - clients. -- **Team collaboration**: Share specific server groups with team members. +- **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?] From 4deb24ece43907122cd7c532f3114d43cfbce178 Mon Sep 17 00:00:00 2001 From: Daniel Kantor Date: Thu, 9 Oct 2025 16:10:09 +0200 Subject: [PATCH 4/9] improve wording --- docs/toolhive/guides-ui/group-management.mdx | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/toolhive/guides-ui/group-management.mdx b/docs/toolhive/guides-ui/group-management.mdx index 857bd631..67e79473 100644 --- a/docs/toolhive/guides-ui/group-management.mdx +++ b/docs/toolhive/guides-ui/group-management.mdx @@ -20,10 +20,9 @@ Groups let you organize MCP servers and control client access: :::info[What's the default behavior?] -All MCP servers are automatically assigned to the `default` group unless you -specify otherwise. The `default` group always exists and cannot be deleted. When -you connect AI clients without specifying a group, they access servers in the -`default` group. +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. ::: From 75979039815b5be857f2ce390b83eca70dbb2317 Mon Sep 17 00:00:00 2001 From: Daniel Kantor Date: Thu, 9 Oct 2025 16:16:55 +0200 Subject: [PATCH 5/9] . --- docs/toolhive/guides-ui/group-management.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/toolhive/guides-ui/group-management.mdx b/docs/toolhive/guides-ui/group-management.mdx index 67e79473..11ebd241 100644 --- a/docs/toolhive/guides-ui/group-management.mdx +++ b/docs/toolhive/guides-ui/group-management.mdx @@ -28,8 +28,8 @@ a different group. ## View and navigate groups -When the groups feature is enabled, a sidebar appears on the left side of the -**MCP Servers** page listing all your groups. The active group is highlighted. +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. From 363f5ec17a48db2bd79f8112cff637afa18043ca Mon Sep 17 00:00:00 2001 From: Daniel Kantor Date: Thu, 9 Oct 2025 17:05:42 +0200 Subject: [PATCH 6/9] fixes --- docs/toolhive/guides-ui/group-management.mdx | 32 ++++++++------------ 1 file changed, 12 insertions(+), 20 deletions(-) diff --git a/docs/toolhive/guides-ui/group-management.mdx b/docs/toolhive/guides-ui/group-management.mdx index 11ebd241..67d57a23 100644 --- a/docs/toolhive/guides-ui/group-management.mdx +++ b/docs/toolhive/guides-ui/group-management.mdx @@ -28,7 +28,7 @@ a different group. ## View and navigate groups -A sidebar appears on the left side of the **MCP Servers** page listing all your +The **MCP Servers** page includes a sidebar on the left that lists all your groups. The active group is highlighted. To view servers in a different group, click on the group name in the sidebar. @@ -39,9 +39,9 @@ The **MCP Servers** page updates to show only the servers in that group. To create a new group: 1. Open the **MCP Servers** page. -2. Click **Add a group** in the groups sidebar. +2. Click **Add a group** in the sidebar. 3. Enter a unique name for the group. -4. Click **Create** to create the group. +4. Click **Create**. Group names are case-sensitive. For example, "Development" and "development" are treated as different groups. @@ -63,32 +63,24 @@ their configuration forms. When installing a new MCP server from the registry or adding a custom server: -1. Fill in the server configuration as usual. +1. Fill in the server configuration. 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. +3. Click **Install server**. -### Move a server to a different group +### Copy a server to a different group -You cannot directly move a server between groups. Instead, you can copy the -server to a different group: +You can copy a 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. +5. Click **Copy**. 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 @@ -96,10 +88,10 @@ 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. +1. Navigate to the group by clicking its name in the sidebar. +2. Click **Manage Clients**. 3. Toggle the switches to enable or disable clients for this group. -4. Click **Save** to apply your changes. +4. Click **Save**. 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 @@ -116,7 +108,7 @@ to servers from all groups where it's enabled. To delete a group: -1. Navigate to the group by clicking on its name in the groups sidebar. +1. Navigate to the group by clicking its name in the sidebar. 2. Click the group actions menu (⋮) in the header. 3. Select **Delete group**. 4. Confirm the deletion in the dialog. From ceaefb45031e23f9c3c8a880972ade07a76db944 Mon Sep 17 00:00:00 2001 From: Daniel Kantor Date: Thu, 9 Oct 2025 17:09:10 +0200 Subject: [PATCH 7/9] fixes --- docs/toolhive/guides-ui/group-management.mdx | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/toolhive/guides-ui/group-management.mdx b/docs/toolhive/guides-ui/group-management.mdx index 67d57a23..cde562c9 100644 --- a/docs/toolhive/guides-ui/group-management.mdx +++ b/docs/toolhive/guides-ui/group-management.mdx @@ -1,14 +1,14 @@ --- title: Organize servers with groups description: - How to organize MCP servers into logical groups and configure client access in - the ToolHive UI. + How to organize MCP servers into 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. +This guide explains how to organize your MCP servers into 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? @@ -148,4 +148,4 @@ You cannot delete the `default` group. - [Run MCP servers](./run-mcp-servers.mdx) - [Client configuration](./client-configuration.mdx) -- [Secrets management](./secrets-management.mdx) +- [Secrets management](./secrets-management.md) From 63a74185024078f9833e7f5e187ecf867efe9b18 Mon Sep 17 00:00:00 2001 From: Daniel Kantor Date: Thu, 9 Oct 2025 18:56:10 +0200 Subject: [PATCH 8/9] . --- docs/toolhive/guides-ui/group-management.mdx | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/toolhive/guides-ui/group-management.mdx b/docs/toolhive/guides-ui/group-management.mdx index cde562c9..3efb8a6e 100644 --- a/docs/toolhive/guides-ui/group-management.mdx +++ b/docs/toolhive/guides-ui/group-management.mdx @@ -43,9 +43,6 @@ To create a new group: 3. Enter a unique name for the group. 4. Click **Create**. -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 From 270c477422bf086b10a6a794a5598f41177c8aea Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Fri, 17 Oct 2025 09:38:41 -0400 Subject: [PATCH 9/9] Update page title to match CLI guide Signed-off-by: Dan Barr <6922515+danbarr@users.noreply.github.com> --- docs/toolhive/guides-ui/group-management.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/toolhive/guides-ui/group-management.mdx b/docs/toolhive/guides-ui/group-management.mdx index 3efb8a6e..db5688a5 100644 --- a/docs/toolhive/guides-ui/group-management.mdx +++ b/docs/toolhive/guides-ui/group-management.mdx @@ -1,5 +1,5 @@ --- -title: Organize servers with groups +title: Organize servers into groups description: How to organize MCP servers into groups and configure client access in the ToolHive UI. @@ -145,4 +145,4 @@ You cannot delete the `default` group. - [Run MCP servers](./run-mcp-servers.mdx) - [Client configuration](./client-configuration.mdx) -- [Secrets management](./secrets-management.md) +- [Secrets management](./secrets-management.mdx)