diff --git a/docs/toolhive/guides-cli/registry.md b/docs/toolhive/guides-cli/registry.md index 5a9150b2..258ab4fc 100644 --- a/docs/toolhive/guides-cli/registry.md +++ b/docs/toolhive/guides-cli/registry.md @@ -185,6 +185,179 @@ thv config unset-registry This restores the default behavior of using ToolHive's built-in registry. +## Organize servers with registry groups + +Registry groups allow you to organize related MCP servers and run them together +as a cohesive unit. This is particularly useful for creating team-specific +toolkits, workflow-based server collections, or environment-specific +configurations. + +:::note + +Registry groups are different from [runtime groups](./group-management.md). +Registry groups organize server definitions within registry files, while runtime +groups organize running server instances for access control. + +::: + +### Group structure + +Groups are defined as a top-level array in your custom registry: + +```json +{ + "servers": { + // Individual servers + }, + "groups": [ + { + "name": "group-name", + "description": "Description of what this group provides", + "servers": { + "server-name": { + // Complete server definition + } + }, + "remote_servers": { + "remote-server-name": { + // Complete remote server definition + } + } + } + ] +} +``` + +### Key characteristics + +- **Optional**: Groups are entirely optional. Omit the `groups` section if you + only need individual servers +- **Independent server definitions**: Each group contains complete server + configurations, not references to top-level servers +- **Self-contained**: Groups can define servers with the same names as top-level + servers but with different configurations +- **Flexible membership**: The same server can appear in multiple groups with + different configurations + +### Example: Multi-environment groups + +Here's an example showing how groups can organize servers for different +purposes: + +```json title='registry-with-groups.json' +{ + "$schema": "https://raw.githubusercontent.com/stacklok/toolhive/main/pkg/registry/data/schema.json", + "version": "1.0.0", + "last_updated": "2025-08-15T10:00:00Z", + "servers": { + "production-fetch": { + "description": "Production web content fetching server", + "image": "ghcr.io/stackloklabs/gofetch/server:latest", + "status": "Active", + "tier": "Community", + "transport": "streamable-http", + "permissions": { + "network": { + "outbound": { + "allow_host": [".company.com"], + "allow_port": [443] + } + } + } + } + }, + "groups": [ + { + "name": "devops-toolkit", + "description": "Complete DevOps toolkit for development teams", + "servers": { + "github": { + "description": "GitHub integration for repository and issue management", + "image": "ghcr.io/github/github-mcp-server:v0.15.0", + "status": "Active", + "tier": "Official", + "transport": "stdio", + "env_vars": [ + { + "name": "GITHUB_PERSONAL_ACCESS_TOKEN", + "description": "GitHub personal access token", + "required": true, + "secret": true + } + ] + }, + "heroku": { + "description": "Heroku platform deployment and management", + "image": "ghcr.io/stacklok/dockyard/npx/heroku-mcp-server:1.0.7", + "status": "Active", + "tier": "Community", + "transport": "stdio", + "env_vars": [ + { + "name": "HEROKU_API_KEY", + "description": "Heroku API key", + "required": true, + "secret": true + } + ] + } + } + }, + { + "name": "testing-suite", + "description": "Servers needed for automated testing workflows", + "servers": { + "test-fetch": { + "description": "Restricted fetch server for testing", + "image": "ghcr.io/stackloklabs/gofetch/server:latest", + "status": "Active", + "tier": "Community", + "transport": "streamable-http", + "args": ["--timeout", "5s"], + "permissions": { + "network": { + "outbound": { + "allow_host": ["test.example.com"], + "allow_port": [443] + } + } + } + } + } + } + ] +} +``` + +This registry provides: + +- A production-ready `production-fetch` server at the top level +- A `devops-toolkit` group with GitHub and Heroku servers for complete DevOps + workflows +- A `testing-suite` group with a restricted `test-fetch` server + +Notice how the `devops-toolkit` group contains multiple servers that work +together—GitHub for repository management and Heroku for +deployment—demonstrating how groups can bundle related functionality. + +### Run registry groups + +You can run entire groups using the group command: + +```bash +# Run all servers in the devops-toolkit group (GitHub + Heroku) +thv group run devops-toolkit + +# Run all servers in the testing-suite group +thv group run testing-suite + +# You can also pass environment variables and secrets to specific servers in the group +thv group run devops-toolkit --secret github-token,target=github.GITHUB_PERSONAL_ACCESS_TOKEN --secret heroku-key,target=heroku.HEROKU_API_KEY +``` + +Groups provide a convenient way to start multiple related servers with a single +command. + ## Next steps See [Run MCP servers](./run-mcp-servers.mdx) to run an MCP server from the diff --git a/docs/toolhive/guides-cli/run-mcp-servers.mdx b/docs/toolhive/guides-cli/run-mcp-servers.mdx index 7d81af9a..b52a9868 100644 --- a/docs/toolhive/guides-cli/run-mcp-servers.mdx +++ b/docs/toolhive/guides-cli/run-mcp-servers.mdx @@ -65,6 +65,27 @@ Use `thv search ` or `thv registry list` to discover available servers. ::: +### Run registry groups + +If you use a [custom registry](./registry.md#use-a-custom-registry) that +includes groups, you can run multiple related servers together as a unit. This +is useful when you need several servers for a specific workflow or project: + +```bash +thv group run +``` + +For example, to run all servers in a group called `dev-toolkit`: + +```bash +thv group run dev-toolkit +``` + +Running a group starts all servers defined within that group simultaneously, +saving you from running each server individually. See +[Registry groups](./registry.md#organize-servers-with-registry-groups) for more +information about organizing servers into groups in your custom registry. + :::info[What's happening?] When you run an MCP server from the registry, ToolHive handles different server diff --git a/docs/toolhive/tutorials/custom-registry.mdx b/docs/toolhive/tutorials/custom-registry.mdx index 53c812bc..27d2bf9a 100644 --- a/docs/toolhive/tutorials/custom-registry.mdx +++ b/docs/toolhive/tutorials/custom-registry.mdx @@ -80,11 +80,49 @@ Create a new file called `registry.json` and add the following content: } } } - } + }, + "groups": [ + { + "name": "dev-toolkit", + "description": "Essential MCP servers for development workflows", + "servers": { + "fetch-tool": { + "description": "A web content fetching MCP server for development", + "image": "ghcr.io/stackloklabs/gofetch/server:latest", + "status": "Active", + "tier": "Community", + "transport": "streamable-http", + "args": ["--user-agent", "Mozilla/5.0 (compatible;DevBot/1.0)"], + "tags": ["web", "fetch", "dev"], + "tools": ["fetch"], + "permissions": { + "network": { + "outbound": { + "allow_host": [".github.com", ".stackoverflow.com"], + "allow_port": [80, 443] + } + } + } + } + } + } + ] } ``` -This registry defines a single MCP server called `my-fetch` with: +This registry contains two types of server configurations: + +- A standalone MCP server called `my-fetch` in the top-level `servers` section +- A group called `dev-toolkit` containing a `fetch-tool` server + +The `dev-toolkit` group demonstrates how you can organize related servers +together. When you run this group later, you'll be able to start multiple +servers as a single unit—perfect for development workflows or team-specific +toolsets. Notice how the `fetch-tool` server has a different user agent and +network permissions than `my-fetch`, showing how you can customize servers +within groups for specific purposes. + +Your server configurations include everything ToolHive needs to run them: - A description explaining its purpose - The container image to use @@ -93,6 +131,13 @@ This registry defines a single MCP server called `my-fetch` with: - Command-line arguments for customization - Network permissions for security +:::note + +Registry groups are currently supported in the CLI. UI support for browsing and +managing registry groups may not be immediately available in all versions. + +::: + ### Step 2: Configure ToolHive to use your registry Configure ToolHive to use your custom registry. @@ -190,6 +235,15 @@ thv run my-fetch The server should start successfully, demonstrating that your custom registry is working correctly. +Next, run the `dev-toolkit` group: + +```bash +thv group run dev-toolkit +``` + +This starts all servers in the `dev-toolkit` group (in this case, just the +`fetch-tool` server). + @@ -257,11 +311,13 @@ You've successfully: - Created a custom MCP registry following the JSON schema - Configured ToolHive to use your custom registry - Added MCP servers with proper metadata and permissions -- Tested your registry by listing and running servers +- Created groups to organize related servers +- Tested your registry by listing and running both individual servers and groups -You can now maintain your own curated list of MCP servers tailored to your -organization's needs. The registry can include both public servers from -container registries and private servers hosted within your organization. +You can now maintain your own curated list of MCP servers and groups tailored to +your organization's needs, organized into logical groups for different teams or +workflows. The registry can include both public servers from container +registries and private servers hosted within your organization. ## Next steps