Skip to content

Remove registry groups from documentation #938

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
danbarr wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Remove registry groups from documentation #938

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
83 changes: 3 additions & 80 deletions docs/toolhive/guides-cli/registry.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -234,91 +234,14 @@ 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.mdx).
Registry groups organize server definitions within registry files, while runtime
groups organize running server instances for access control.

:::

### Group structure

Groups are defined under `data.groups` in your custom registry. Each group has a
name, description, and an array of servers:

```json
{
"data": {
"servers": [
// Individual servers
],
"groups": [
{
"name": "group-name",
"description": "Description of what this group provides",
"servers": [
// Complete server definitions
]
}
]
}
}
```

See the [registry schema](../reference/registry-schema-upstream.mdx) for the
full server object structure.

### 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

### Full example

For a complete custom registry file with both top-level servers and groups, see
the [Full example](../reference/registry-schema-upstream.mdx#full-example) in
the registry schema reference.

### Use registry servers with groups

You can organize registry servers into runtime groups after running them:

```bash
thv group create dev-toolkit
thv run --group dev-toolkit github
thv run --group dev-toolkit heroku
```

You can pass environment variables and secrets to each server individually:

```bash
thv run --group dev-toolkit --secret github-token,target=GITHUB_PERSONAL_ACCESS_TOKEN github
thv run --group dev-toolkit --secret heroku-key,target=HEROKU_API_KEY heroku
```

Groups provide a convenient way to start multiple related servers with a single
command. See [Group management](./group-management.mdx) for more details on
creating and managing groups.

## Next steps

See [Run MCP servers](./run-mcp-servers.mdx) to run an MCP server from the
registry.

Learn how to [organize servers into groups](./group-management.mdx) to manage
related servers together.

Learn how to [create a custom MCP registry](../tutorials/custom-registry.mdx).

## Related information
Expand Down
43 changes: 0 additions & 43 deletions docs/toolhive/guides-ui/registry.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,49 +54,6 @@ Click on any server in the registry to view detailed information including:
This detailed view helps you understand the server's purpose and capabilities
before adding it to your ToolHive installation.

## 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.

The default ToolHive registry contains only individual servers. To use groups,
configure a [custom registry](../tutorials/custom-registry.mdx) that defines
them.

### Key characteristics

- **Optional**: Groups are entirely optional. You only need a custom registry
with groups if you want to install multiple servers together
- **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
individual servers but with different configurations
- **Flexible membership**: The same server can appear in multiple groups with
different configurations

### Browse and view groups

When you use a custom registry that includes groups, they appear in the registry
grid alongside individual servers. Click on any group to view its name,
description, and a list of all included servers with their descriptions. From
the group details page, you can click **Install group** to begin installation.

### Install a group

To install a group:

1. Click **Install group** to open the wizard
2. Configure each server following the same process as
[installing an individual server](./run-mcp-servers.mdx#configure-the-server)
3. Click **Next** after each server, or **Finish** on the last one

The wizard guides you through each server one at a time, showing your progress
(for example, "Installing server 1 of 3"). After installation, the group appears
in the **MCP Servers** page where you can
[manage the servers together](./group-management.mdx).

## Registry settings

To configure your registry, ToolHive provides a dedicated **Registry** settings
Expand Down
20 changes: 9 additions & 11 deletions docs/toolhive/reference/registry-schema-upstream.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,7 @@
title: Registry JSON schema
description:
JSON schema reference for the ToolHive registry format, which builds on the
official MCP server schema and adds skills, groups, and publisher-provided
metadata.
official MCP server schema and adds skills and publisher-provided metadata.
displayed_sidebar: toolhiveSidebar
---

Expand All @@ -14,15 +13,14 @@ import PublisherProvidedSchema from '@site/static/api-specs/publisher-provided.s
import SkillSchema from '@site/static/api-specs/skill.schema.json';

This is the ToolHive registry schema, built on the official MCP server schema
with ToolHive-specific additions for skills, groups, and publisher-provided
metadata. It defines the structure and constraints for registry entries,
ensuring that all entries conform to a consistent format.

The top-level `data` object holds three arrays: `servers` (objects conforming to
the official MCP server schema), `skills` (objects conforming to the ToolHive
skill schema, documented below), and `groups` (optional groupings). The schema
requires `servers` to be present even when empty, so a skills-only file still
needs `"servers": []`.
with ToolHive-specific additions for skills and publisher-provided metadata. It
defines the structure and constraints for registry entries, ensuring that all
entries conform to a consistent format.

The top-level `data` object holds two arrays: `servers` (objects conforming to
the official MCP server schema) and `skills` (objects conforming to the ToolHive
skill schema, documented below). The schema requires `servers` to be present
even when empty, so a skills-only file still needs `"servers": []`.

:::info

Expand Down