ToolHive

https://docs.stacklok.com/toolhive
Admin
ToolHive simplifies the secure deployment and management of Model Context Protocol (MCP) servers,...
Tokens:677,049
Snippets:5,785
Trust Score:8.3
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### Install a skill by name (example)

Source: https://docs.stacklok.com/toolhive/guides-cli/skills-management

Example of installing the `toolhive-cli-user` skill by name from the registry.

```bash
thv skill install toolhive-cli-user
```

--------------------------------

### Run and inspect a server example

Source: https://docs.stacklok.com/toolhive/guides-cli/test-mcp-servers

Example showing how to start a server with `thv run fetch` and then inspect it with `thv inspector fetch`. The output displays the Inspector UI URL with the server details pre-populated.

```bash
thv run fetch

thv inspector fetch
```

```text
2:52PM	INFO	Pulling image: ghcr.io/modelcontextprotocol/inspector:0.17.0

2:52PM	INFO	Pull complete for image: ghcr.io/modelcontextprotocol/inspector:0.17.0

2:52PM	INFO	Waiting for MCP Inspector to be ready...

2:52PM	INFO	Connected to MCP server: fetch

2:52PM	INFO	Inspector UI is now available at http://localhost:6274?transport=streamable-http&serverUrl=http://host.docker.internal:21309/mcp&MCP_PROXY_AUTH_TOKEN=<RANDOM_TOKEN>
```

--------------------------------

### Run automated setup with Task

Source: https://docs.stacklok.com/toolhive/guides-k8s/quickstart

Run the automated setup that creates the kind cluster, installs an nginx ingress controller, and deploys the latest ToolHive operator image.

```bash
task kind-with-toolhive-operator
```

--------------------------------

### Example output of thv client status

Source: https://docs.stacklok.com/toolhive/guides-cli/quickstart

Example output showing a registered VS Code client with installation and registration status marked as 'Yes'.

```text
┌────────────────┬───────────┬────────────┐
│ CLIENT TYPE    │ INSTALLED │ REGISTERED │
├────────────────┼───────────┼────────────┤
│ vscode         │ ✅ Yes    │ ✅ Yes     │
└────────────────┴───────────┴────────────┘
```

--------------------------------

### thv client setup command synopsis

Source: https://docs.stacklok.com/toolhive/reference/cli/thv_client_setup

Shows the basic usage of the thv client setup command. Use this command to interactively select and register installed but unregistered MCP clients.

```bash
thv client setup [flags]
```

--------------------------------

### Get specific plugin version - URL example

Source: https://docs.stacklok.com/toolhive/reference/registry-api

Example URL for the endpoint using localhost:8080. Replace the path parameters with actual values.

```http
http://localhost:8080/registry/{registryName}/v0.1/x/dev.toolhive/plugins/{namespace}/{name}/versions/{version}
```

--------------------------------

### Expected output of thv version

Source: https://docs.stacklok.com/toolhive/guides-cli/quickstart

Example output from the `thv version` command, confirming the installation and showing version details.

```text
ToolHive v0.1.1

Commit: 18956ca1710e11c9952d13a8dde039d5d1d147d6

Built: 2025-06-30 13:59:34 UTC

Go version: go1.24.1

Platform: darwin/arm64
```

--------------------------------

### Example URL for listing plugin versions

Source: https://docs.stacklok.com/toolhive/reference/registry-api

Example URL using localhost:8080 as the base host. Replace path parameters with actual values.

```http
http://localhost:8080/registry/{registryName}/v0.1/x/dev.toolhive/plugins/{namespace}/{name}/versions
```

--------------------------------

### thv client setup options

Source: https://docs.stacklok.com/toolhive/reference/cli/thv_client_setup

Lists the options available for the thv client setup command. The -h, --help flag displays help for the setup command.

```bash
  -h, --help   help for setup
```

--------------------------------

### thv start command synopsis

Source: https://docs.stacklok.com/toolhive/reference/cli/thv_start

Shows the basic syntax for the thv start command. Use it to start or resume a tooling server, optionally specifying a workload name.

```bash
thv start [workload-name] [flags]
```

--------------------------------

### Install the chart with helm upgrade --install

Source: https://docs.stacklok.com/toolhive/guides-registry/deploy-helm

Installs or upgrades the registry server chart from its OCI registry into the toolhive-system namespace, using values.yaml and waiting up to 3 minutes.

```bash
helm upgrade --install registry-server \
  oci://ghcr.io/stacklok/toolhive-registry-server \
  -n toolhive-system \
  -f values.yaml \
  --wait --timeout=3m
```

--------------------------------

### GET /registry/{registryName}/v0.1/servers/{serverName}/versions/{version} - 200 Response Sample

Source: https://docs.stacklok.com/toolhive/reference/registry-api

Example JSON response for a successful request (HTTP 200). Shows the structure of the server metadata, including the _meta object, server details, package arguments, and registry information. Use this to understand the expected response format when retrieving a specific server version.

```json
{
  "_meta": {
    "io.modelcontextprotocol.registry/official": {
      "isLatest": true,
      "publishedAt": "2019-08-24T14:15:22Z",
      "status": "active",
      "statusChangedAt": "2019-08-24T14:15:22Z",
      "statusMessage": "string",
      "updatedAt": "2019-08-24T14:15:22Z"
    }
  },
  "server": {
    "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
    "_meta": {
      "io.modelcontextprotocol.registry/publisher-provided": {
        "property1": null,
        "property2": null
      }
    },
    "description": "MCP server providing weather data and forecasts via OpenWeatherMap API",
    "icons": [
      {
        "mimeType": "image/png",
        "sizes": ["string"],
        "src": "https://example.com/icon.png",
        "theme": "string"
      }
    ],
    "name": "io.github.user/weather",
    "packages": [
      {
        "environmentVariables": [
          {
            "choices": ["string"],
            "default": "string",
            "description": "string",
            "format": "string",
            "isRequired": true,
            "isSecret": true,
            "name": "SOME_VARIABLE",
            "placeholder": "string",
            "value": "string",
            "variables": {
              "property1": {
                "choices": ["string"],
                "default": "string",
                "description": "string",
                "format": "string",
                "isRequired": true,
                "isSecret": true,
                "placeholder": "string",
                "value": "string"
              },
              "property2": {
                "choices": ["string"],
                "default": "string",
                "description": "string",
                "format": "string",
                "isRequired": true,
                "isSecret": true,
                "placeholder": "string",
                "value": "string"
              }
            }
          }
        ],
        "fileSha256": "fe333e598000ae021bd27117db32ec69af7f507ba7a63c90638ff633ce",
        "identifier": "@modelcontextprotocol/server-brave-search",
        "packageArguments": [
          {
            "choices": ["string"],
            "default": "string",
            "description": "string",
            "format": "string",
            "isRepeated": true,
            "isRequired": true,
            "isSecret": true,
            "name": "--port",
            "placeholder": "string",
            "type": "positional",
            "value": "string",
            "valueHint": "file_path",
            "variables": {
              "property1": {
                "choices": ["string"],
                "default": "string",
                "description": "string",
                "format": "string",
                "isRequired": true,
                "isSecret": true,
                "placeholder": "string",
                "value": "string"
              },
              "property2": {
                "choices": ["string"],
                "default": "string",
                "description": "string",
                "format": "string",
                "isRequired": true,
                "isSecret": true,
                "placeholder": "string",
                "value": "string"
              }
            }
          }
        ],
        "registryBaseUrl": "https://registry.npmjs.org",
        "registryType": "npm",
        "runtimeArguments": [
          {
            "choices": ["string"],
            "default": "string",
            "description": "string",
            "format": "string",
            "isRepeated": true,
            "isRequired": true,
            "isSecret": true,
            "name": "--port",
            "placeholder": "string",
            "type": "positional",
            "value": "string",
            "valueHint": "file_path",
            "variables": {
              "property1": {
                "choices": ["string"],
                "default": "string",
                "description": "string",
                "format": "string",
                "isRequired": true,
                "isSecret": true,
                "placeholder": "string",
                "value": "string"
              },
              "property2": {
                "choices": ["string"],
                "default": "string",
                "description": "string",
                "format": "string",
                "isRequired": true,
                "isSecret": true,
                "placeholder": "string",
                "value": "string"
              }
            }
          }
        ]
      }
    ]
  }
}
```

--------------------------------

### Publish Entry - Request Body Example

Source: https://docs.stacklok.com/toolhive/reference/registry-api

Example request body for publishing a new entry. The schema requires exactly one of 'server', 'skill', or 'plugin' to be provided. The example shows an empty object, but the actual payload must contain one of those fields.

```json
{ }
```

--------------------------------

### List Sources - 200 Response Example

Source: https://docs.stacklok.com/toolhive/reference/registry-api

Example JSON response for a successful 200 response when listing all sources. The response contains a 'sources' array with objects including claims, creation metadata, filter configuration, source configuration, sync status, and timestamps.

```json
{
  "sources": [
    {
      "claims": {
        "property1": null,
        "property2": null
      },
      "createdAt": "string",
      "creationType": "API",
      "filterConfig": {
        "names": {
          "exclude": [
            "string"
          ],
          "include": [
            "string"
          ]
        },
        "tags": {
          "exclude": [
            "string"
          ],
          "include": [
            "string"
          ]
        }
      },
      "name": "string",
      "sourceConfig": null,
      "sourceType": "git",
      "syncSchedule": "string",
      "syncStatus": {
        "attemptCount": 0,
        "lastAttempt": "string",
        "lastSyncTime": "string",
        "message": "string",
        "phase": "string",
        "pluginCount": 0,
        "serverCount": 0,
        "skillCount": 0
      },
      "type": "string",
      "updatedAt": "string"
    }
  ]
}
```

--------------------------------

### Response sample for 200 (application/json)

Source: https://docs.stacklok.com/toolhive/reference/registry-api

Example JSON response for a successful request. Contains metadata, server details, and package arguments.

```json
{
  "metadata": {
    "count": 0,
    "nextCursor": "string"
  },
  "servers": [
    {
      "_meta": {
        "io.modelcontextprotocol.registry/official": {
          "isLatest": true,
          "publishedAt": "2019-08-24T14:15:22Z",
          "status": "active",
          "statusChangedAt": "2019-08-24T14:15:22Z",
          "statusMessage": "string",
          "updatedAt": "2019-08-24T14:15:22Z"
        }
      },
      "server": {
        "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
        "_meta": {
          "io.modelcontextprotocol.registry/publisher-provided": {
            "property1": {
              "choices": [],
              "default": null,
              "description": null,
              "format": null,
              "isRequired": null,
              "isSecret": null,
              "placeholder": null,
              "value": null
            },
            "property2": {
              "choices": [],
              "default": null,
              "description": null,
              "format": null,
              "isRequired": null,
              "isSecret": null,
              "placeholder": null,
              "value": null
            }
          }
        },
        "description": "MCP server providing weather data and forecasts via OpenWeatherMap API",
        "icons": [
          {
            "mimeType": "image/png",
            "sizes": ["string"],
            "src": "https://example.com/icon.png",
            "theme": "string"
          }
        ],
        "name": "io.github.user/weather",
        "packages": [
          {
            "environmentVariables": [
              {
                "choices": ["string"],
                "default": "string",
                "description": "string",
                "format": "string",
                "isRequired": true,
                "isSecret": true,
                "name": "SOME_VARIABLE",
                "placeholder": "string",
                "value": "string",
                "variables": {
                  "property1": {
                    "choices": [],
                    "default": null,
                    "description": null,
                    "format": null,
                    "isRequired": null,
                    "isSecret": null,
                    "placeholder": null,
                    "value": null
                  },
                  "property2": {
                    "choices": [],
                    "default": null,
                    "description": null,
                    "format": null,
                    "isRequired": null,
                    "isSecret": null,
                    "placeholder": null,
                    "value": null
                  }
                }
              }
            ],
            "fileSha256": "fe333e598595000ae021bd17db32ec69af6987f507ba7a63c90638ff633ce",
            "identifier": "@modelcontextprotocol/server-brave-search",
            "packageArguments": [
              {
                "choices": ["string"],
                "default": "string",
                "description": "string",
                "format": "string",
                "isRepeated": true,
                "isRequired": true,
                "isSecret": true,
                "name": "--port",
                "placeholder": "string",
                "type": "positional",
                "value": "string",
                "valueHint": "file_path",
                "variables": {
                  "property1": {
                    "choices": [],
                    "default": null,
                    "description": null,
                    "format": null,
                    "isRequired": null,
                    "isSecret": null,
                    "placeholder": null,
                    "value": null
                  },
                  "property2": {
                    "choices": [],
                    "default": null,
                    "description": null,
                    "format": null,
                    "isRequired": null,
                    "isSecret": null,
                    "placeholder": null,
                    "value": null
                  }
                }
              }
            ],
            "registryBaseUrl": "https://registry.npmjs.org",
            "registryType": "npm",
            "runtimeArguments": [
              {
                "choices": ["string"],
                "default": "string",
                "description": "string"
              }
            ]
          }
        ]
      }
    }
  ]
}
```

--------------------------------

### HTTP request URL

Source: https://docs.stacklok.com/toolhive/reference/registry-api

Example URL for the skill versions endpoint.

```http
http://localhost:8080/registry/{registryName}/v0.1/x/dev.toolhive/skills/{namespace}/{name}/versions
```

--------------------------------

### 200 Response sample

Source: https://docs.stacklok.com/toolhive/reference/registry-api

Example JSON response for a successful request.

```json
{
  "metadata": {
    "count": 0,
    "nextCursor": "string"
  },
  "skills": [
    {
      "_meta": {
        "property1": null,
        "property2": null
      },
      "allowedTools": [
        "string"
      ],
      "compatibility": "string",
      "description": "string",
      "icons": [
        {
          "label": "string",
          "size": "string",
          "src": "string",
          "type": "string"
        }
      ],
      "license": "string",
      "metadata": {
        "property1": null,
        "property2": null
      },
      "name": "string",
      "namespace": "string",
      "packages": [
        {
          "commit": "string",
          "digest": "string",
          "identifier": "string",
          "mediaType": "string",
          "ref": "string",
          "registryType": "string",
          "subfolder": "string",
          "url": "string"
        }
      ],
      "provenance": {
        "attestation": {
          "predicate": null,
          "predicate_type": "string"
        },
        "cert_issuer": "string",
        "repository_ref": "string",
        "repository_uri": "string",
        "runner_environment": "string",
        "signer_identity": "string",
        "sigstore_url": "string"
      },
      "repository": {
        "type": "string",
        "url": "string"
      },
      "status": "string",
      "title": "string",
      "version": "string"
    }
  ]
}
```

--------------------------------

### MCPRemoteProxy YAML example

Source: https://docs.stacklok.com/toolhive/reference/crds/mcpremoteproxy

Example manifest for an MCPRemoteProxy resource. The spec includes a remoteUrl pointing to the remote MCP server. The allowPrivateEndpoint field defaults to false, and loopback, link-local, cloud-metadata, and kubernetes.default endpoints remain blocked regardless of this setting.

```yaml
apiVersion: toolhive.stacklok.dev/v1beta1

kind: MCPRemoteProxy

metadata:

  name: my-mcpremoteproxy

  namespace: default

spec:

  remoteUrl: https://example.com
```

--------------------------------

### VirtualMCPServer manifest example

Source: https://docs.stacklok.com/toolhive/reference/crds/virtualmcpserver

Example YAML manifest for a VirtualMCPServer resource. It references an MCPGroup via spec.groupRef.name and sets incomingAuth.type to 'anonymous'.

```yaml
apiVersion: toolhive.stacklok.dev/v1beta1

kind: VirtualMCPServer

metadata:

  name: my-virtualmcpserver

  namespace: default

spec:

  groupRef:

    name: <string>

  incomingAuth:

    type: anonymous
```

--------------------------------

### Full upstream registry JSON example

Source: https://docs.stacklok.com/toolhive/reference/registry-schema-upstream

Complete upstream registry JSON example showing the schema, version, metadata, and data sections. It includes two server entries (osv and toolhive-doc-mcp-remote) with their packages/remotes and publisher-provided metadata, plus a skills entry for code-review. Use this as a template for constructing or validating an upstream registry file.

```json
{
  "$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"
          }
        ]
      }
    ]
  }
}
```

--------------------------------

### GET /registry/{registryName}/v0.1/x/dev.toolhive/plugins/{namespace}/{name}

Source: https://docs.stacklok.com/toolhive/reference/registry-api

Get the latest version of a plugin by namespace and name. This endpoint requires Bearer authentication and returns plugin details.

```APIDOC
## GET /registry/{registryName}/v0.1/x/dev.toolhive/plugins/{namespace}/{name}

### Description
Get the latest version of a plugin by namespace and name.

### Method
GET

### Endpoint
/registry/{registryName}/v0.1/x/dev.toolhive/plugins/{namespace}/{name}

### Parameters
#### Path Parameters
- **registryName** (string) - Required - Registry name
- **namespace** (string) - Required - Plugin namespace (reverse-DNS)
- **name** (string) - Required - Plugin name

### Authorizations
_BearerAuth_

### Response
#### Success Response (200)
Plugin details

#### Response Example
{
  "_meta": {
    "property1": null,
    "property2": null
  },
  "description": "string",
  "icons": [
    {
      "label": "string",
      "size": "string",
      "src": "string",
      "type": "string"
    }
  ],
  "license": "string",
  "metadata": {
    "property1": null,
    "property2": null
  },
  "name": "string",
  "namespace": "string",
  "packages": [
    {
      "commit": "string",
      "digest": "string",
      "identifier": "string",
      "mediaType": "string",
      "ref": "string",
      "registryType": "string",
      "subfolder": "string",
      "url": "string"
    }
  ],
  "repository": {
    "type": "string",
    "url": "string"
  },
  "status": "string",
  "title": "string",
  "version": "string"
}

#### Error Responses
- **400** - Bad request
- **404** - Plugin not found
- **500** - Internal server error
```

--------------------------------

### GET /registry/{registryName}/v0.1/x/dev.toolhive/skills/{namespace}/{name}/versions

Source: https://docs.stacklok.com/toolhive/reference/registry-api

Lists all versions of a skill. Requires Bearer authentication and path parameters for registry name, namespace, and skill name.

```APIDOC
## GET /registry/{registryName}/v0.1/x/dev.toolhive/skills/{namespace}/{name}/versions

### Description
List all versions of a skill.

### Method
GET

### Endpoint
/registry/{registryName}/v0.1/x/dev.toolhive/skills/{namespace}/{name}/versions

### Parameters
#### Path Parameters
- **registryName** (string) - Required - Registry name
- **namespace** (string) - Required - Skill namespace (reverse-DNS)
- **name** (string) - Required - Skill name

### Authorizations
BearerAuth

### Response
#### Success Response (200)
List of skill versions

#### Response Example
{
  "metadata": {
    "count": 0,
    "nextCursor": "string"
  },
  "skills": [
    {
      "_meta": {
        "property1": null,
        "property2": null
      },
      "allowedTools": [
        "string"
      ],
      "compatibility": "string",
      "description": "string",
      "icons": [
        {
          "label": "string",
          "size": "string",
          "src": "string",
          "type": "string"
        }
      ],
      "license": "string",
      "metadata": {
        "property1": null,
        "property2": null
      },
      "name": "string",
      "namespace": "string",
      "packages": [
        {
          "commit": "string",
          "digest": "string",
          "identifier": "string",
          "mediaType": "string",
          "ref": "string",
          "registryType": "string",
          "subfolder": "string",
          "url": "string"
        }
      ],
      "provenance": {
        "attestation": {
          "predicate": null,
          "predicate_type": "string"
        },
        "cert_issuer": "string",
        "repository_ref": "string",
        "repository_uri": "string",
        "runner_environment": "string",
        "signer_identity": "string",
        "sigstore_url": "string"
      },
      "repository": {
        "type": "string",
        "url": "string"
      },
      "status": "string",
      "title": "string",
      "version": "string"
    }
  ]
}

#### Error Responses
- **400** - Bad request
- **404** - Skill not found
- **500** - Internal server error
```

--------------------------------

### 200 response sample - Skill details

Source: https://docs.stacklok.com/toolhive/reference/registry-api

Example JSON response for a successful request (HTTP 200). The response contains the full skill details including metadata, packages, provenance, and repository information.

```json
{
  "_meta": {
    "property1": null,
    "property2": null
  },
  "allowedTools": [
    "string"
  ],
  "compatibility": "string",
  "description": "string",
  "icons": [
    {
      "label": "string",
      "size": "string",
      "src": "string",
      "type": "string"
    }
  ],
  "license": "string",
  "metadata": {
    "property1": null,
    "property2": null
  },
  "name": "string",
  "namespace": "string",
  "packages": [
    {
      "commit": "string",
      "digest": "string",
      "identifier": "string",
      "mediaType": "string",
      "ref": "string",
      "registryType": "string",
      "subfolder": "string",
      "url": "string"
    }
  ],
  "provenance": {
    "attestation": {
      "predicate": null,
      "predicate_type": "string"
    },
    "cert_issuer": "string",
    "repository_ref": "string",
    "repository_uri": "string",
    "runner_environment": "string",
    "signer_identity": "string",
    "sigstore_url": "string"
  },
  "repository": {
    "type": "string",
    "url": "string"
  },
  "status": "string",
  "title": "string",
  "version": "string"
}
```

--------------------------------

### GET /registry/{registryName}/v0.1/servers/{serverName}/versions/{version}

Source: https://docs.stacklok.com/toolhive/reference/registry-api

Retrieves detailed information about a specific version of an MCP server from a specific registry. Use the special version 'latest' to get the latest version.

```APIDOC
## GET /registry/{registryName}/v0.1/servers/{serverName}/versions/{version}

### Description
Returns detailed information about a specific version of an MCP server from a specific registry. Use the special version `latest` to get the latest version.

### Method
GET

### Endpoint
/registry/{registryName}/v0.1/servers/{serverName}/versions/{version}

### Parameters
#### Path Parameters
- **registryName** (string) - Required - Registry name
- **serverName** (string) - Required - URL-encoded server name (e.g., \
- **version** (string) - Required - URL-encoded version to retrieve (e.g., \

### Request Example
No request body required.

### Response
#### Success Response (200)
- **Detailed server information** - Detailed server information

#### Response Example
```json
{
  "_meta": {
    "io.modelcontextprotocol.registry/official": {
      "isLatest": true,
      "publishedAt": "2019-08-24T14:15:22Z",
      "status": "active",
      "statusChangedAt": "2019-08-24T14:15:22Z",
      "statusMessage": "string",
      "updatedAt": "2019-08-24T14:15:22Z"
    }
  },
  "server": {
    "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
    "_meta": {
      "io.modelcontextprotocol.registry/publisher-provided": {
        "property1": null,
        "property2": null
      }
    },
    "description": "MCP server providing weather data and forecasts via OpenWeatherMap API",
    "icons": [
      {
        "mimeType": "image/png",
        "sizes": [
          "string"
        ],
        "src": "https://example.com/icon.png",
        "theme": "string"
      }
    ],
    "name": "io.github.user/weather",
    "packages": [
      {
        "environmentVariables": [
          {
            "choices": [
              "string"
            ],
            "default": "string",
            "description": "string",
            "format": "string",
            "isRequired": true,
            "isSecret": true,
            "name": "SOME_VARIABLE",
            "placeholder": "string",
            "value": "string",
            "variables": {
              "property1": {
                "choices": [
                  "string"
                ],
                "default": "string",
                "description": "string",
                "format": "string",
                "isRequired": true,
                "isSecret": true,
                "placeholder": "string",
                "value": "string"
              },
              "property2": {
                "choices": [
                  "string"
                ],
                "default": "string",
                "description": "string",
                "format": "string",
                "isRequired": true,
                "isSecret": true,
                "placeholder": "string",
                "value": "string"
              }
            }
          }
        ],
        "fileSha256": "fe333e598595000ae021bd27117db32ec69af6987f507ba7a63c90638ff633ce",
        "identifier": "@modelcontextprotocol/server-brave-search",
        "packageArguments": [
          {
            "choices": [
              "string"
            ],
            "default": "string",
            "description": "string",
            "format": "string",
            "isRepeated": true,
            "isRequired": true,
            "isSecret": true,
            "name": "--port",
            "placeholder": "string",
            "type": "positional",
            "value": "string",
            "valueHint": "file_path",
            "variables": {
              "property1": {
                "choices": [
                  "string"
                ],
                "default": "string",
                "description": "string",
                "format": "string",
                "isRequired": true,
                "isSecret": true,
                "placeholder": "string",
                "value": "string"
              },
              "property2": {
                "choices": [
                  "string"
                ],
                "default": "string",
                "description": "string",
                "format": "string",
                "isRequired": true,
                "isSecret": true,
                "placeholder": "string",
                "value": "string"
              }
            }
          }
        ],
        "registryBaseUrl": "https://registry.npmjs.org",
        "registryType": "npm",
        "runtimeArguments": [
          {
            "choices": [
              "string"
            ],
            "default": "string",
            "description": "string",
            "format": "string",
            "isRepeated": true,
            "isRequired": true,
            "isSecret": true,
            "name": "--port",
            "placeholder": "string",
            "type": "positional",
            "value": "string",
            "valueHint": "file_path",
            "variables": {
              "property1": {
                "choices": [
                  "string"
                ],
                "default": "string",
                "description": "string",
                "format": "string",
                "isRequired": true,
                "isSecret": true,
                "placeholder": "string",
                "value": "string"
              },
              "property2": {
                "choices": [
                  "string"
                ],
                "default": "string",
                "description": "string",
                "format": "string",
                "isRequired": true,
                "isSecret": true,
                "placeholder": "string",
                "value": "string"
              }
            }
          }
        ]
      }
    ]
  }
}
```

### Error Handling
- **400** - Bad request
- **401** - Unauthorized
- **404** - Server or version not found

```

--------------------------------

### GET /registry/{registryName}/v0.1/servers/{serverName}/versions

Source: https://docs.stacklok.com/toolhive/reference/registry-api

Retrieves all versions of a specific MCP server from a specific registry. Requires BearerAuth. Returns a list of server versions with metadata.

```http
get/registry/{registryName}/v0.1/servers/{serverName}/versions
```

--------------------------------

### GET /v1/sources/{name}

Source: https://docs.stacklok.com/toolhive/reference/registry-api

Retrieves a source by its name. Returns source details including configuration, sync status, and metadata.

```APIDOC
## GET /v1/sources/{name}

### Description
Get a source by name.

### Method
GET

### Endpoint
/v1/sources/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - Source Name

### Response
#### Success Response (200)
Source details

#### Response Example
```json
{
  "claims": {
    "property1": null,
    "property2": null
  },
  "createdAt": "string",
  "creationType": "API",
  "filterConfig": {
    "names": {
      "exclude": ["string"],
      "include": ["string"]
    },
    "tags": {
      "exclude": ["string"],
      "include": ["string"]
    }
  },
  "name": "string",
  "sourceConfig": null,
  "sourceType": "git",
  "syncSchedule": "string",
  "syncStatus": {
    "attemptCount": 0,
    "lastAttempt": "string",
    "lastSyncTime": "string",
    "message": "string",
    "phase": "string",
    "pluginCount": 0,
    "serverCount": 0,
    "skillCount": 0
  },
  "type": "string",
  "updatedAt": "string"
}
```

#### Error Responses
- **400** - Bad request
- **404** - Source not found
- **500** - Internal server error
```

--------------------------------

### GET /registry/{registryName}/v0.1/servers/{serverName}/versions

Source: https://docs.stacklok.com/toolhive/reference/registry-api

Returns all available versions for a specific MCP server from a specific registry. Requires Bearer authentication.

```APIDOC
## GET /registry/{registryName}/v0.1/servers/{serverName}/versions

### Description
Returns all available versions for a specific MCP server from a specific registry.

### Method
GET

### Endpoint
http://localhost:8080/registry/{registryName}/v0.1/servers/{serverName}/versions

### Parameters
#### Path Parameters
- **registryName** (string) - Required - Registry name
- **serverName** (string) - Required - URL-encoded server name (e.g., \"io.github.user/weather\")

### Authorizations
_BearerAuth_

### Responses
#### Success Response (200)
A list of all versions for the server

#### Response Example
{
  "metadata": {
    "count": 0,
    "nextCursor": "string"
  },
  "servers": [
    {
      "_meta": {
        "io.modelcontextprotocol.registry/official": {
          "isLatest": true,
          "publishedAt": "2019-08-24T14:15:22Z",
          "status": "active",
          "statusChangedAt": "2019-08-24T14:15:22Z",
          "statusMessage": "string",
          "updatedAt": "2019-08-24T14:15:22Z"
        }
      },
      "server": {
        "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
        "_meta": {
          "io.modelcontextprotocol.registry/publisher-provided": {
            "property1": null,
            "property2": null
          }
        },
        "description": "MCP server providing weather data and forecasts via OpenWeatherMap API",
        "icons": [
          {
            "mimeType": "image/png",
            "sizes": [
              "string"
            ],
            "src": "https://example.com/icon.png",
            "theme": "string"
          }
        ],
        "name": "io.github.user/weather",
        "packages": [
          {
            "environmentVariables": [
              {
                "choices": [
                  "string"
                ],
                "default": "string",
                "description": "string",
                "format": "string",
                "isRequired": true,
                "isSecret": true,
                "name": "SOME_VARIABLE",
                "placeholder": "string",
                "value": "string",
                "variables": {
                  "property1": {
                    "choices": [],
                    "default": null,
                    "description": null,
                    "format": null,
                    "isRequired": null,
                    "isSecret": null,
                    "placeholder": null,
                    "value": null
                  },
                  "property2": {
                    "choices": [],
                    "default": null,
                    "description": null,
                    "format": null,
                    "isRequired": null,
                    "isSecret": null,
                    "placeholder": null,
                    "value": null
                  }
                }
              }
            ],
            "fileSha256": "fe333e598595000ae021bd27117db32ec69af6987f507ba7a63c90638ff633ce",
            "identifier": "@modelcontextprotocol/server-brave-search",
            "packageArguments": [
              {
                "choices": [
                  "string"
                ],
                "default": "string",
                "description": "string",
                "format": "string",
                "isRepeated": true,
                "isRequired": true,
                "isSecret": true,
                "name": "--port",
                "placeholder": "string",
                "type": "positional",
                "value": "string",
                "valueHint": "file_path",
                "variables": {
                  "property1": {
                    "choices": [],
                    "default": null,
                    "description": null,
                    "format": null,
                    "isRequired": null,
                    "isSecret": null,
                    "placeholder": null,
                    "value": null
                  },
                  "property2": {
                    "choices": [],
                    "default": null,
                    "description": null,
                    "format": null,
                    "isRequired": null,
                    "isSecret": null,
                    "placeholder": null,
                    "value": null
                  }
                }
              }
            ],
            "registryBaseUrl": "https://registry.npmjs.org",
            "registryType": "npm",
            "runtimeArguments": [
              {
                "choices": [
                  "string"
                ],
                "default": "string",
                "description": "string",
                "format": "string",
                "isRequired": true,
                "isSecret": true,
                "name": "--port",
                "placeholder": "string",
                "type": "positional",
                "value": "string",
                "valueHint": "file_path",
                "variables": {
                  "property1": {
                    "choices": [],
                    "default": null,
                    "description": null,
                    "format": null,
                    "isRequired": null,
                    "isSecret": null,
                    "placeholder": null,
                    "value": null
                  },
                  "property2": {
                    "choices": [],
                    "default": null,
                    "description": null,
                    "format": null,
                    "isRequired": null,
                    "isSecret": null,
                    "placeholder": null,
                    "value": null
                  }
                }
              }
            ]
          }
        ]
      }
    }
  ]
}

#### Error Responses
- **400** - Bad request
- **401** - Unauthorized
- **404** - Server not found
```

--------------------------------

### MCPServer YAML example

Source: https://docs.stacklok.com/toolhive/reference/crds/mcpserver

Minimal manifest for an MCPServer resource. The spec requires an image field; other fields like args, audit, authServerRef, and authzConfig are optional.

```yaml
apiVersion: toolhive.stacklok.dev/v1beta1

kind: MCPServer

metadata:

  name: my-mcpserver

  namespace: default

spec:

  image: <string>
```

--------------------------------

### List source entries - Response sample (200)

Source: https://docs.stacklok.com/toolhive/reference/registry-api

Example JSON response for a successful request to list source entries. The response contains an 'entries' array with objects that include 'claims', 'entryType', 'name', and 'versions' fields.

```json
{
  "entries": [
    {
      "claims": {
        "property1": null,
        "property2": null
      },
      "entryType": "string",
      "name": "string",
      "versions": [
        {
          "createdAt": "string",
          "description": "string",
          "title": "string",
          "updatedAt": "string",
          "version": "string"
        }
      ]
    }
  ]
}
```

--------------------------------

### 200 Response - Plugin details JSON

Source: https://docs.stacklok.com/toolhive/reference/registry-api

Example 200 response body for the plugin details endpoint. This is the application/json payload returned on success.

```json
{
  "_meta": {
    "property1": null,
    "property2": null
  },
  "description": "string",
  "icons": [
    {
      "label": "string",
      "size": "string",
      "src": "string",
      "type": "string"
    }
  ],
  "license": "string",
  "metadata": {
    "property1": null,
    "property2": null
  },
  "name": "string",
  "namespace": "string",
  "packages": [
    {
      "commit": "string",
      "digest": "string",
      "identifier": "string",
      "mediaType": "string",
      "ref": "string",
      "registryType": "string",
      "subfolder": "string",
      "url": "string"
    }
  ],
  "repository": {
    "type": "string",
    "url": "string"
  },
  "status": "string",
  "title": "string",
  "version": "string"
}
```
Tokens:
Raw