Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
17 changes: 8 additions & 9 deletions docs/toolhive/guides-cli/registry.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -137,10 +137,10 @@ organizations that want to maintain their own private registry of MCP servers.
ToolHive supports two types of custom registries:

- **File-based registries**: JSON files that follow the
[upstream registry schema](../reference/registry-schema-upstream.mdx)
[ToolHive registry schema](../reference/registry-schema-upstream.mdx)
- **API-based registries**: REST API endpoints that implement the
[MCP Registry API specification](../guides-registry/index.mdx), which use the
[upstream registry schema](../reference/registry-schema-upstream.mdx)
[ToolHive registry schema](../reference/registry-schema-upstream.mdx)
Comment thread
rdimitrov marked this conversation as resolved.

:::warning[Legacy format no longer accepted]

Expand All @@ -154,7 +154,7 @@ thv registry convert --in registry.json --in-place
```

The conversion is lossless: every ToolHive-specific field is mapped to a
publisher-provided extension on the corresponding upstream server entry.
publisher-provided extension on the corresponding MCP server entry.

:::

Expand Down Expand Up @@ -273,8 +273,8 @@ name, description, and an array of servers:
}
```

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

### Key characteristics

Expand All @@ -289,10 +289,9 @@ for the full server object structure.

### Full example

For a complete custom registry file with both top-level servers and groups in
the upstream format, see the
[Full example](../reference/registry-schema-upstream.mdx#full-example) in the
upstream registry schema reference.
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.
Comment thread
rdimitrov marked this conversation as resolved.

### Use registry servers with groups

Expand Down
4 changes: 2 additions & 2 deletions docs/toolhive/guides-registry/configuration.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -97,8 +97,8 @@ Kubernetes lease name suffixes for leader election.

## Registry data format

The Registry Server reads registry data in the official
[upstream MCP registry format](../reference/registry-schema-upstream.mdx). All
The Registry Server reads registry data in the
[ToolHive registry format](../reference/registry-schema-upstream.mdx). All
synced sources (Git, API, and File) must provide data in this format. For a
walkthrough of what the file looks like and how to land changes in a Git
repository, see [Publish MCP servers](./publish-servers.mdx).
Comment thread
rdimitrov marked this conversation as resolved.
Expand Down
2 changes: 1 addition & 1 deletion docs/toolhive/guides-registry/deploy-operator.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -827,7 +827,7 @@ Common causes include:
- **Source unavailable**: Git repository, API endpoint, or file is inaccessible
- **Invalid JSON format**: Registry file contains invalid JSON
- **Schema mismatch**: The data does not conform to the
[upstream MCP registry schema](../reference/registry-schema-upstream.mdx)
[ToolHive registry schema](../reference/registry-schema-upstream.mdx)
- **Filter too restrictive**: Filters may be excluding all servers

</details>
7 changes: 4 additions & 3 deletions docs/toolhive/guides-registry/intro.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -118,7 +118,8 @@ The server supports five source types:

1. **Managed** - A fully-managed MCP source
- Ideal for hosting private MCP server catalogs
- Automatically exposes entries following upstream MCP Registry format
- Automatically exposes entries following the MCP Registry format with
ToolHive-specific extensions
- Supports publishing MCP servers and skills via the `/v1/entries` admin API

2. **Upstream API** - Sync from upstream MCP Registry APIs
Expand All @@ -135,12 +136,12 @@ The server supports five source types:

4. **Git** - Clone and sync from Git repositories
- Supports branch, tag, or commit pinning
- Syncs both MCP servers and skills (upstream format)
- Syncs both MCP servers and skills
- Does not support publishing

5. **File** - Read from filesystem
- Ideal for local development and testing
- Syncs both MCP servers and skills (upstream format)
- Syncs both MCP servers and skills
- Does not support publishing

## Registry Server and the rest of ToolHive
Expand Down
24 changes: 12 additions & 12 deletions docs/toolhive/guides-registry/publish-servers.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -28,8 +28,8 @@ a `skill` payload instead of a `server` payload.
## Registry file format

Git and file sources both read a single JSON file in the
[upstream MCP registry format](../reference/registry-schema-upstream.mdx). The
file has top-level `version` and `meta` fields, plus a `data` object that holds
[ToolHive registry format](../reference/registry-schema-upstream.mdx). The file
has top-level `version` and `meta` fields, plus a `data` object that holds
`servers` and optionally `skills` arrays. A single file can carry servers,
skills, or both:

Expand Down Expand Up @@ -99,13 +99,13 @@ skills, or both:
### Required fields

Each entry in the `data.servers` array needs the following keys, per the
upstream schema:
registry schema:

- `name`: reverse-DNS identifier (for example, `io.github.acme/deploy-helper`).
This is the unique key for the entry.
- `description`: short text displayed in listings.
- `version`: the version this entry represents. Must follow the rules in the
upstream schema.
registry schema.
- Either `packages` (for servers distributed as container images or other
package types) or `remotes` (for remote MCP servers accessed by URL).

Expand All @@ -114,9 +114,9 @@ at least one `packages` entry referencing the skill's Git repository or OCI
artifact. See [Manage skills](./skills.mdx) for the full skill-specific field
reference and the managed-source admin API for skills.

See the [upstream registry schema](../reference/registry-schema-upstream.mdx)
for the full field catalog, including optional metadata, tool definitions, and
the ToolHive extensions under
See the [registry schema](../reference/registry-schema-upstream.mdx) for the
full field catalog, including optional metadata, tool definitions, and the
ToolHive extensions under
`_meta["io.modelcontextprotocol.registry/publisher-provided"]`.

### Add the `$schema` property
Expand Down Expand Up @@ -189,7 +189,7 @@ source (see

### Validate before committing

Validate the file against the upstream schema locally before opening a PR. Any
Validate the file against the registry schema locally before opening a PR. Any
JSON Schema validator works. For a quick check with
[`check-jsonschema`](https://github.com/python-jsonschema/check-jsonschema):

Expand Down Expand Up @@ -276,8 +276,8 @@ curl -X POST \

Required fields in the `server` object: `name`, `description`, `version`, and
either `packages` or `remotes`. See the
[upstream registry schema](../reference/registry-schema-upstream.mdx) for the
full structure and the optional ToolHive extensions.
[registry schema](../reference/registry-schema-upstream.mdx) for the full
structure and the optional ToolHive extensions.

A successful response returns `201 Created` with the published server. If the
version already exists, the server returns `409 Conflict`.
Expand Down Expand Up @@ -364,8 +364,8 @@ for the authorization rules.

## Related information

- [Upstream registry JSON schema](../reference/registry-schema-upstream.mdx) -
the full structure and validation rules for server and skill entries
- [Registry JSON schema](../reference/registry-schema-upstream.mdx) - the full
structure and validation rules for server and skill entries
- [Registry Server API reference](../reference/registry-api.mdx) - request and
response schemas for every endpoint
- [Configure sources and registries](./configuration.mdx) - source types, sync
Expand Down
4 changes: 2 additions & 2 deletions docs/toolhive/guides-registry/quickstart.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ ToolHive CLI and UI, see the [Introduction](./intro.mdx) for a comparison.
- How to install the ToolHive Operator, which bundles the `MCPRegistry` CRD
- How to deploy a minimal PostgreSQL database for the Registry Server
- How to define registry data in a ConfigMap using the
[upstream MCP registry format](../reference/registry-schema-upstream.mdx)
[ToolHive registry format](../reference/registry-schema-upstream.mdx)
- How to create an `MCPRegistry` resource that reads from that ConfigMap
- How to query the Registry API

Expand Down Expand Up @@ -184,7 +184,7 @@ the Registry Server pod and points the server at it automatically when you set

Define registry data in a ConfigMap. The Registry Server reads it through a
file-based source. The ConfigMap uses the
[upstream MCP registry format](../reference/registry-schema-upstream.mdx) with a
[ToolHive registry format](../reference/registry-schema-upstream.mdx) with a
single example server entry:

```yaml title="registry-data.yaml"
Expand Down
2 changes: 1 addition & 1 deletion docs/toolhive/guides-registry/skills.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ Skills can come from two paths:
- **Publish to a managed source via the admin API** (covered in depth below).
Good for programmatic or UI-driven publishing with per-version control.
- **Sync from external sources** (Git, upstream API, or file) that contain
skills in the upstream registry format. Good for catalogs that live in a
skills in the ToolHive registry format. Good for catalogs that live in a
repository with code review and CI.

For the file-based path, the registry JSON format is identical to the one used
Expand Down
4 changes: 2 additions & 2 deletions docs/toolhive/reference/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -72,8 +72,8 @@ tutorials, see the individual product sections.
item={{
type: 'link',
href: '/toolhive/reference/registry-schema-upstream',
label: 'Upstream registry JSON schema',
description: 'JSON schema for the upstream MCP registry format.',
label: 'Registry JSON schema',
description: 'JSON schema for the ToolHive registry format.',
}}
/>

Expand Down
15 changes: 7 additions & 8 deletions docs/toolhive/reference/registry-schema-upstream.mdx
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
title: Upstream registry JSON schema
title: Registry JSON schema
Comment thread
rdimitrov marked this conversation as resolved.
description:
JSON schema reference for the ToolHive registry format, which builds on the
official MCP server schema and adds skills, groups, and publisher-provided
Expand Down Expand Up @@ -27,10 +27,9 @@ needs `"servers": []`.
:::info

The CLI, UI, and [Registry Server](/toolhive/guides-registry/intro) all consume
this upstream format. The legacy ToolHive-native registry format is no longer
accepted by `thv config set-registry` or by remote registries; migrate any
existing custom registry file with
[`thv registry convert`](./cli/thv_registry_convert.md).
this format. The legacy ToolHive-native registry format is no longer accepted by
`thv config set-registry` or by remote registries; migrate any existing custom
registry file with [`thv registry convert`](./cli/thv_registry_convert.md).

:::

Expand All @@ -57,9 +56,9 @@ official MCP server schema:

## ToolHive extensions schema

ToolHive extends the upstream MCP server schema with additional metadata to
support features like container configuration, authentication, and
categorization. These extensions are stored in the
ToolHive extends the MCP server schema with additional metadata to support
features like container configuration, authentication, and categorization. These
extensions are stored in the
`_meta['io.modelcontextprotocol.registry/publisher-provided']` property of each
server definition.

Expand Down
4 changes: 2 additions & 2 deletions docs/toolhive/tutorials/custom-registry.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -395,8 +395,8 @@ registries (public or private) as well as remote servers hosted at a URL.
registry with authentication, multiple data sources, and automatic
synchronization
- Explore the full
[upstream registry schema reference](../reference/registry-schema-upstream.mdx)
to understand all available configuration options
[registry schema reference](../reference/registry-schema-upstream.mdx) to
understand all available configuration options
- Learn about [custom permissions](../guides-cli/custom-permissions.mdx) for
fine-grained security control
- Set up [secrets management](../guides-cli/secrets-management.mdx) for servers
Expand Down
2 changes: 1 addition & 1 deletion docusaurus.config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -304,7 +304,7 @@ const config: Config = {
to: 'toolhive/reference/registry-api',
},
{
label: 'Upstream registry schema',
label: 'Registry schema',
to: 'toolhive/reference/registry-schema-upstream',
},
],
Expand Down