ToolHive

https://github.com/stacklok/toolhive
Admin
ToolHive simplifies and secures the deployment and management of Model Context Protocol (MCP)...
Tokens:364,285
Snippets:3,282
Trust Score:9.7
License:Apache-2.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Interactive Client Setup with thv client setup

Source: https://github.com/stacklok/toolhive/blob/main/skills/toolhive-cli-user/references/EXAMPLES.md

Runs a guided setup for detected clients.

```bash
# Guided setup for detected clients
thv client setup
```

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

### Install the Go SDK with go get

Source: https://github.com/stacklok/toolhive/blob/main/sdk/go/README.md

Use this command to install the SDK. Since no SDK tag is published, you must pin a ToolHive commit or Go pseudo-version compatible with your ToolHive version.

```bash
go get github.com/stacklok/toolhive/sdk/go@<commit-or-pseudo-version>
```

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

### CLI Setup Example: Running Multiple Servers

Source: https://github.com/stacklok/toolhive/blob/main/docs/operator/virtualmcpserver-kubernetes-guide.md

Shows how to run multiple backend servers via CLI, which is the equivalent of a VirtualMCPServer. Note that CLI grouping works differently; backends reference groups via config.

```bash
# CLI: Running multiple servers
thv run github --image ghcr.io/example/github-mcp
thv run jira --image ghcr.io/example/jira-mcp
thv run slack --image ghcr.io/example/slack-mcp

# Note: CLI grouping works differently - backends reference groups via config
```

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

### Git URL patterns for skill installation

Source: https://github.com/stacklok/toolhive/blob/main/docs/arch/12-skills-system.md

Examples of git:// URLs for installing skills from a repository root, a specific tag, a subdirectory, or a branch with a subdirectory. The default branch is used when no ref is specified.

```text
git://github.com/org/repo                    # Repo root, default branch
git://github.com/org/repo@v1.0.0             # Specific tag
git://github.com/org/repo#skills/my-skill    # Subdirectory
git://github.com/org/repo@main#skills/my-skill  # Branch + subdirectory
```

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

### Build examples

Source: https://github.com/stacklok/toolhive/blob/main/docs/cli/thv_build.md

Example invocations of `thv build` with various protocols and options.

```bash
$ thv build uvx://mcp-server-git
$ thv build --tag my-custom-name:latest npx://@modelcontextprotocol/server-filesystem
$ thv build go://./my-local-server
$ thv build npx://@launchdarkly/mcp-server -- start
```

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

### Quick start: create client and get health

Source: https://github.com/stacklok/toolhive/blob/main/sdk/go/README.md

Creates a client with a base URL, calls GetHealth, and prints the result. The client validates the URL, applies a 30-second deadline, and a 10 MiB response-body limit by default.

```go
package main

import (
	"context"
	"fmt"
	"log"

	"github.com/stacklok/toolhive/sdk/go/client"
)

func main() {
	api, err := client.NewClient("http://127.0.0.1:8080")
	if err != nil {
		log.Fatal(err)
	}

	health, err := api.GetHealth(context.Background())
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(health)
}
```

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

### API Test Example

Source: https://github.com/stacklok/toolhive/blob/main/test/e2e/README.md

Example of a Ginkgo test for the Workloads API, using the 'api' and 'workloads' labels. It starts the server with e2e.StartServer() and makes a GET request to /api/v1beta/workloads.

```go
var _ = Describe("Workloads API", Label("api", "workloads"), func() {
    var apiServer *e2e.Server

    BeforeEach(func() {
        config := e2e.NewServerConfig()
        apiServer = e2e.StartServer(config)
    })

    It("should list workloads", func() {
        resp, err := apiServer.Get("/api/v1beta/workloads")
        Expect(err).ToNot(HaveOccurred())
        defer resp.Body.Close()
        Expect(resp.StatusCode).To(Equal(http.StatusOK))
    })
})
```

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

### Quick start: create group, run MCP servers, configure and start vmcp

Source: https://github.com/stacklok/toolhive/blob/main/cmd/vmcp/README.md

A step-by-step workflow to set up a ToolHive group, run MCP servers, create a vmcp configuration file, validate it, start the server, and test the health endpoint.

```bash
# 1. Create a ToolHive group
thv group create my-team

# 2. Run some MCP servers in the group
thv run github --name github-mcp --group my-team
thv run fetch --name fetch-mcp --group my-team

# 3. Create a vmcp configuration file (see examples/vmcp-config.yaml)
cat > vmcp-config.yaml <<EOF
name: "my-vmcp"
groupRef: "my-team"
incomingAuth:
  type: anonymous
outgoingAuth:
  source: inline
  default:
    type: unauthenticated
aggregation:
  conflictResolution: prefix
  conflictResolutionConfig:
    prefixFormat: "{workload}_"
EOF

# 4. Validate the configuration
vmcp validate --config vmcp-config.yaml

# 5. Start the Virtual MCP Server
vmcp serve --config vmcp-config.yaml

# 6. Test the health endpoint
curl http://127.0.0.1:4483/health
# {"status":"ok"}

# 7. Connect your MCP client to http://127.0.0.1:4483/mcp
# The client will see aggregated tools from all backends:
#   - github-mcp_create_issue, github-mcp_list_repos, ...
#   - fetch-mcp_fetch, ...
```

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

### Install skills with thv skill install

Source: https://github.com/stacklok/toolhive/blob/main/skills/toolhive-cli-user/SKILL.md

Installs a skill from the registry or by OCI reference. Use --clients to target specific clients, --scope project with --project-root for project-scoped installs, --group to add to a group, and --force to overwrite existing skills.

```bash
thv skill install my-skill                              # Install from registry
thv skill install ghcr.io/org/skill:v1.0                # Install by OCI reference
thv skill install my-skill --clients claude-code          # Target specific client(s)
thv skill install my-skill --scope project --project-root .  # Project-scoped
thv skill install my-skill --group development           # Add to group
thv skill install my-skill --force                       # Overwrite existing
```

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

### Run automated Kind ingress setup with Task

Source: https://github.com/stacklok/toolhive/blob/main/docs/kind/ingress.md

Runs the automated installation of the Nginx Ingress Controller using Task. It installs the controller and fixes secret inconsistencies, but does not handle the cloud-provider-kind Load Balancer, which must be run separately.

```bash
task kind-ingress-setup
```

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

### Build and install vmcp from source

Source: https://github.com/stacklok/toolhive/blob/main/cmd/vmcp/README.md

Commands to build the vmcp binary using task, or install it to GOPATH/bin.

```bash
# Build the binary
task build-vmcp

# Or install to GOPATH/bin
task install-vmcp
```

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

### Inspect and install AI plugins

Source: https://github.com/stacklok/toolhive/blob/main/skills/toolhive-cli-user/references/EXAMPLES.md

Inspect installed project plugins, install a reviewed OCI plugin, and install from a Git source. For Codex, complete the explicit client hand-off manually.

```bash
# Inspect installed project plugins before changing them.
thv ai-plugin list --scope project --project-root .
thv ai-plugin info example-plugin --scope project --project-root .

# Install a reviewed OCI plugin into this project and target Claude Code.
thv ai-plugin install ghcr.io/example-org/example-plugin:v1.0 \
  --scope project --project-root . --clients claude-code

# A Git source can select a ref and plugin subdirectory.
thv ai-plugin install git://github.com/example-org/plugin-repo@v1.0#plugins/example-plugin \
  --scope project --project-root . --clients codex
```

```bash
codex plugin install example-plugin@toolhive
```

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

### Apply Nginx Ingress Controller manifest

Source: https://github.com/stacklok/toolhive/blob/main/docs/kind/ingress.md

Installs the Nginx Ingress Controller by applying the official Kind example manifest. This is the manual installation step.

```bash
kubectl apply -f https://kind.sigs.k8s.io/examples/ingress/deploy-ingress-nginx.yaml
```

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

### Install skill by reference type

Source: https://github.com/stacklok/toolhive/blob/main/docs/arch/12-skills-system.md

Shows three ways to install a skill: by name (registry lookup), by OCI reference, or from a git repository. The reference format determines the resolver used.

```bash
thv skill install code-review                          # By name (registry lookup)
thv skill install ghcr.io/org/skill:v1.0.0             # By OCI reference
thv skill install git://github.com/org/repo@v1#skills/my-skill  # From git
```

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

### Install, list, sync, and upgrade AI plugins with thv ai-plugin

Source: https://github.com/stacklok/toolhive/blob/main/skills/toolhive-cli-user/SKILL.md

Use these commands to manage AI plugins via the ToolHive API. Start `thv serve` first. Install by exact registry name, OCI reference, or git source; use `--clients` to target `claude-code`, `codex`, or `all`. Verification and lock-file trust are project-only; user-scoped installs skip lock-file verification.

```bash
thv ai-plugin install example-plugin --clients claude-code
thv ai-plugin install ghcr.io/example-org/example-plugin:v1.0 --scope project --project-root .
thv ai-plugin install git://github.com/example-org/example-plugin@v1.0#plugin --scope project --project-root .
thv ai-plugin list --scope project --project-root .
thv ai-plugin sync --check --project-root .
thv ai-plugin upgrade --preview --project-root .
```

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

### Start vmcp server with basic usage

Source: https://github.com/stacklok/toolhive/blob/main/cmd/vmcp/README.md

Basic command to start the vmcp server with a specified configuration file.

```bash
# Basic usage
vmcp serve --config /path/to/vmcp-config.yaml
```

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

### Start vmcp server with custom host and port

Source: https://github.com/stacklok/toolhive/blob/main/cmd/vmcp/README.md

Starts the server on a custom host and port.

```bash
# Customize host and port
vmcp serve --config /path/to/vmcp-config.yaml --host 0.0.0.0 --port 8080
```

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

### Install ToolHive Binary

Source: https://github.com/stacklok/toolhive/blob/main/docs/README.md

Installs the ToolHive CLI binary into the GOPATH/bin directory using Task.

```bash
task install
```

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

### POST /api/v1beta/skills/

Source: https://github.com/stacklok/toolhive/blob/main/docs/arch/12-skills-system.md

Installs a skill.

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

### Description
Installs a skill.

### Method
POST

### Endpoint
/api/v1beta/skills/

### Request Body
- **skill** (object) - Required - Skill installation details.

### Request Example
{
  "skill": {}
}

### Response
#### Success Response (200)
- **status** (string) - Installation status.

#### Response Example
{
  "status": "installed"
}
```

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

### Run from a container image

Source: https://github.com/stacklok/toolhive/blob/main/docs/cli/thv_run.md

Starts a server from a container image.

```bash
thv run ghcr.io/github/github-mcp-server
```

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

### Add build tools for native extensions with --runtime-add-package

Source: https://github.com/stacklok/toolhive/blob/main/docs/runtime-version-customization.md

Use --runtime-add-package to install additional packages during build and runtime stages. The flag can be repeated. Example adds gcc and musl-dev for Go native extensions.

```bash
# Add build tools for native extensions
thv run go://github.com/example/server \
  --runtime-image golang:1.24-alpine \
  --runtime-add-package gcc \
  --runtime-add-package musl-dev
```

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

### Typical Authoring Workflow

Source: https://github.com/stacklok/toolhive/blob/main/skills/toolhive-cli-user/references/EXAMPLES.md

End-to-end workflow for authoring and publishing a skill: validate, build, push, install, and confirm installation.

```bash
# 1. Create and validate
thv skill validate ./my-skill

# 2. Build the artifact
thv skill build ./my-skill --tag ghcr.io/myorg/my-skill:v1.0

# 3. Push to registry
thv skill push ghcr.io/myorg/my-skill:v1.0

# 4. Install from registry to verify
thv skill install ghcr.io/myorg/my-skill:v1.0 --clients claude-code

# 5. Confirm installation
thv skill info my-skill
```

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

### Install Skills

Source: https://github.com/stacklok/toolhive/blob/main/skills/toolhive-cli-user/references/EXAMPLES.md

Install skills for the current user, specific clients, projects, or groups. Use --force to overwrite existing installations, and --scope project with --project-root for project-scoped installs.

```bash
# Install a skill for the current user
thv skill install code-review

# Install targeting a specific client
thv skill install code-review --clients claude-code

# Install into a project (requires --project-root)
thv skill install code-review --scope project --project-root /home/user/myproject

# Force reinstall (overwrites existing)
thv skill install code-review --force

# Install and assign to a group
thv skill install code-review --group development

# Install by OCI reference
thv skill install ghcr.io/stacklok/skills/code-review:v1.0
```

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

### Install skill for all clients (default)

Source: https://github.com/stacklok/toolhive/blob/main/docs/arch/12-skills-system.md

Installs a skill for all skill-supporting clients. This is the default behavior when no --clients flag is provided.

```bash
thv skill install code-review
```

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

### Long description with examples

Source: https://github.com/stacklok/toolhive/blob/main/docs/cli-best-practices.md

Example of a Long description that provides a detailed explanation, usage notes, and 2-3 practical examples with commands like 'thv list' and 'thv list --all'.

```go
Long: `List all MCP servers managed by ToolHive, including their status and configuration.

The list command shows running servers by default. Use --all to include stopped servers.

Examples:
  # List running MCP servers
  thv list

  # List all servers including stopped ones
  thv list --all

  # List servers in JSON format
  thv list --format json`,

```

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

### Start server with OpenAPI docs enabled

Source: https://github.com/stacklok/toolhive/blob/main/docs/server/README.md

Start the ToolHive server with the --openapi flag to enable API documentation endpoints. Access the JSON spec at /api/openapi.json and the Scalar UI at /api/doc.

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

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

### Composite Tools Configuration Example

Source: https://github.com/stacklok/toolhive/blob/main/docs/operator/virtualmcpserver-api.md

Defines an inline composite tool workflow with parameters, steps, and dependencies. The example shows a deploy_and_notify tool that merges a PR, elicits user confirmation, and deploys to Kubernetes.

```yaml
spec:
  compositeTools:
    - name: deploy_and_notify
      description: Deploy PR with user confirmation and notification
      parameters:
        pr_number:
          type: integer
          required: true
      steps:
        - id: merge
          tool: github.merge_pr
          arguments:
            pr: "{{.params.pr_number}}"
        - id: confirm_deploy
          type: elicitation
          message: "PR {{.params.pr_number}} merged. Proceed with deployment?"
          dependsOn: ["merge"]
        - id: deploy
          tool: kubernetes.deploy
          arguments:
            pr: "{{.params.pr_number}}"
          dependsOn: ["confirm_deploy"]
```

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

### Task: Create fresh kind cluster and install operator

Source: https://github.com/stacklok/toolhive/blob/main/docs/kind/deploying-toolhive-operator.md

Run this command to create a kind cluster, install an nginx ingress controller, and install the latest built ToolHive Operator image.

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

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

### First install of externally key-signed OCI plugin

Source: https://github.com/stacklok/toolhive/blob/main/skills/toolhive-cli-user/references/EXAMPLES.md

Supply the reviewed public key only for the first project install. ToolHive pins it in `toolhive.lock.yaml` and reuses it for sync and upgrade.

```bash
# Supply the reviewed public key only for the first project install.
# ToolHive pins it in toolhive.lock.yaml and reuses it for sync and upgrade.
thv ai-plugin install ghcr.io/example-org/example-plugin:v1.0 \
  --scope project --project-root . --public-key ./keys/example-plugin.cosign.pub
```

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

### Installation flow diagram

Source: https://github.com/stacklok/toolhive/blob/main/docs/arch/12-skills-system.md

Mermaid flowchart showing the installation decision tree: reference type detection, git/OCI/registry resolution, validation, and persistence steps.

```mermaid
flowchart TD
    A[Install Request] --> B{Reference Type?}
    B -->|git://| C[Git Resolver]
    B -->|OCI ref| D[OCI Pull]
    B -->|Plain name| E[Registry Lookup]

    C --> F[Clone repo with timeout]
    F --> G[Extract skill files]

    E --> H{Found in local store?}
    H -->|Yes| I[Use local artifact]
    H -->|No| J[Query registry/index]
    J --> D

    D --> K[Pull from registry]
    K --> L[Decompress + extract tar.gz]
    G --> L

    I --> L

    L --> M[Validate: no symlinks, path traversal]
    M --> N[Sanitize permissions]
    N --> O[Write to client skill directory]
    O --> P[Create DB record]
    P --> Q{Group specified?}
    Q -->|Yes| R[Add to group]
    Q -->|No| S[Done]
    R --> S

    style A fill:#e3f2fd
    style S fill:#c8e6c9
    style M fill:#fff3e0
    style N fill:#fff3e0
```

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

### thv config set-registry examples

Source: https://github.com/stacklok/toolhive/blob/main/docs/cli/thv_config_set-registry.md

Examples of setting the registry to a static remote file, API endpoint, local file path, explicit file URL, and with OAuth authentication.

```bash
thv config set-registry https://example.com/registry.json           # Static remote file
  thv config set-registry https://registry.example.com                # API endpoint
  thv config set-registry /path/to/local-registry.json               # Local file path
  thv config set-registry file:///path/to/local-registry.json        # Explicit file URL
  thv config set-registry https://registry.example.com \
    --issuer https://auth.company.com --client-id toolhive-cli       # With OAuth auth
```

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

### Task: Install operator on existing kind cluster

Source: https://github.com/stacklok/toolhive/blob/main/docs/kind/deploying-toolhive-operator.md

Use these commands to install the operator into an existing kind cluster. The first installs the latest built image from GitHub (recommended); the second builds and deploys locally (for development).

```bash
# If you want to install the latest built operator image from Github (recommended)
task operator-deploy-latest

# If you want to built the operator image locally and deploy it (only recommended if you're doing development around the Operator)
task operator-deploy-local
```

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

### Start vmcp server with audit logging enabled

Source: https://github.com/stacklok/toolhive/blob/main/cmd/vmcp/README.md

Starts the server with audit logging enabled using default configuration.

```bash
# With audit logging enabled (uses default configuration)
vmcp serve --config /path/to/vmcp-config.yaml --enable-audit
```

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

### Install and List Skills by Group

Source: https://github.com/stacklok/toolhive/blob/main/docs/arch/12-skills-system.md

Commands to install a skill into a specific group and list skills within that group. The group is specified with the --group flag.

```bash
thv skill install code-review --group dev-tools
thv skill list --group dev-tools
```

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

### thv run Resource Parameter Examples

Source: https://github.com/stacklok/toolhive/blob/main/docs/remote-mcp-authentication.md

Command-line examples for the thv run command demonstrating automatic resource parameter defaulting, explicit resource parameter validation, and error cases for invalid resource URIs. The automatic example shows normalization of scheme/host and fragment stripping. Explicit parameters are validated but not modified, returning errors for fragments or missing schemes.

```bash
# Automatic resource parameter (defaults and normalizes to remote URL)
thv run https://MCP.Example.COM/api#section
# Resource defaults to: https://mcp.example.com/api (normalized, fragment stripped)

# Explicit resource parameter (not modified, must be valid)
thv run https://mcp.example.com/api \
  --remote-auth-resource https://mcp.example.com

# Invalid explicit resource parameter with fragment (returns error)
thv run https://mcp.example.com/api \
  --remote-auth-resource https://mcp.example.com#fragment
# Error: invalid resource parameter: resource URI must not contain fragments

# Invalid explicit resource parameter without scheme (returns error)
thv run https://mcp.example.com/api \
  --remote-auth-resource mcp.example.com
# Error: invalid resource parameter: resource URI must include a scheme
```

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

### GET /api/v1beta/skills/{name}

Source: https://github.com/stacklok/toolhive/blob/main/docs/arch/12-skills-system.md

Gets information about a specific installed skill.

```APIDOC
## GET /api/v1beta/skills/{name}

### Description
Gets information about a specific installed skill.

### Method
GET

### Endpoint
/api/v1beta/skills/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the skill.

### Response
#### Success Response (200)
- **skill** (object) - Skill information.

#### Response Example
{
  "skill": {}
}
```

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

### Quick Start with Registry Server

Source: https://github.com/stacklok/toolhive/blob/main/skills/toolhive-cli-user/references/EXAMPLES.md

Basic lifecycle commands for a filesystem server: run, list, status, view tools, logs, stop, and remove.

```bash
# Run filesystem server
thv run filesystem

# Check it's running
thv list

# Get detailed status
thv status filesystem

# View capabilities
thv mcp list tools --server filesystem

# View logs
thv logs filesystem

# Stop when done
thv stop filesystem

# Clean up
thv rm filesystem
```

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

### Install Task with Homebrew

Source: https://github.com/stacklok/toolhive/blob/main/docs/README.md

Installs the Task automation tool on macOS using Homebrew. Recommended for running development tasks.

```bash
brew install go-task
```

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

### Start LLM proxy with thv llm proxy start

Source: https://github.com/stacklok/toolhive/blob/main/docs/cli/thv_llm_proxy_start.md

Starts the LLM gateway localhost proxy in the foreground. The proxy blocks until interrupted with Ctrl+C. To run it in the background, use your shell or a process manager, for example: thv llm proxy start &

```bash
thv llm proxy start [flags]
```

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

### Run a server with custom arguments and toolsets

Source: https://github.com/stacklok/toolhive/blob/main/docs/cli/thv_run.md

Starts a server from the registry, passing custom arguments and toolsets to the server.

```bash
thv run github -- --toolsets repos
```

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

### thv skill install command syntax

Source: https://github.com/stacklok/toolhive/blob/main/skills/toolhive-cli-user/references/COMMANDS.md

Installs a skill by name or OCI reference. Requires thv serve to be running. Flags include --clients, --scope (default user), --force, --project-root, and --group.

```bash
thv skill install [flags] SKILL_NAME
```

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

### thv client commands: status, setup, register, list-registered, remove

Source: https://github.com/stacklok/toolhive/blob/main/skills/toolhive-cli-user/SKILL.md

Commands to manage clients. Use 'thv client status' to check all supported clients, 'thv client setup' for interactive setup, 'thv client register claude-code --group development' to register a client with a group, 'thv client list-registered' to list registered clients, and 'thv client remove' to remove a client.

```bash
thv client status              # Check all supported clients
thv client setup               # Interactive setup
thv client register claude-code --group development  # Register with group
thv client list-registered     # List registered
thv client remove              # Remove client
```

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

### GET /api/v1beta/skills/

Source: https://github.com/stacklok/toolhive/blob/main/docs/arch/12-skills-system.md

Lists installed skills. Supports filtering by scope, client, project_root, and group.

```APIDOC
## GET /api/v1beta/skills/

### Description
Lists installed skills. Supports filtering by scope, client, project_root, and group.

### Method
GET

### Endpoint
/api/v1beta/skills/

### Parameters
#### Query Parameters
- **scope** (string) - Optional - Filter by scope.
- **client** (string) - Optional - Filter by client.
- **project_root** (string) - Optional - Filter by project root.
- **group** (string) - Optional - Filter by group.

### Response
#### Success Response (200)
- **skills** (array) - List of installed skills.

#### Response Example
{
  "skills": []
}
```

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

### Run Server with Custom Configuration

Source: https://github.com/stacklok/toolhive/blob/main/skills/toolhive-cli-user/references/EXAMPLES.md

Examples of running servers with environment variables, volume mounts, and labels.

```bash
# Named server with environment variables
thv run github \
  --name my-github \
  -e GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxx \
  -- --toolsets repos

# Server with volume mount
thv run filesystem \
  --name project-fs \
  -v /home/user/projects:/workspace:ro

# Server with multiple labels
thv run fetch \
  --name docs-fetch \
  -l env=production \
  -l team=backend \
  -l version=1.0
```

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

### Step 5: Deploy Everything

Source: https://github.com/stacklok/toolhive/blob/main/docs/operator/virtualmcpserver-kubernetes-guide.md

Deploys all resources in order: Group, Backends, then VirtualMCP. Also verifies the deployment with kubectl get commands.

```bash
# Deploy in order: Group → Backends → VirtualMCP
kubectl apply -f mcp-group.yaml
kubectl apply -f github.yaml
kubectl apply -f jira.yaml
kubectl apply -f slack.yaml
kubectl apply -f virtual-mcp-server.yaml

# Verify deployment
kubectl get mcpgroup my-services
kubectl get mcpserver
kubectl get virtualmcpserver my-vmcp
```

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

### Start MCP server with --authz-config flag

Source: https://github.com/stacklok/toolhive/blob/main/docs/authz.md

Command to start an MCP server with authorization enabled. Uses the --authz-config flag to point to the configuration file.

```bash
thv run --transport sse --name my-mcp-server --proxy-port 8080 --authz-config /path/to/authz-config.yaml my-mcp-server-image:latest -- my-mcp-server-args
```

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

### RunConfig delegate_clients example

Source: https://github.com/stacklok/toolhive/blob/main/docs/arch/17-token-exchange-delegation.md

Example RunConfig excerpt showing delegate client configuration with `client_secret_env_var`. Note that `delegate_clients` require scopes and audiences to be subsets of `scopes_supported` and `allowed_audiences`. `client_secret_env_var` may be replaced by `client_secret_file`. Inline secrets are not supported. Generate the secret with a CSPRNG like `openssl rand -base64 32`.

```yaml
issuer: https://auth.example.com
scopes_supported: [openid, profile]
allowed_audiences: [https://mcp.example.com]
delegate_clients:
  - client_id: reporting-delegate
    client_secret_env_var: REPORTING_DELEGATE_CLIENT_SECRET
    scopes: [openid]
    audiences: [https://mcp.example.com]
trusted_issuers:
  - issuer_url: https://login.example-idp.com
    expected_audience: https://mcp.example.com
    allowed_actors: [external-reporting-client]
    allowed_delegate_clients: [reporting-delegate]

```

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

### thv secret commands: set, list, get, delete

Source: https://github.com/stacklok/toolhive/blob/main/skills/toolhive-cli-user/SKILL.md

Commands to manage secrets. Setup is required before use with 'thv secret setup' (interactive provider selection). Providers include Encrypted (AES-256-GCM, password in OS keyring) and 1Password (read-only, requires OP_SERVICE_ACCOUNT_TOKEN). Use 'thv secret set' for interactive input, 'echo | thv secret set' for piped input, 'thv secret list' to list all, 'thv secret get' to retrieve, and 'thv secret delete' to remove.

```bash
thv secret set MY_API_KEY              # Interactive input
echo "value" | thv secret set MY_KEY   # Piped input
thv secret list                        # List all
thv secret get MY_API_KEY              # Retrieve
thv secret delete MY_API_KEY           # Remove
```

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

### Run using a protocol scheme (Python with uv)

Source: https://github.com/stacklok/toolhive/blob/main/docs/cli/thv_run.md

Starts a server using the uvx:// protocol scheme, which uses Python with uv.

```bash
thv run uvx://mcp-server-git
```

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

### Focused Steps DO Example

Source: https://github.com/stacklok/toolhive/blob/main/docs/operator/advanced-workflow-patterns.md

Shows the recommended pattern of one responsibility per step, with clear dependencies between steps.

```yaml
steps:
  - id: fetch_user
    tool: db.query_user
  - id: validate_permissions
    tool: auth.check_permissions
    dependsOn: [fetch_user]
  - id: perform_action
    tool: api.execute
    dependsOn: [validate_permissions]
```

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

### Get Workflow Status (Go)

Source: https://github.com/stacklok/toolhive/blob/main/docs/operator/advanced-workflow-patterns.md

Retrieves workflow status programmatically via the Composer Go API. Prints workflow ID, status, start time, duration, and completed steps. HTTP REST endpoints are planned for a future release.

```go
// Get workflow status
status, err := composer.GetWorkflowStatus(ctx, workflowID)
if err != nil {
    // Handle error
}

// Check workflow state
fmt.Printf("Workflow ID: %s\n", status.WorkflowID)
fmt.Printf("Status: %s\n", status.Status)
fmt.Printf("Started: %s\n", status.StartTime)
fmt.Printf("Duration: %s\n", status.Duration)
fmt.Printf("Completed Steps: %v\n", status.CompletedSteps)
```

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

### Telemetry Configuration Example

Source: https://github.com/stacklok/toolhive/blob/main/docs/operator/virtualmcpserver-api.md

Configures OpenTelemetry-based telemetry for the Virtual MCP server, including OTLP endpoint, service name, tracing, metrics, and Prometheus metrics path. The example sets an insecure OTLP endpoint and enables tracing and metrics.

```yaml
spec:
  groupRef:
    name: my-group
  config:
    telemetry:
      endpoint: "otel-collector:4317"
      serviceName: "my-vmcp"
      insecure: true
      tracingEnabled: true
      samplingRate: "0.1"
      metricsEnabled: true
      enablePrometheusMetricsPath: true
```

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

### Redis Sentinel RunConfig with ACL user authentication

Source: https://github.com/stacklok/toolhive/blob/main/docs/redis-storage.md

Example RunConfig for a Redis Sentinel setup. Uses ACL user authentication with username and password environment variables. Includes sentinel master name, addresses, database, key prefix, and timeouts.

```json
{
  "type": "redis",
  "redisConfig": {
    "sentinelConfig": {
      "masterName": "mymaster",
      "sentinelAddrs": [
        "redis-sentinel-0:26379",
        "redis-sentinel-1:26379",
        "redis-sentinel-2:26379"
      ],
      "db": 0
    },
    "authType": "aclUser",
    "aclUserConfig": {
      "usernameEnvVar": "TOOLHIVE_AS_REDIS_USERNAME",
      "passwordEnvVar": "TOOLHIVE_AS_REDIS_PASSWORD"
    },
    "keyPrefix": "thv:auth:{default:my-auth-config}:",
    "dialTimeout": "5s",
    "readTimeout": "3s",
    "writeTimeout": "3s"
  }
}
```

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

### thv start - Start stopped servers

Source: https://github.com/stacklok/toolhive/blob/main/skills/toolhive-cli-user/SKILL.md

Resumes stopped servers. Use --all to start all stopped servers, or --group to start all in a group. Note: Remote servers trigger fresh OAuth authentication on start.

```bash
thv start filesystem              # Resume stopped server
thv start --all                   # Start all stopped servers
thv start --group development     # Start all in group
thv restart filesystem            # Alias for start (backward compat)
```

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

### Register with the System (Go)

Source: https://github.com/stacklok/toolhive/blob/main/docs/middleware.md

Adds the new middleware to the supported middleware map in GetSupportedMiddlewareFactories(). Must be added to pkg/runner/middleware.go. This example shows the full map with existing entries and the new yourpackage entry.

```go
func GetSupportedMiddlewareFactories() map[string]types.MiddlewareFactory {
    return map[string]types.MiddlewareFactory{
        auth.MiddlewareType:                   auth.CreateMiddleware,
        tokenexchange.MiddlewareType:          tokenexchange.CreateMiddleware,
        upstreamswap.MiddlewareType:           upstreamswap.CreateMiddleware,
        mcp.ParserMiddlewareType:              mcp.CreateParserMiddleware,
        mcp.ToolFilterMiddlewareType:          mcp.CreateToolFilterMiddleware,
        mcp.ToolCallFilterMiddlewareType:      mcp.CreateToolCallFilterMiddleware,
        usagemetrics.MiddlewareType:           usagemetrics.CreateMiddleware,
        telemetry.MiddlewareType:              telemetry.CreateMiddleware,
        authz.MiddlewareType:                  authz.CreateMiddleware,
        audit.MiddlewareType:                  audit.CreateMiddleware,
        recovery.MiddlewareType:               recovery.CreateMiddleware,
        headerfwd.HeaderForwardMiddlewareName: headerfwd.CreateMiddleware,
        yourpackage.MiddlewareType:            yourpackage.CreateMiddleware,
    }
}
```

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

### Deploy Keycloak and setup realm

Source: https://github.com/stacklok/toolhive/blob/main/deploy/keycloak/README.md

Run these commands from the cmd/thv-operator/ directory to deploy Keycloak and set up the realm.

```bash
task kind-setup
task operator-install-crds
task operator-deploy-local
task keycloak:deploy-dev
```

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

### Read and write mounts example

Source: https://github.com/stacklok/toolhive/blob/main/docs/arch/05-runconfig-and-permissions.md

Shows a JSON configuration with both read and write mounts. Read mounts are read-only, write mounts are read-write.

```json
{
  "read": ["/home/user/config:/config"],
  "write": ["/home/user/output:/output"]
}
```

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

### Start a workload with thv start

Source: https://github.com/stacklok/toolhive/blob/main/docs/arch/08-workloads-lifecycle.md

Starts a previously stopped workload (my-server). It loads the state, verifies it is not running, and starts the workload with its saved configuration. Note: thv restart remains as an alias for backward compatibility.

```bash
thv start my-server
```

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

### Import the package

Source: https://github.com/stacklok/toolhive/blob/main/docs/authz.md

Blank import to ensure the init() function runs and registers the factory.

```go
import _ "github.com/stacklok/toolhive/pkg/authz/authorizers/myauthorizer"
```

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

### Install Codex plugin manually: codex plugin install <name>@toolhive

Source: https://github.com/stacklok/toolhive/blob/main/docs/arch/14-plugins-system.md

Run this command to complete the client-side installation of a plugin into Codex after ToolHive has registered it in the marketplace. Marketplace discovery alone does not install the plugin; this manual step is required.

```bash
codex plugin install <name>@toolhive
```

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

### Simple run

Source: https://github.com/stacklok/toolhive/blob/main/docs/arch/06-registry-system.md

Runs a server from the registry with default settings.

```bash
thv run weather-server
```

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

### Install swag for OpenAPI generation

Source: https://github.com/stacklok/toolhive/blob/main/docs/server/README.md

Install the swag CLI tool at version v2.0.0-rc4 using go install. Required before generating OpenAPI documentation.

```bash
# Install swag for OpenAPI generation
go install github.com/swaggo/swag/v2/cmd/swag@v2.0.0-rc4
```

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

### Install ToolHive Operator CRDs with Helm

Source: https://github.com/stacklok/toolhive/blob/main/deploy/charts/operator-crds/README.md

Installs the ToolHive Operator CRDs chart from the OCI registry. Use this command to install or upgrade the chart.

```console
helm upgrade -i toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds
```

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

### Options

Source: https://github.com/stacklok/toolhive/blob/main/docs/cli/thv_config_set-build-auth-file.md

Lists the options for the `set-build-auth-file` command.

```bash
  -h, --help    help for set-build-auth-file
      --stdin   Read file content from stdin instead of command line argument (default false)
```

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

### Install ToolHive CLI with Homebrew or winget

Source: https://github.com/stacklok/toolhive/blob/main/skills/toolhive-cli-user/SKILL.md

Installation commands for ToolHive CLI. Use Homebrew on macOS/Linux and winget on Windows. After installation, verify with `thv version`.

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

```bash
winget install stacklok.thv
```

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

### Install Redis Operator with Helm

Source: https://github.com/stacklok/toolhive/blob/main/docs/redis-storage.md

Adds the Spotahome Helm repository, updates it, and installs the redis-operator in a dedicated namespace. Run these commands from a Kubernetes cluster with Helm installed.

```bash
# Using Helm
helm repo add redis-operator https://spotahome.github.io/redis-operator
helm repo update

helm install redis-operator redis-operator/redis-operator \
  --namespace redis-operator \
  --create-namespace
```

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

### Quick start commands for server lifecycle

Source: https://github.com/stacklok/toolhive/blob/main/skills/toolhive-cli-user/SKILL.md

Common commands to run, list, inspect, view logs, stop, and remove MCP servers.

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

```bash
thv list                # List running servers
```

```bash
thv status filesystem   # Detailed server info
```

```bash
thv logs filesystem     # View logs
```

```bash
thv stop filesystem     # Stop server
```

```bash
thv rm filesystem       # Remove server
```

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

### Run a server from the registry

Source: https://github.com/stacklok/toolhive/blob/main/docs/cli/thv_run.md

Starts a server from the registry using the 'filesystem' server name.

```bash
thv run filesystem
```

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

### Options: -h, --help

Source: https://github.com/stacklok/toolhive/blob/main/docs/cli/thv_config_get-build-env.md

Displays the help flag for the get-build-env command.

```bash
  -h, --help   help for get-build-env
```

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

### Verify ToolHive CLI installation

Source: https://github.com/stacklok/toolhive/blob/main/skills/toolhive-cli-user/SKILL.md

Command to verify the ToolHive CLI installation.

```bash
thv version
```

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

### Preview and apply an upgrade

Source: https://github.com/stacklok/toolhive/blob/main/skills/toolhive-cli-user/references/EXAMPLES.md

Use `--preview` to show mutable-reference changes without persisting. Then confirm at the prompt to apply the upgrade.

```bash
# Show mutable-reference changes without persisting them.
thv ai-plugin upgrade --preview --project-root .

# After reviewing repositories and signer identities, confirm at the prompt.
thv ai-plugin upgrade example-plugin --project-root .
```

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

### Install check-jsonschema via pipx

Source: https://github.com/stacklok/toolhive/blob/main/docs/registry/schema.md

Install check-jsonschema cross-platform using pipx.

```bash
pipx install check-jsonschema
```

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

### Install check-jsonschema via Homebrew

Source: https://github.com/stacklok/toolhive/blob/main/docs/registry/schema.md

Install check-jsonschema on macOS using Homebrew.

```bash
brew install check-jsonschema
```

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

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

Source: https://github.com/stacklok/toolhive/blob/main/docs/arch/12-skills-system.md

Gets a specific skill from the registry.

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

### Description
Gets a specific skill from the registry.

### Method
GET

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

### Parameters
#### Path Parameters
- **name** (string) - Required - Registry name.
- **namespace** (string) - Required - Skill namespace.
- **skillName** (string) - Required - Skill name.

### Response
#### Success Response (200)
- **skill** (object) - Skill details.

#### Response Example
{
  "skill": {}
}
```

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

### Run remote server with OIDC authentication

Source: https://github.com/stacklok/toolhive/blob/main/skills/toolhive-cli-user/references/EXAMPLES.md

Shows two OIDC setups: full with client credentials from file, and dynamic client registration without credentials.

```bash
# Full OIDC setup
thv run https://api.example.com/mcp --name secure-api \
  --remote-auth-issuer https://auth.example.com \
  --remote-auth-client-id my-client-id \
  --remote-auth-client-secret-file /path/to/secret \
  --remote-auth-scopes "openid profile"

# Dynamic client registration (no credentials needed)
thv run https://api.example.com/mcp --name auto-api \
  --remote-auth \
  --remote-auth-issuer https://auth.example.com
```

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

### GET /api/v1beta/skills/content

Source: https://github.com/stacklok/toolhive/blob/main/docs/arch/12-skills-system.md

Gets a skill's SKILL.md body and file listing for a reference.

```APIDOC
## GET /api/v1beta/skills/content

### Description
Gets a skill's SKILL.md body and file listing for a reference.

### Method
GET

### Endpoint
/api/v1beta/skills/content

### Parameters
#### Query Parameters
- **reference** (string) - Required - The skill reference.

### Response
#### Success Response (200)
- **content** (string) - SKILL.md body.
- **files** (array) - File listing.

#### Response Example
{
  "content": "# Skill",
  "files": []
}
```

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

### Run using npx (Node.js)

Source: https://github.com/stacklok/toolhive/blob/main/docs/cli/thv_run.md

Starts a server using the npx:// protocol scheme, which uses Node.js.

```bash
thv run npx://@modelcontextprotocol/server-everything
```

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

### Setup Kind Cluster with Task

Source: https://github.com/stacklok/toolhive/blob/main/docs/kind/setup-kind-cluster.md

Run this command from the ToolHive repository to create a single-node Kind cluster and output its kubeconfig to kconfig.yaml.

```bash
task kind-setup
```

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

### Sync project installs with thv ai-plugin sync

Source: https://github.com/stacklok/toolhive/blob/main/skills/toolhive-cli-user/references/COMMANDS.md

Compares project installs with toolhive.lock.yaml. Use --check for CI to report without changes; without it, sync prompts before installing unless --yes is given. --adopt writes lock entries for existing unmanaged installs, and --prune removes plugins absent from the lock.

```bash
thv ai-plugin sync [flags]
```

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

### Step 6: Verify and Test

Source: https://github.com/stacklok/toolhive/blob/main/docs/operator/virtualmcpserver-kubernetes-guide.md

Checks that the VirtualMCPServer discovered all backends and tests connectivity via port-forward.

```bash
# Check discovered backends
kubectl get virtualmcpserver my-vmcp -o jsonpath='{.status.discoveredBackends}' | jq

# Test connectivity
kubectl port-forward service/my-vmcp 8080:8080
# Test with MCP client at http://localhost:8080
```

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

### Good CLI command delegating to pkg/

Source: https://github.com/stacklok/toolhive/blob/main/docs/cli-best-practices.md

Example of a CLI command that delegates to business logic in pkg/ and only handles formatting. This is the recommended pattern.

```go
// ✅ Good - CLI delegates to pkg/
func listCmdFunc(cmd *cobra.Command, args []string) error {
    ctx := cmd.Context()

    manager, err := workloads.NewManager(ctx)
    if err != nil {
        return fmt.Errorf("failed to create workload manager: %w", err)
    }

    workloadList, err := manager.ListWorkloads(ctx, listAll, listLabelFilter...)
    if err != nil {
        return fmt.Errorf("failed to list workloads: %w", err)
    }

    // CLI only handles formatting
    switch listFormat {
    case FormatJSON:
        return printJSONOutput(workloadList)
    default:
        printTextOutput(workloadList)
        return nil
    }
}
```

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

### Install Prometheus/Grafana Stack

Source: https://github.com/stacklok/toolhive/blob/main/examples/otel/README.md

Installs the kube-prometheus-stack with Jaeger pre-configured as a data source. Uses the prometheus-stack-values.yaml configuration file.

```bash
helm upgrade -i kube-prometheus-stack prometheus-community/kube-prometheus-stack -f prometheus-stack-values.yaml -n monitoring
```

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

### Install operator via Helm

Source: https://github.com/stacklok/toolhive/blob/main/cmd/thv-operator/README.md

Installs the ToolHive operator using Helm. Replace <release_name> and <version> with your values.

```bash
# Standard installation
helm upgrade -i <release_name> oci://ghcr.io/stacklok/toolhive/toolhive-operator --version=<version> -n toolhive-system --create-namespace
```

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

### MCPServerEntry backend example

Source: https://github.com/stacklok/toolhive/blob/main/docs/operator/virtualmcpserver-api.md

Example of an MCPServerEntry backend for a public remote server. No externalAuthConfigRef is needed because the endpoint is public.

```yaml
apiVersion: toolhive.stacklok.dev/v1beta1
kind: MCPServerEntry
metadata:
  name: context7
spec:
  remoteUrl: https://mcp.context7.com/mcp
  transport: streamable-http
  groupRef:
    name: engineering-team
  # No externalAuthConfigRef — public endpoint, no auth needed
```

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

### thv CLI usage examples

Source: https://github.com/stacklok/toolhive/blob/main/docs/arch/00-overview.md

Shows common ways to run MCP servers using the thv CLI: from a registry, from a container image, and using protocol schemes like uvx, npx, and go.

```bash
# Run from registry
thv run server-name

# Run from container image
thv run ghcr.io/example/mcp-server:latest

# Run using protocol schemes
thv run uvx://package-name
thv run npx://package-name
thv run go://package-name
```

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

### Secrets Management Initial Setup

Source: https://github.com/stacklok/toolhive/blob/main/skills/toolhive-cli-user/references/EXAMPLES.md

Configure the secret provider: encrypted (recommended) or 1Password with a service account token.

```bash
# Configure encrypted provider (recommended)
thv secret setup
# Select: encrypted
# Enter password when prompted

# Or use 1Password
export OP_SERVICE_ACCOUNT_TOKEN=your-token
thv secret setup
# Select: 1password
```

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

### Step 4: Create VirtualMCPServer

Source: https://github.com/stacklok/toolhive/blob/main/docs/operator/virtualmcpserver-kubernetes-guide.md

Creates a VirtualMCPServer that aggregates the backend MCPServers. Includes configuration for authentication, backend authentication discovery, and tool aggregation strategy.

```yaml
# virtual-mcp-server.yaml
apiVersion: toolhive.stacklok.dev/v1beta1
kind: VirtualMCPServer
metadata:
  name: my-vmcp
  namespace: default
spec:
  groupRef:
    name: my-services
  config: {}

  # Configure authentication (adjust from CLI if using OIDC)
  # For OIDC, use oidcConfigRef with a shared MCPOIDCConfig resource:
  #   type: oidc
  #   oidcConfigRef:
  #     name: my-oidc-config
  #     audience: my-vmcp
  incomingAuth:
    type: anonymous  # Or configure OIDC (see above)
    authzConfig:
      type: inline
      inline:
        policies:
          - 'permit(principal, action, resource);'

  # Backend authentication discovery
  outgoingAuth:
    source: discovered

  # Tool aggregation strategy
  aggregation:
    conflictResolution: prefix
    conflictResolutionConfig:
      prefixFormat: "{workload}_"
```

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

### Install OpenTelemetry Collector

Source: https://github.com/stacklok/toolhive/blob/main/examples/otel/README.md

Installs the OTEL collector to aggregate and forward telemetry data. Uses the otel-values.yaml configuration file.

```bash
helm upgrade -i otel-collector open-telemetry/opentelemetry-collector -f otel-values.yaml -n monitoring
```

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

### Generate and verify SDK with task commands

Source: https://github.com/stacklok/toolhive/blob/main/sdk/go/README.md

Run these commands from the repository root to refresh the OpenAPI docs and SDK snapshot/client, then run tests, lint, and verification. The generation executable is pinned to ogen-go/ogen@v1.15.0.

```bash
task docs        # refreshes the OpenAPI docs and SDK snapshot/client
task sdk-test
task sdk-lint
task sdk-verify
```

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

### List all servers

Source: https://github.com/stacklok/toolhive/blob/main/docs/arch/06-registry-system.md

Lists all available servers in the registry.

```bash
thv registry list
```
Tokens:
Raw