diff --git a/docs/toolhive/guides-ui/client-configuration.mdx b/docs/toolhive/guides-ui/client-configuration.mdx index 08d2639..aa2d3c4 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 0000000..db5688a --- /dev/null +++ b/docs/toolhive/guides-ui/group-management.mdx @@ -0,0 +1,148 @@ +--- +title: Organize servers into groups +description: + 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 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 + +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. +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 sidebar. +3. Enter a unique name for the group. +4. Click **Create**. + +:::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. +2. In the **Group** field, select the group where you want to add the server. +3. Click **Install server**. + +### Copy a 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. 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. + +## 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 its name in the sidebar. +2. Click **Manage Clients**. +3. Toggle the switches to enable or disable clients for this group. +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 +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 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. + +:::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 2497a0f..45492da 100644 --- a/docs/toolhive/guides-ui/run-mcp-servers.mdx +++ b/docs/toolhive/guides-ui/run-mcp-servers.mdx @@ -61,6 +61,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 @@ -118,6 +123,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 @@ -235,6 +244,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. @@ -291,6 +305,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. @@ -353,12 +372,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 @@ -398,7 +421,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. @@ -448,6 +471,10 @@ On the **MCP Servers** page, you can manage your installed MCP servers: update. - **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 7cd3c87..efb5d29 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -59,6 +59,7 @@ const sidebars: SidebarsConfig = { id: 'toolhive/guides-ui/run-mcp-servers', }, items: [ + 'toolhive/guides-ui/group-management', 'toolhive/guides-ui/secrets-management', 'toolhive/guides-ui/network-isolation', ],