diff --git a/docs/toolhive/guides-cli/client-configuration.mdx b/docs/toolhive/guides-cli/client-configuration.mdx index bf0d546e..63ce406a 100644 --- a/docs/toolhive/guides-cli/client-configuration.mdx +++ b/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 --group +``` + 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 ``` +To remove a client configuration from a specific group: + +```bash +thv client remove --group +``` + ## Other clients or tools If you have other clients or development libraries that ToolHive doesn't diff --git a/docs/toolhive/guides-cli/group-management.md b/docs/toolhive/guides-cli/group-management.md new file mode 100644 index 00000000..98b35be0 --- /dev/null +++ b/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 +``` + +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 --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) diff --git a/docs/toolhive/guides-cli/manage-mcp-servers.md b/docs/toolhive/guides-cli/manage-mcp-servers.md index 99f673d7..d0aab926 100644 --- a/docs/toolhive/guides-cli/manage-mcp-servers.md +++ b/docs/toolhive/guides-cli/manage-mcp-servers.md @@ -62,6 +62,12 @@ thv stop 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 +``` + 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 ``` +Add the `--group` flag to restart all servers in a specific group: + +```bash +thv restart --group +``` + ### 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 +``` + :::note If you use `docker rm` to remove an MCP container that ToolHive created, it diff --git a/docs/toolhive/guides-cli/run-mcp-servers.mdx b/docs/toolhive/guides-cli/run-mcp-servers.mdx index e4ee541a..9440d5d5 100644 --- a/docs/toolhive/guides-cli/run-mcp-servers.mdx +++ b/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 +``` + +:::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 diff --git a/sidebars.ts b/sidebars.ts index 5ee03d89..4fa7a9c1 100644 --- a/sidebars.ts +++ b/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', {