Add MCP Server

Add MCP Server to ToolHive Registry

Each entry is a server.json file in registries/toolhive/servers/<name>/ following the MCP ServerJSON schema with ToolHive extensions in _meta.

Workflow

1. Determine type: Docker/OCI image → Container (packages). HTTP endpoint → Remote (remotes).
2. Choose name: lowercase, numbers, hyphens only. Append -remote for remote variants.
3. Create directory: mkdir -p registries/toolhive/servers/<name>
4. Gather info if needed: fetch README/docs for tools, transport, env vars, auth.
5. Create icon.svg: service logo, simple, standard SVG format.
6. Create server.json: use templates below.
7. Validate: task catalog:validate && task catalog:build

Minimal Container Template

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
  "name": "io.github.stacklok/<server-name>",
  "description": "Clear, concise one-line description",
  "title": "<Human-Readable Title>",
  "repository": {
    "url": "https://github.com/org/repo",
    "source": "github"
  },
  "version": "1.0.0",
  "packages": [
    {
      "registryType": "oci",
      "identifier": "ghcr.io/org/server:v1.0.0",
      "transport": {
        "type": "stdio"
      }
    }
  ],
  "icons": [
    {
      "src": "https://raw.githubusercontent.com/stacklok/toolhive-registry/main/registries/toolhive/servers/<server-name>/icon.svg",
      "mimeType": "image/svg+xml",
      "sizes": ["any"]
    }
  ],
  "_meta": {
    "io.modelcontextprotocol.registry/publisher-provided": {
      "io.github.stacklok": {
        "ghcr.io/org/server:v1.0.0": {
          "tier": "Community",
          "status": "Active",
          "tags": ["category1", "category2"],
          "tools": ["tool_name"],
          "overview": "## Server Title\n\nA 3-5 sentence markdown description of purpose and capabilities."
        }
      }
    }
  }
}

For complete templates with env vars, permissions, provenance: see references/container-servers.md.

Minimal Remote Template

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
  "name": "io.github.stacklok/<server-name>",
  "description": "Clear, concise one-line description",
  "title": "<Human-Readable Title> (Remote)",
  "repository": {
    "url": "https://github.com/org/repo",
    "source": "github"
  },
  "version": "1.0.0",
  "remotes": [
    {
      "type": "streamable-http",
      "url": "https://api.example.com/mcp"
    }
  ],
  "icons": [
    {
      "src": "https://raw.githubusercontent.com/stacklok/toolhive-registry/main/registries/toolhive/servers/<server-name>/icon.svg",
      "mimeType": "image/svg+xml",
      "sizes": ["any"]
    }
  ],
  "_meta": {
    "io.modelcontextprotocol.registry/publisher-provided": {
      "io.github.stacklok": {
        "https://api.example.com/mcp": {
          "tier": "Community",
          "status": "Active",
          "tags": ["remote", "category1"],
          "tools": ["tool_name"],
          "overview": "## Server Title (Remote)\n\nA 3-5 sentence markdown description of purpose and capabilities."
        }
      }
    }
  }
}

For complete templates with OAuth, custom_metadata: see references/remote-servers.md.

Critical Rules

Auto-Populated Fields (Do NOT Include)

CI workflows automatically populate these — omit from new entries:

• metadata.stars, metadata.pulls, metadata.last_updated
• tool_definitions (full MCP Tool objects with inputSchema)

The tools list is also auto-updated by CI on PR, but include your best-effort list in new entries.

Information Gathering

When the user provides only a URL or incomplete details:

1. Repository README: tools, env vars, auth, quick start
2. Official docs: transport, OAuth flows, API specs
3. Container registry: image references, versions

Extract: tool names, description, transport type, env vars, auth method, network hosts.

Validation

# Validate schema compliance
task catalog:validate

# Build full registry
task catalog:build

# Verify entry in output
jq '.data.servers[] | select(.name == "io.github.stacklok/<name>")' build/toolhive/registry-upstream.json

Reference Examples

Study existing entries for patterns:

• Container, stdio: registries/toolhive/servers/github/server.json
• Container, streamable-http: registries/toolhive/servers/sqlite/server.json
• Remote, Official: registries/toolhive/servers/semgrep-remote/server.json
• Remote, OAuth: registries/toolhive/servers/github-remote/server.json

See Also

• references/container-servers.md — Full container template, transport variants, env vars, provenance, permissions
• references/remote-servers.md — Full remote template, OAuth configuration
• references/field-reference.md — All field details, overview format, network permissions, troubleshooting
• references/examples.md — Real-world patterns from the registry (heroku, sqlite, semgrep-remote, github-remote)