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 registry wraps the official MCP server schema, which is documented separately below.

info

ToolHive also supports the ToolHive-native registry format, which is used by the built-in registry. Both formats work with custom file-based registries and the ToolHive Registry Server.

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/main/pkg/registry/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

The metadata object can include an optional kubernetes nested object with fields like kind, namespace, name, uid, image, and transport. This metadata is only present for servers that were auto-discovered from Kubernetes deployments (MCPServer, MCPRemoteProxy, or VirtualMCPServer resources) by the ToolHive Registry Server.

Loading ....

Full example​

The following example shows a complete registry file with both a container server and a remote server, demonstrating the different ToolHive extensions available for each type:

Example registry file with ToolHive extensions
{
  "$schema": "https://raw.githubusercontent.com/stacklok/toolhive/main/pkg/registry/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,
                  // Optional: Only present when served from ToolHive Registry Server
                  // with auto-discovered Kubernetes deployments
                  "kubernetes": {
                    "kind": "MCPRemoteProxy",
                    "namespace": "mcp-servers",
                    "name": "toolhive-doc-remote",
                    "uid": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d"
                  }
                },
                "status": "Active",
                "tags": [
                  "remote",
                  "docs",
                  "documentation",
                  "help",
                  "search",
                  "stacklok",
                  "support",
                  "toolhive"
                ],
                "tier": "Official",
                "tools": ["query_docs", "get_chunk"]
              }
            }
          }
        }
      }
    ]
  }
}