Upstream registry JSON schema

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": [].

info

The Registry Server only accepts this upstream format. The CLI and UI additionally support the legacy ToolHive-native registry format for their built-in and custom file-based registries.

To use this schema in your own custom registry file, add a $schema property at the top of your JSON file:

{
  "$schema": "https://raw.githubusercontent.com/stacklok/toolhive-core/main/registry/types/data/upstream-registry.schema.json",
  ...
}

Registry schema

Loading ....

MCP server object schema

The servers array in the registry contains objects that conform to the official MCP server schema:

Loading ....

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 _meta['io.modelcontextprotocol.registry/publisher-provided'] property of each server definition.

The available properties vary by server type:

• Container servers (keyed by OCI image reference): permissions, args, provenance, docker_tags, and proxy_port
• Remote servers (keyed by URL): oauth_config and env_vars
• All servers: status, tier, tools, tags, metadata, and custom_metadata

:::note Read-only metadata

The metadata object can include an optional kubernetes nested object with fields like kind, namespace, name, uid, image, and transport. This metadata is automatically added by the ToolHive Registry Server for servers that were auto-discovered from Kubernetes deployments (typically remote servers accessed via Kubernetes-exposed URLs). You should not manually add this field when creating custom registry files.

:::

Loading ....

Skill object schema

The skills array in the registry contains objects that conform to the ToolHive skill schema. Each skill entry declares a namespace, name, and version, along with one or more package references in packages that point at the skill's Git repository or OCI artifact. See Manage skills for the full field reference and publishing lifecycle.

Loading ....

Full example

The following example shows a complete custom registry file with a container server, a remote server, and a skill, demonstrating the different ToolHive extensions you can use when building your own registry:

Example registry file with ToolHive extensions

{
  "$schema": "https://raw.githubusercontent.com/stacklok/toolhive-core/main/registry/types/data/upstream-registry.schema.json",
  "version": "1.0.0",
  "meta": {
    "last_updated": "2026-02-05T16:59:49Z"
  },
  "data": {
    "servers": [
      {
        "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
        "name": "io.github.stacklok/osv",
        "description": "OSV (Open Source Vulnerabilities) database access for querying package and commit vulnerabilities",
        "title": "osv",
        "repository": {
          "url": "https://github.com/StacklokLabs/osv-mcp",
          "source": "github"
        },
        "version": "1.0.0",
        "packages": [
          {
            "registryType": "oci",
            "identifier": "ghcr.io/stackloklabs/osv-mcp/server:0.1.0",
            "transport": {
              "type": "streamable-http",
              "url": "http://localhost:8080"
            }
          }
        ],
        "_meta": {
          "io.modelcontextprotocol.registry/publisher-provided": {
            "io.github.stacklok": {
              "ghcr.io/stackloklabs/osv-mcp/server:0.1.0": {
                "metadata": {
                  "last_updated": "2026-01-30T02:55:46Z",
                  "pulls": 0,
                  "stars": 0
                },
                "permissions": {
                  "network": {
                    "outbound": {
                      "allow_host": ["api.osv.dev"],
                      "allow_port": [443]
                    }
                  }
                },
                "provenance": {
                  "sigstore_url": "tuf-repo-cdn.sigstore.dev",
                  "repository_uri": "https://github.com/StacklokLabs/osv-mcp",
                  "signer_identity": "/.github/workflows/release.yml",
                  "runner_environment": "github-hosted",
                  "cert_issuer": "https://token.actions.githubusercontent.com"
                },
                "status": "Active",
                "tags": ["vulnerability", "security", "osv"],
                "tier": "Community",
                "tools": [
                  "query_vulnerability",
                  "query_vulnerabilities_batch",
                  "get_vulnerability"
                ]
              }
            }
          }
        }
      },
      {
        "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
        "name": "io.github.stacklok/toolhive-doc-mcp-remote",
        "description": "Search ToolHive docs for help with using and contributing to the project (hosted version)",
        "title": "toolhive-doc-mcp-remote",
        "repository": {
          "url": "https://github.com/StacklokLabs/toolhive-doc-mcp",
          "source": "github"
        },
        "version": "1.0.0",
        "remotes": [
          {
            "type": "streamable-http",
            "url": "https://toolhive-doc-mcp.stacklok.dev/mcp"
          }
        ],
        "_meta": {
          "io.modelcontextprotocol.registry/publisher-provided": {
            "io.github.stacklok": {
              "https://toolhive-doc-mcp.stacklok.dev/mcp": {
                "custom_metadata": {
                  "author": "Stacklok",
                  "homepage": "https://github.com/StacklokLabs/toolhive-doc-mcp",
                  "license": "Apache-2.0"
                },
                "metadata": {
                  "last_updated": "2026-01-25T13:39:45Z",
                  "pulls": 0,
                  "stars": 3
                },
                "status": "Active",
                "tags": [
                  "remote",
                  "docs",
                  "documentation",
                  "help",
                  "search",
                  "stacklok",
                  "support",
                  "toolhive"
                ],
                "tier": "Official",
                "tools": ["query_docs", "get_chunk"]
              }
            }
          }
        }
      }
    ],
    "skills": [
      {
        "namespace": "io.github.stacklok",
        "name": "code-review",
        "description": "Performs structured code reviews using best practices",
        "version": "1.0.0",
        "status": "active",
        "license": "Apache-2.0",
        "packages": [
          {
            "registryType": "git",
            "url": "https://github.com/stacklok/skills",
            "ref": "v1.0.0",
            "subfolder": "code-review"
          }
        ]
      }
    ]
  }
}