stacklok · rdimitrov · Sep 15, 2025 · Sep 15, 2025
diff --git a/docs/toolhive/reference/cli/thv.md b/docs/toolhive/reference/cli/thv.md
@@ -18,7 +18,7 @@ ToolHive (thv) is a lightweight, secure, and fast manager for MCP servers
 ToolHive (thv) is a lightweight, secure, and fast manager for MCP (Model Context Protocol) servers.
 It is written in Go and has extensive test coverage—including input validation—to ensure reliability and security.
 
-Under the hood, ToolHive acts as a very thin client for the Docker/Podman Unix socket API.
+Under the hood, ToolHive acts as a very thin client for the Docker/Podman/Colima Unix socket API.
 This design choice allows it to remain both efficient and lightweight while still providing powerful,
 container-based isolation for running MCP servers.
 
@@ -47,12 +47,12 @@ thv [flags]
 * [thv proxy](thv_proxy.md)	 - Create a transparent proxy for an MCP server with authentication support
 * [thv registry](thv_registry.md)	 - Manage MCP server registry
 * [thv restart](thv_restart.md)	 - Restart a tooling server
-* [thv rm](thv_rm.md)	 - Remove an MCP server
+* [thv rm](thv_rm.md)	 - Remove one or more MCP servers
 * [thv run](thv_run.md)	 - Run an MCP server
 * [thv runtime](thv_runtime.md)	 - Commands related to the container runtime
 * [thv search](thv_search.md)	 - Search for MCP servers
 * [thv secret](thv_secret.md)	 - Manage secrets
 * [thv serve](thv_serve.md)	 - Start the ToolHive API server
-* [thv stop](thv_stop.md)	 - Stop an MCP server
+* [thv stop](thv_stop.md)	 - Stop one or more MCP servers
 * [thv version](thv_version.md)	 - Show the version of ToolHive
 
diff --git a/docs/toolhive/reference/cli/thv_rm.md b/docs/toolhive/reference/cli/thv_rm.md
@@ -11,19 +11,20 @@ mdx:
 
 ## thv rm
 
-Remove an MCP server
+Remove one or more MCP servers
 
 ### Synopsis
 
-Remove an MCP server managed by ToolHive.
+Remove one or more MCP servers managed by ToolHive.
 
 ```
-thv rm [workload-name] [flags]
+thv rm [workload-name...] [flags]
 ```
 
 ### Options
 
 ```
+      --all            Delete all workloads
       --group string   Delete all workloads in the specified group
   -h, --help           help for rm
 ```

diff --git a/docs/toolhive/reference/cli/thv_run.md b/docs/toolhive/reference/cli/thv_run.md
@@ -107,10 +107,10 @@ thv run [flags] SERVER_OR_IMAGE_OR_PROTOCOL [-- ARGS...]
       --otel-env-vars stringArray               Environment variable names to include in OpenTelemetry spans (comma-separated: ENV1,ENV2)
       --otel-headers stringArray                OpenTelemetry OTLP headers in key=value format (e.g., x-honeycomb-team=your-api-key)
       --otel-insecure                           Connect to the OpenTelemetry endpoint using HTTP instead of HTTPS
-      --otel-metrics-enabled                    Enable OTLP metrics export (when OTLP endpoint is configured)
+      --otel-metrics-enabled                    Enable OTLP metrics export (when OTLP endpoint is configured) (default true)
       --otel-sampling-rate float                OpenTelemetry trace sampling rate (0.0-1.0) (default 0.1)
       --otel-service-name string                OpenTelemetry service name (defaults to toolhive-mcp-proxy)
-      --otel-tracing-enabled                    Enable distributed tracing (when OTLP endpoint is configured)
+      --otel-tracing-enabled                    Enable distributed tracing (when OTLP endpoint is configured) (default true)
       --permission-profile string               Permission profile to use (none, network, or path to JSON file)
       --print-resolved-overlays                 Debug: show resolved container paths for tmpfs overlays
       --proxy-mode string                       Proxy mode for stdio transport (sse or streamable-http) (default "sse")
@@ -132,6 +132,7 @@ thv run [flags] SERVER_OR_IMAGE_OR_PROTOCOL [-- ARGS...]
       --target-port int                         Port for the container to expose (only applicable to SSE or Streamable HTTP transport)
       --thv-ca-bundle string                    Path to CA certificate bundle for ToolHive HTTP operations (JWKS, OIDC discovery, etc.)
       --tools stringArray                       Filter MCP server tools (comma-separated list of tool names)
+      --tools-override string                   Path to a JSON file containing overrides for MCP server tools names and descriptions
       --transport string                        Transport mode (sse, streamable-http or stdio)
   -v, --volume stringArray                      Mount a volume into the container (format: host-path:container-path[:ro])
 ```

diff --git a/docs/toolhive/reference/cli/thv_stop.md b/docs/toolhive/reference/cli/thv_stop.md
@@ -11,14 +11,14 @@ mdx:
 
 ## thv stop
 
-Stop an MCP server
+Stop one or more MCP servers
 
 ### Synopsis
 
-Stop a running MCP server managed by ToolHive.
+Stop one or more running MCP servers managed by ToolHive.
 
 ```
-thv stop [workload-name] [flags]
+thv stop [workload-name...] [flags]
 ```
 
 ### Options

diff --git a/static/api-specs/toolhive-api.yaml b/static/api-specs/toolhive-api.yaml
@@ -194,6 +194,9 @@ components:
             Port is the port on which the workload is exposed.
             This is embedded in the URL.
           type: integer
+        proxy_mode:
+          description: ProxyMode is the proxy mode for stdio transport (sse or streamable-http).
+          type: string
         remote:
           description: Remote indicates whether this is a remote workload (true) or
             a container workload (false).
@@ -326,6 +329,29 @@ components:
             If true, the value will be stored as a secret rather than as a plain environment variable
           type: boolean
       type: object
+    registry.Group:
+      properties:
+        description:
+          description: Description is a human-readable description of the group's
+            purpose and functionality
+          type: string
+        name:
+          description: Name is the identifier for the group, used when referencing
+            the group in commands
+          type: string
+        remote_servers:
+          additionalProperties:
+            $ref: '#/components/schemas/registry.RemoteServerMetadata'
+          description: RemoteServers is a map of server names to their corresponding
+            remote server definitions within this group
+          type: object
+        servers:
+          additionalProperties:
+            $ref: '#/components/schemas/registry.ImageMetadata'
+          description: Servers is a map of server names to their corresponding server
+            definitions within this group
+          type: object
+      type: object
     registry.Header:
       properties:
         choices:
@@ -527,6 +553,13 @@ components:
     registry.Registry:
       description: Full registry data
       properties:
+        groups:
+          description: Groups is a slice of group definitions containing related MCP
+            servers
+          items:
+            $ref: '#/components/schemas/registry.Group'
+          type: array
+          uniqueItems: false
         last_updated:
           description: LastUpdated is the timestamp when the registry was last updated,
             in RFC3339 format
@@ -785,24 +818,18 @@ components:
           description: ThvCABundle is the path to the CA certificate bundle for ToolHive
             HTTP operations
           type: string
-        tool_override:
-          additionalProperties:
-            $ref: '#/components/schemas/runner.ToolOverride'
-          description: |-
-            ToolOverride is the map of tool names to override. Tools to override are
-            specified as ToolOverride structs.
-          type: object
-        tool_override_file:
-          description: |-
-            ToolOverrideFile is the path to a file containing tool overrides.
-            The file is a JSON struct mapping actual names to ToolOverride structs.
-          type: string
         tools_filter:
           description: ToolsFilter is the list of tools to filter
           items:
             type: string
           type: array
           uniqueItems: false
+        tools_override:
+          additionalProperties:
+            $ref: '#/components/schemas/runner.ToolOverride'
+          description: ToolsOverride is a map from an actual tool to its overridden
+            name and/or description
+          type: object
         transport:
           description: Transport is the transport mode (stdio, sse, or streamable-http)
           type: string
@@ -869,6 +896,7 @@ components:
           items:
             type: string
           type: array
+          uniqueItems: false
         headers:
           additionalProperties:
             type: string
@@ -1137,6 +1165,11 @@ components:
             type: string
           type: array
           uniqueItems: false
+        tools_override:
+          additionalProperties:
+            $ref: '#/components/schemas/v1.toolOverride'
+          description: Tools override
+          type: object
         transport:
           description: Transport configuration
           type: string
@@ -1413,6 +1446,16 @@ components:
           description: Type of the secrets provider that was setup
           type: string
       type: object
+    v1.toolOverride:
+      description: Tool override
+      properties:
+        description:
+          description: Description of the tool
+          type: string
+        name:
+          description: Name of the tool
+          type: string
+      type: object
     v1.updateRequest:
       description: Request to update an existing workload (name cannot be changed)
       properties:
@@ -1472,6 +1515,11 @@ components:
             type: string
           type: array
           uniqueItems: false
+        tools_override:
+          additionalProperties:
+            $ref: '#/components/schemas/v1.toolOverride'
+          description: Tools override
+          type: object
         transport:
           description: Transport configuration
           type: string

diff --git a/static/api-specs/toolhive-registry-schema.json b/static/api-specs/toolhive-registry-schema.json
@@ -31,6 +31,13 @@
       },
       "additionalProperties": false
     },
+    "groups": {
+      "type": "array",
+      "description": "Collection of group definitions containing related MCP servers",
+      "items": {
+        "$ref": "#/definitions/group"
+      }
+    },
     "version": {
       "type": "string",
       "description": "Registry schema version",
@@ -546,6 +553,47 @@
         }
       },
       "additionalProperties": false
+    },
+    "group": {
+      "type": "object",
+      "description": "Group definition containing related MCP servers that can be deployed together",
+      "required": ["name", "description"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Identifier for the group, used when referencing the group in commands",
+          "pattern": "^[a-z0-9][a-z0-9-]*[a-z0-9]$",
+          "minLength": 1,
+          "maxLength": 100
+        },
+        "description": {
+          "type": "string",
+          "description": "Human-readable description of the group's purpose and functionality",
+          "minLength": 10,
+          "maxLength": 500
+        },
+        "servers": {
+          "type": "object",
+          "description": "Collection of MCP server entries within this group indexed by server name",
+          "patternProperties": {
+            "^[a-z0-9][a-z0-9-]+[a-z0-9]$": {
+              "$ref": "#/definitions/server"
+            }
+          },
+          "additionalProperties": false
+        },
+        "remote_servers": {
+          "type": "object",
+          "description": "Collection of remote MCP server entries within this group indexed by server name",
+          "patternProperties": {
+            "^[a-z0-9][a-z0-9-]+[a-z0-9]$": {
+              "$ref": "#/definitions/remote_server"
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
     }
   }
 }