### Install Skill Response Example (JSON)

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

An example of a successful response (201 Created) when installing a skill. It includes the details of the skill that was installed.

```json
{
  "skill": {
    "clients": [
      "string"
    ],
    "installed_at": "string",
    "metadata": {
      "author": "string",
      "description": "string",
      "name": "string",
      "tags": [
        "string"
      ],
      "version": "string"
    },
    "scope": "user",
    "status": "installed"
  }
}
```

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

### Run ToolHive MCP Server with Authorization

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

These commands demonstrate how to start the MCP server with a specified authorization configuration file. The first example shows a basic setup, while the second combines authorization with OpenID Connect (OIDC) authentication parameters for a more secure environment.

```bash
thv run \
  --authz-config /path/to/authz-config.json \
  <server-name>
```

```bash
thv run \
  --oidc-audience <your-audience> \
  --oidc-client-id <your-client-id> \
  --oidc-issuer <https://your-oidc-issuer.com> \
  --oidc-jwks-url <https://your-oidc-issuer.com/path/to/jwks> \
  --authz-config /path/to/authz-config.json \
  <server-name>
```

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

### Install ToolHive CLI from Binary

Source: https://docs.stacklok.com/toolhive/quickstart

Installs the ToolHive CLI ('thv') by downloading a pre-compiled binary. This involves extracting the archive, moving the binary to a directory in your system's PATH, and making it executable.

```bash
# Extract the archive
tar -xzf toolhive_<version>_<platform>.tar.gz
# Move the binary to a directory in your PATH
sudo mv thv /usr/local/bin/
# Make it executable (if needed)
sudo chmod +x thv
```

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

### Verify ToolHive Installation

Source: https://docs.stacklok.com/toolhive/quickstart

Checks if the ToolHive CLI ('thv') is installed correctly by running the version command. This command outputs the installed version, commit hash, build date, and Go version.

```bash
thv version
```

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

### Install ToolHive CLI using WinGet

Source: https://docs.stacklok.com/toolhive/quickstart

Installs the ToolHive CLI ('thv') on Windows systems using the WinGet package manager. This command directly installs the 'thv' application from the configured repositories.

```powershell
winget install stacklok.thv
```

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

### Automated ToolHive Operator Setup with Task

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

This command automates the setup of a local Kubernetes cluster using kind, installs an nginx ingress controller, and deploys the latest ToolHive operator image. It requires Task to be installed.

```bash
git clone https://github.com/stacklok/toolhive.git
cd toolhive
task kind-with-toolhive-operator
```

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

### Install ToolHive CLI using Homebrew

Source: https://docs.stacklok.com/toolhive/quickstart

Installs the ToolHive CLI ('thv') on macOS and Linux systems using the Homebrew package manager. This command first adds the necessary repository and then installs the tool.

```bash
brew tap stacklok/tap
brew install thv
```

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

### thv client setup

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

Interactively setup and register installed clients.

```APIDOC
## thv client setup

### Description
Interactively setup and register installed clients.

### Method
N/A (CLI command)

### Endpoint
N/A (CLI command)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
thv client setup
```

### Response
#### Success Response (200)
Interactive prompts for client setup and registration.

#### Response Example
```
# Interactive prompts will guide the user through the setup process.
```
```

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

### Run Fetch MCP Server with ToolHive CLI

Source: https://docs.stacklok.com/toolhive/quickstart

Starts the Fetch MCP server by pulling the necessary container image and initiating the server process. It handles image verification, pulling, and background execution. Dependencies include a container runtime like Docker or Podman.

```bash
thv run fetch
```

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

### Run Fetch MCP Server with Custom Proxy Port

Source: https://docs.stacklok.com/toolhive/quickstart

Starts the Fetch MCP server, allowing specification of a custom port for the proxy. This is useful for resolving port conflicts or when the default port is unavailable. Dependencies include a container runtime.

```bash
thv run --proxy-port 8081 fetch
```

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

### Get Information about a Specific MCP Server

Source: https://docs.stacklok.com/toolhive/quickstart

Fetches detailed information about a specific MCP server from the ToolHive registry. This includes details about the tools it provides and any available configuration options.

```bash
thv registry info fetch
```

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

### Troubleshoot Operator Pod Startup (kubectl logs)

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

Retrieves the logs for the toolhive-operator deployment to diagnose issues preventing the operator pod from starting. This is crucial for identifying startup failures.

```bash
kubectl logs -n toolhive-system deployment/toolhive-operator
```

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

### CI/CD Integration Example (GitHub Actions)

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

Provides an example GitHub Actions workflow for automating the build and push of MCP server container images triggered by Git tags. It includes steps for installing ToolHive, logging into a container registry, building, and pushing the image.

```yaml
# Example GitHub Actions workflow
name: Build and Deploy MCP Server
on:
  push:
    tags: ['v*']

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install ToolHive
        uses: StacklokLabs/toolhive-actions/install@v0
        with:
          version: latest

      - name: Log in to Container Registry
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Build MCP server
        run: |
          thv build --tag ghcr.io/${{ github.repository }}/mcp-server:${{ github.ref_name }} \
            uvx://mcp-server-git@${{ github.ref_name }}

      - name: Push to registry
        run: |
          docker push ghcr.io/${{ github.repository }}/mcp-server:${{ github.ref_name }}
```

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

### Register AI Clients with ToolHive CLI

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

Use the `thv client setup` command to automatically discover and register supported AI clients with ToolHive. This command simplifies the process by detecting clients based on their configuration files. After setup, use `thv client status` to view the current state of detected and configured clients.

```bash
thv client setup
thv client status
```

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

### Check ToolHive Client Registration Status

Source: https://docs.stacklok.com/toolhive/quickstart

Displays the registration status of MCP clients managed by ToolHive. It shows whether each client type is installed and if it has been successfully registered with ToolHive.

```bash
thv client status
```

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

### Troubleshoot MCP Server Access (kubectl get service & endpoints)

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

Verifies if the necessary service and endpoints for accessing the MCP server have been created. This is a key step in diagnosing connectivity issues.

```bash
kubectl get service mcp-fetch-proxy -n toolhive-system
kubectl get endpoints mcp-fetch-proxy -n toolhive-system
```

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

### Create Workload Response Example (JSON)

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

An example of a successful response (201 Created) when creating a workload. It returns the name and port of the newly created workload.

```json
{
  "name": "string",
  "port": 0
}
```

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

### Install a skill

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

Installs a skill from a remote source. Requires a JSON request body.

```APIDOC
## POST /api/v1beta/skills/install

### Description
Install a skill from a remote source.

### Method
POST

### Endpoint
/api/v1beta/skills/install

### Parameters
#### Request Body
- **(object)** - Required - Install request body.

### Request Example
```json
{
  "": ""
}
```

### Response
#### Success Response (201)
- **skill** (object) - Details of the installed skill.
  - **clients** (array) - List of clients associated with the skill.
  - **installed_at** (string) - Timestamp when the skill was installed.
  - **metadata** (object) - Metadata about the skill.
    - **author** (string)
    - **description** (string)
    - **name** (string)
    - **tags** (array) - List of tags associated with the skill.
    - **version** (string)
  - **scope** (string) - The scope of the skill installation (e.g., 'user').
  - **status** (string) - The current status of the skill (e.g., 'installed').

#### Error Response (501)
Not Implemented

#### Response Example (201)
```json
{
  "skill": {
    "clients": [
      "string"
    ],
    "installed_at": "string",
    "metadata": {
      "author": "string",
      "description": "string",
      "name": "string",
      "tags": [
        "string"
      ],
      "version": "string"
    },
    "scope": "user",
    "status": "installed"
  }
}
```
```

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

### Install Skill Request and Response Schemas (JSON)

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

Defines the JSON structure for installing a skill, including request payload and successful response. The response contains details about the installed skill.

```json
{
  "installed": true,
  "installed_skill": {
    "clients": [
      "string"
    ],
    "installed_at": "string",
    "metadata": {
      "author": "string",
      "description": "string",
      "name": "string",
      "tags": [
        "string"
      ],
      "version": "string"
    },
    "scope": "user",
    "status": "installed"
  },
  "metadata": {
    "author": "string",
    "description": "string",
    "name": "string",
    "tags": [
      "string"
    ],
    "version": "string"
  }
}
```

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

### List Installed Skills Response Schema (JSON)

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

Defines the JSON structure for the response when listing all installed skills. It returns a list of skill objects, each with installation details.

```json
{
  "skills": [
    {
      "clients": [
        "string"
      ],
      "installed_at": "string",
      "metadata": {
        "author": "string",
        "description": "string",
        "name": "string",
        "tags": [
          "string"
        ],
        "version": "string"
      },
      "scope": "user",
      "status": "installed"
    }
  ]
}
```

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

### Push Skill Response Example (String)

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

An example of a response when pushing a skill. A simple string response is shown, likely indicating success or a status message.

```json
"string"
```

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

### Example: Run Server from Registry

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

Demonstrates running a simple MCP server named 'filesystem' by fetching it from the ToolHive registry.

```bash
# Run a server from the registry
thv run filesystem
```

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

### Register MCP Client with ToolHive

Source: https://docs.stacklok.com/toolhive/quickstart

Sets up and registers an MCP client with ToolHive. This command automatically discovers supported clients on your system and configures them to use ToolHive MCP servers without manual configuration.

```bash
thv client setup
```

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

### List Available MCP Servers in ToolHive Registry

Source: https://docs.stacklok.com/toolhive/quickstart

Retrieves and displays a list of available Model Context Protocol (MCP) servers from the ToolHive registry. The output includes server names, descriptions, tier, stars, and pull counts.

```bash
thv registry list
```

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

### Quick Start MCPRemoteProxy Example

Source: https://docs.stacklok.com/toolhive/guides-k8s/remote-mcp-proxy

A basic configuration for an MCPRemoteProxy suitable for testing and development. It connects to a public MCP specification server and includes example OIDC and authorization configurations.

```yaml
apiVersion: toolhive.stacklok.dev/v1alpha1
kind: MCPRemoteProxy
metadata:
  name: mcp-spec-proxy
  namespace: toolhive-system
spec:
  remoteURL: https://modelcontextprotocol.io/mcp
  port: 8080
  transport: streamable-http

  # For testing - use your IDP's configuration
  oidcConfig:
    type: inline
    inline:
      issuer: https://auth.company.com/realms/test
      audience: mcp-test

  # Simple allow-all policy for testing
  authzConfig:
    type: inline
    inline:
      policies:
        - |
          permit(
            principal,
            action,
            resource
          );

  audit:
    enabled: true

  resources:
    limits:
      cpu: '100m'
      memory: 128Mi
    requests:
      cpu: '50m'
      memory: 64Mi
```

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

### Install ToolHive Operator CRDs with Helm

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

Installs the Custom Resource Definitions (CRDs) for the ToolHive operator using Helm. These CRDs define the 'MCPServer' resource that the operator manages.

```bash
helm upgrade --install toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds
```

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

### Interactive Secrets Provider Setup (CLI)

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

This command initiates an interactive setup process for configuring a secrets provider. It guides the user through selecting from available providers like 'encrypted', '1password', or 'environment', validating the chosen configuration, and ensuring proper initialization. This setup is a prerequisite for using other secrets management functionalities.

```bash
thv secret setup [flags]
```

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

### Verify MCP Server Status with ToolHive CLI

Source: https://docs.stacklok.com/toolhive/quickstart

Lists all running MCP servers managed by ToolHive, displaying their status, URL, port, and other relevant details. This command is used to confirm that the Fetch server is active and accessible.

```bash
thv list
```

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

### Example Dockerfile Output

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

Illustrates the structure of a Dockerfile generated by 'thv build --dry-run'. It shows the base image, installation of 'uv', the package installation, and the entrypoint configuration.

```dockerfile
# Generated by: thv build --dry-run uvx://mcp-server-git
FROM python:3.12-slim

# Install uv
RUN pip install uv

# Install the package
RUN uv tool install mcp-server-git

# Set the entrypoint
ENTRYPOINT ["uv", "tool", "run", "mcp-server-git"]
```

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

### Example: Run Server with Custom Arguments

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

Shows how to run an MCP server from the 'github' registry entry and pass custom arguments, such as specifying toolsets.

```bash
# Run a server with custom arguments and toolsets
thv run github -- --toolsets repos
```

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

### Complete vMCP Example for Discovered Mode

Source: https://docs.stacklok.com/toolhive/guides-vmcp/backend-discovery

This comprehensive YAML example defines all necessary resources for a vMCP setup in discovered mode with authentication. It includes an MCPGroup, MCPExternalAuthConfig for token exchange, an MCPServer for the backend, and the VirtualMCPServer resource itself. This configuration enables automatic discovery of backends and their associated authentication configurations.

```yaml
---
# 1. Create the MCPGroup
apiVersion: toolhive.stacklok.dev/v1alpha1
kind: MCPGroup
metadata:
  name: engineering-tools
  namespace: toolhive-system
spec:
  description: Engineering team MCP servers

---
# 2. Create authentication config for GitHub backend
apiVersion: toolhive.stacklok.dev/v1alpha1
kind: MCPExternalAuthConfig
metadata:
  name: github-token-config
  namespace: toolhive-system
spec:
  type: tokenExchange
  tokenExchange:
    tokenUrl: https://oauth.example.com/token
    clientId: github-mcp-client
    clientSecretRef:
      name: github-oauth-secret
      key: client-secret
    audience: github-api

---
# 3. Create backend MCPServer
apiVersion: toolhive.stacklok.dev/v1alpha1
kind: MCPServer
metadata:
  name: github-mcp
  namespace: toolhive-system
spec:
  groupRef: engineering-tools
  image: ghcr.io/example/github-mcp-server:v1.2.3
  transport: sse
  externalAuthConfigRef:
    name: github-token-config

---
# 4. Create VirtualMCPServer (discovered mode)
apiVersion: toolhive.stacklok.dev/v1alpha1
kind: VirtualMCPServer
metadata:
  name: engineering-vmcp
  namespace: toolhive-system
spec:
  config:
    groupRef: engineering-tools
  incomingAuth:
    type: oidc
    oidc:
      issuer: https://auth.company.com
      audience: engineering-vmcp
  outgoingAuth:
    source: discovered # Discovers github-mcp and its auth config
```

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

### GET /websites/stacklok_toolhive

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

Retrieves the configuration and status of the stacklok_toolhive service. This endpoint provides detailed information about the service's setup, including audit configurations, authorization settings, container details, and network policies.

```APIDOC
## GET /websites/stacklok_toolhive

### Description
Retrieves the configuration and status of the stacklok_toolhive service. This endpoint provides detailed information about the service's setup, including audit configurations, authorization settings, container details, and network policies.

### Method
GET

### Endpoint
/websites/stacklok_toolhive

### Parameters
#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **audit_config** (object) - Configuration for audit logging.
- **audit_config_path** (string) - Path to the audit configuration file.
- **authz_config** (object) - Authorization configuration.
- **authz_config_path** (string) - Path to the authorization configuration file.
- **base_name** (string) - Base name of the service.
- **cmd_args** (array) - Command-line arguments for the service.
- **container_labels** (object) - Labels associated with the container.
- **container_name** (string) - Name of the container.
- **debug** (boolean) - Debug mode status.
- **embedded_auth_server_config** (object) - Configuration for an embedded authentication server.
- **endpoint_prefix** (string) - Prefix for service endpoints.
- **env_file_dir** (string) - Directory for environment files.
- **env_vars** (object) - Environment variables for the service.
- **group** (string) - Group the service belongs to.
- **header_forward** (object) - Configuration for forwarding headers.
- **host** (string) - Hostname of the service.
- **ignore_config** (object) - Configuration for ignoring certain settings.
- **image** (string) - Docker image used by the service.
- **isolate_network** (boolean) - Whether network isolation is enabled.
- **jwks_auth_token_file** (string) - Path to the JWKS authentication token file.
- **k8s_pod_template_patch** (string) - Kubernetes pod template patch.
- **middleware_configs** (array) - List of middleware configurations.
- **name** (string) - Name of the service.
- **oidc_config** (object) - OpenID Connect (OIDC) configuration.
- **permission_profile** (object) - Permission profile for the service.
- **permission_profile_name_or_path** (string) - Name or path of the permission profile.
- **port** (integer) - Port the service listens on.
- **proxy_mode** (string) - Proxy mode of the service.
- **remote_auth_config** (object) - Remote authentication configuration.

#### Response Example
```json
{
  "audit_config": {
    "component": "string",
    "enabled": true,
    "eventTypes": [
      "string"
    ],
    "excludeEventTypes": [
      "string"
    ],
    "includeRequestData": true,
    "includeResponseData": true,
    "logFile": "string",
    "maxDataSize": 0
  },
  "audit_config_path": "string",
  "authz_config": {
    "type": "string",
    "version": "string"
  },
  "authz_config_path": "string",
  "base_name": "string",
  "cmd_args": [
    "string"
  ],
  "container_labels": {
    "property1": "string",
    "property2": "string"
  },
  "container_name": "string",
  "debug": true,
  "embedded_auth_server_config": {
    "allowed_audiences": [
      "string"
    ],
    "hmac_secret_files": [
      "string"
    ],
    "issuer": "string",
    "schema_version": "string",
    "scopes_supported": [
      "string"
    ],
    "signing_key_config": {
      "fallback_key_files": [
        "string"
      ],
      "key_dir": "string",
      "signing_key_file": "string"
    },
    "token_lifespans": {
      "access_token_lifespan": "string",
      "auth_code_lifespan": "string",
      "refresh_token_lifespan": "string"
    },
    "upstreams": [
      {
        "name": "string",
        "oauth2_config": {
          "authorization_endpoint": "string",
          "client_id": "string",
          "client_secret_env_var": "string",
          "client_secret_file": "string",
          "redirect_uri": "string",
          "scopes": [
            "string"
          ],
          "token_endpoint": "string",
          "userinfo": {
            "additional_headers": {
              "property1": "string",
              "property2": "string"
            },
            "endpoint_url": "string",
            "field_mapping": {
              "email_fields": [
                "string"
              ],
              "name_fields": [
                "string"
              ],
              "subject_fields": [
                "string"
              ]
            },
            "http_method": "string"
          }
        },
        "oidc_config": {
          "client_id": "string",
          "client_secret_env_var": "string",
          "client_secret_file": "string",
          "issuer_url": "string",
          "redirect_uri": "string",
          "scopes": [
            "string"
          ],
          "userinfo_override": {
            "additional_headers": {
              "property1": "string",
              "property2": "string"
            },
            "endpoint_url": "string",
            "field_mapping": {
              "email_fields": [
                "string"
              ],
              "name_fields": [
                "string"
              ],
              "subject_fields": [
                "string"
              ]
            },
            "http_method": "string"
          }
        },
        "type": "oidc"
      }
    ]
  },
  "endpoint_prefix": "string",
  "env_file_dir": "string",
  "env_vars": {
    "property1": "string",
    "property2": "string"
  },
  "group": "string",
  "header_forward": {
    "add_headers_from_secret": {
      "property1": "string",
      "property2": "string"
    },
    "add_plaintext_headers": {
      "property1": "string",
      "property2": "string"
    }
  },
  "host": "string",
  "ignore_config": {
    "loadGlobal": true,
    "printOverlays": true
  },
  "image": "string",
  "isolate_network": true,
  "jwks_auth_token_file": "string",
  "k8s_pod_template_patch": "string",
  "middleware_configs": [
    {
      "parameters": {},
      "type": "string"
    }
  ],
  "name": "string",
  "oidc_config": {
    "allowPrivateIP": true,
    "audience": "string",
    "authTokenFile": "string",
    "cacertPath": "string",
    "clientID": "string",
    "clientSecret": "string",
    "insecureAllowHTTP": true,
    "introspectionURL": "string",
    "issuer": "string",
    "jwksurl": "string",
    "resourceURL": "string",
    "scopes": [
      "string"
    ]
  },
  "permission_profile": {
    "name": "string",
    "network": {
      "inbound": {
        "allow_host": [
          "string"
        ]
      },
      "mode": "string",
      "outbound": {
        "allow_host": [
          "string"
        ],
        "allow_port": [
          0
        ],
        "insecure_allow_all": true
      }
    },
    "privileged": true,
    "read": [
      "string"
    ],
    "write": [
      "string"
    ]
  },
  "permission_profile_name_or_path": "string",
  "port": 0,
  "proxy_mode": "sse",
  "remote_auth_config": {
    "authorize_url": "string",
    "bearer_token": "string",
    "bearer_token_file": "string",
    "cached_client_id": "string",
    "cached_client_secret_ref": "string",
    "cached_refresh_token_ref": "string",
    "cached_reg_token_ref": "string",
    "cached_secret_expiry": "string",
    "cached_token_expiry": "string",
    "callback_port": 0,
    "client_id": "string"
  }
}
```

#### Error Response (404)
- **message** (string) - Error message indicating the resource was not found.
```

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

### Run GitHub MCP Server with CLI

Source: https://docs.stacklok.com/toolhive/guides-mcp/github_mode=cli

Demonstrates how to run the GitHub MCP server using the ToolHive CLI. This includes basic execution, setting secrets, and enabling network isolation. It requires the 'thv' CLI tool and a GitHub personal access token.

```bash
thv run github  
thv secret set github  
thv run --secret github,target=GITHUB_PERSONAL_ACCESS_TOKEN github  
gh auth token | thv secret set github  
thv run --secret github,target=GITHUB_PERSONAL_ACCESS_TOKEN github  
thv run --isolate-network github  
```

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

### Get MCP Server Service Details (Kubernetes)

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

Fetches the details of the 'mcp-fetch-proxy' service within the 'toolhive-system' namespace. This is a preliminary step to port-forwarding and testing the server locally.

```bash
kubectl get service mcp-fetch-proxy -n toolhive-system
```

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

### Example: Run Remote Server with Authentication

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

Illustrates how to run a remote MCP server, likely from GitHub, and provides placeholders for remote authentication credentials.

```bash
# Run a remote GitHub MCP server with authentication
thv run github-remote --remote-auth
--remote-auth-client-id
--remote-auth-client-secret
```

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

### Example: Run Server using Node.js Protocol Scheme

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

Shows how to run an MCP server using the 'npx' protocol scheme for Node.js packages, targeting the '@modelcontextprotocol/server-everything' package.

```bash
# Run using npx (Node.js)
thv run npx://@modelcontextprotocol/server-everything
```

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

### Example: Run Server using Python Protocol Scheme

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

Demonstrates running an MCP server using the 'uvx' protocol scheme for Python packages, specifically the 'mcp-server-git' package.

```bash
# Run using a protocol scheme (Python with uv)
thv run uvx://mcp-server-git
```

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

### Example: Run Server from Container Image

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

Illustrates running an MCP server directly from a container image hosted on GHCR.

```bash
# Run from a container image
thv run ghcr.io/github/github-mcp-server
```

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

### Test MCP Server Health Endpoint (Curl)

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

Sends an HTTP GET request to the local port-forwarded address of the MCP server to check its health. A successful response should be 'OK'.

```bash
curl http://localhost:8080/health
```

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

### Deploy ToolHive Operator with Helm

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

Deploys the ToolHive operator to the 'toolhive-system' namespace using Helm. This command also creates the namespace if it doesn't exist. It requires Helm to be installed.

```bash
helm upgrade --install toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator -n toolhive-system --create-namespace
```

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

### Multi-architecture MCP Server Builds with GitHub Actions

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

Builds MCP server containers for multiple architectures (amd64, arm64) using Docker Buildx within a GitHub Actions workflow. It requires checkout, QEMU setup, Docker Buildx setup, and ToolHive installation. The output is a multi-architecture container image pushed to a registry.

```yaml
name: Multi-arch Build
on:
  push:
    tags: ['v*']

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up QEMU
        uses: docker/setup-qemu-action@v3

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Install ToolHive
        uses: StacklokLabs/toolhive-actions/install@v0
        with:
          version: latest

      - name: Generate Dockerfile
        run: |
          thv build --dry-run --output Dockerfile uvx://mcp-server-git

      - name: Build multi-arch container
        run: |
          docker buildx build \
            --platform linux/amd64,linux/arm64 \
            --tag ghcr.io/myorg/mcp-server:${{ github.ref_name }} \
            --push \
            .
```

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

### Serve Local ToolHive API Documentation

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

Starts the ToolHive API server and enables the serving of local API documentation. This allows developers to view and test API endpoints directly.

```bash
thv serve --openapi
```

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

### Create Local Kubernetes Cluster with Kind

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

Creates a local Kubernetes cluster named 'toolhive' using the 'kind' tool. This provides an isolated environment for testing the ToolHive operator. It requires 'kind' to be installed.

```bash
kind create cluster --name toolhive
```

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

### Kubernetes Deployment Example (YAML)

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

A Kubernetes Deployment YAML example for deploying the registry API. It demonstrates how to mount a configuration file and highlights that service account tokens and CA certificates are automatically provided by Kubernetes.

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: registry-api
spec:
  replicas: 1
  selector:
    matchLabels:
      app: registry-api
  template:
    metadata:
      labels:
        app: registry-api
    spec:
      serviceAccountName: registry-api
      containers:
        - name: registry-api
          image: ghcr.io/stacklok/thv-registry-api:latest
          args:
            - serve
            - --config=/etc/registry/config.yaml
          volumeMounts:
            - name: config
              mountPath: /etc/registry/config.yaml
              subPath: config.yaml
              readOnly: true
            # Service account token and CA cert are mounted automatically by Kubernetes
      volumes:
        - name: config
          configMap:
            name: registry-api-config
```

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

### Response Sample for Get Servers

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

A sample JSON response for the GET /registry/v0.1/servers endpoint. It includes metadata like count and nextCursor, and a list of servers, each with detailed package, remote, and repository information.

```JSON
{
  "metadata": {
    "count": 0,
    "nextCursor": "string"
  },
  "servers": [
    {
      "_meta": {
        "io.modelcontextprotocol.registry/official": {
          "isLatest": true,
          "publishedAt": "2019-08-24T14:15:22Z",
          "status": "active",
          "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": [
              {
                "name": "SOME_VARIABLE"
}
],
            "fileSha256": "fe333e598595000ae021bd27117db32ec69af6987f507ba7a63c90638ff633ce",
            "identifier": "@modelcontextprotocol/server-brave-search",
            "packageArguments": [
              {
                "isRepeated": true,
                "name": "--port",
                "type": "positional",
                "valueHint": "file_path"
}
],
            "registryBaseUrl": "https://registry.npmjs.org",
            "registryType": "npm",
            "runtimeArguments": [
              {
                "isRepeated": true,
                "name": "--port",
                "type": "positional",
                "valueHint": "file_path"
}
],
            "runtimeHint": "npx",
            "transport": {
              "headers": [
                {
                  "name": "SOME_VARIABLE"
}
],
              "type": "stdio",
              "url": "https://api.example.com/mcp",
              "variables": {
                "property1": {
                  "choices": [
                    null
],
                  "default": "string",
                  "description": "string",
                  "format": "string",
                  "isRequired": true,
                  "isSecret": true,
                  "placeholder": "string",
                  "value": "string"
},
                "property2": {
                  "choices": [
                    null
],
                  "default": "string",
                  "description": "string",
                  "format": "string",
                  "isRequired": true,
                  "isSecret": true,
                  "placeholder": "string",
                  "value": "string"
}
}
},
            "version": "1.0.2"
}
],
        "remotes": [
          {
            "headers": [
              {
                "name": "SOME_VARIABLE"
}
],
            "type": "stdio",
            "url": "https://api.example.com/mcp",
            "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"
}
}
}
],
        "repository": {
          "id": "b94b5f7e-c7c6-d760-2c78-a5e9b8a5b8c9",
          "source": "github",
          "subfolder": "src/everything",
          "url": "https://github.com/modelcontextprotocol/servers"
},
        "title": "Weather API",
        "version": "1.0.2",
        "websiteUrl": "https://modelcontextprotocol.io/examples"
}
}
]

}
```

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

### Secure MCP Server Container Builds with GitHub Actions

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

Enhances MCP server container builds with supply chain security features like SBOM generation, provenance attestation, and image signing using Cosign. This GitHub Actions workflow requires Cosign installation, Docker Buildx setup, and ToolHive installation. It builds and pushes images with security metadata.

```yaml
name: Secure Build
on:
  push:
    tags: ['v*']

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
      id-token: write
    steps:
      - uses: actions/checkout@v4

      - name: Install Cosign
        uses: sigstore/cosign-installer@v3

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Install ToolHive
        uses: StacklokLabs/toolhive-actions/install@v0
        with:
          version: latest

      - name: Generate Dockerfile
        run: |
          thv build --dry-run --output Dockerfile uvx://mcp-server-git

      - name: Build with security features
        uses: docker/build-push-action@v6
        id: build
        with:
          context: .
          platforms: linux/amd64,linux/arm64
          push: true
          tags: ghcr.io/myorg/mcp-server:${{ github.ref_name }}
          sbom: true # Generate Software Bill of Materials
          provenance: true # Generate build provenance
          cache-from: type=gha
          cache-to: type=gha,mode=max

      - name: Sign container image
        env:
          DIGEST: ${{ steps.build.outputs.digest }}
        run: |
          cosign sign --yes ghcr.io/myorg/mcp-server@${DIGEST}
```