Skip to main content

Upstream registry JSON schema

This is the JSON schema for the official upstream MCP registry format. 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). Both are documented below. A single file can carry servers, skills, or both.

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 packages references that point at the skill's Git repository or OCI artifact. See Manage skills for the full field reference and publishing lifecycle, and the authoritative schema at skill.schema.json.

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"
          }
        ]
      }
    ]
  }
}