stacklok · JAORMX · Jun 4, 2026 · Jun 4, 2026 · Jun 4, 2026 · Jun 4, 2026
diff --git a/.github/upstream-projects.yaml b/.github/upstream-projects.yaml
@@ -35,7 +35,7 @@ projects:
 
   - id: toolhive
     repo: stacklok/toolhive
-    version: v0.28.3
+    version: v0.29.0
     # toolhive is a monorepo covering the CLI, the Kubernetes
     # operator, and the vMCP gateway. It also introduces cross-
     # cutting features that land in concepts/, integrations/,

diff --git a/docs/toolhive/concepts/embedded-auth-server.mdx b/docs/toolhive/concepts/embedded-auth-server.mdx
@@ -166,6 +166,36 @@ DCR-registered client gains the ability to request these scopes, including
 public clients like Claude Code, Cursor, and VS Code, so privileged scopes do
 not belong in the baseline.
 
+## Client ID Metadata Document (CIMD)
+
+DCR requires every client to register before its first authorization request.
+Some MCP clients, including recent VS Code builds, can instead present an HTTPS
+URL that hosts a Client ID Metadata Document (CIMD), letting the authorization
+server resolve client metadata on demand without a prior registration step.
+
+To allow CIMD-style client IDs, enable CIMD on the embedded authorization
+server. When enabled, the server accepts HTTPS URLs as `client_id` values,
+fetches the document from the URL, and caches the result. When disabled (the
+default), only DCR-registered `client_id` values are accepted.
+
+```yaml
+spec:
+  embeddedAuthServer:
+    cimd:
+      enabled: true
+      cacheMaxSize: 256
+      cacheFallbackTtl: '5m'
+```
+
+`cacheMaxSize` sets the LRU cache capacity (default `256`), and
+`cacheFallbackTtl` sets the TTL applied to every cached entry as a Go duration
+string (default `5m`). The CIMD fetcher does not yet honor `Cache-Control`
+headers; every cached document uses the fallback TTL.
+
+If you also set `baselineClientScopes`, those scopes apply to CIMD-resolved
+clients too. Because CIMD clients can be resolved from arbitrary HTTPS URLs,
+keep the baseline narrow.
+
 ## Session storage
 
 By default, session storage is in-memory. Upstream tokens are lost when pods

diff --git a/docs/toolhive/guides-cli/manage-mcp-servers.mdx b/docs/toolhive/guides-cli/manage-mcp-servers.mdx
@@ -161,6 +161,92 @@ thv start <REMOTE_SERVER_NAME>
 
 This will always prompt for re-authentication, even if valid tokens exist.
 
+## Check for and apply upgrades
+
+For MCP servers you ran from a registry entry (`thv run <SERVER_NAME>`),
+ToolHive can compare each workload's image and configuration against the
+registry's current entry and report when a newer version is available. This only
+works for registry-sourced workloads on the local runtime; remote servers and
+workloads run directly from an image reference report as `not-registry-sourced`.
+
+:::note
+
+Upgrade detection is not yet available for the Kubernetes operator.
+
+:::
+
+### Check for available upgrades
+
+The `thv upgrade check` command is an offline metadata comparison: it inspects
+each workload's image tag and configuration against the registry and never pulls
+images.
+
+To see a summary table for every workload (including stopped ones):
+
+```bash
+thv upgrade check
+```
+
+Each row shows the workload's current image, the candidate image the registry
+reports, the count of new environment variables the candidate declares, and a
+posture marker if the candidate's transport or permission profile differs from
+the workload's current configuration. Possible statuses are `up-to-date`,
+`upgrade-available`, `not-registry-sourced`, `server-not-found`, and `unknown`.
+
+For a detailed report on a single workload, pass its name:
+
+```bash
+thv upgrade check <SERVER_NAME>
+```
+
+The detailed report adds the registry server name, any new environment variables
+(with their descriptions and whether they're required), and the specific
+transport or permission profile changes between the running workload and the
+candidate.
+
+You can also add an upgrade column to the `thv list` output with an opt-in flag:
+
+```bash
+thv list --check-upgrades
+```
+
+The default `thv list` output is unchanged and performs no registry lookup, so
+it stays offline-friendly.
+
+### Apply an upgrade
+
+To upgrade a workload to the candidate image while preserving its configuration
+(environment variables, secrets, permission profile, transport, volumes,
+middleware), use `thv upgrade apply`:
+
+```bash
+thv upgrade apply <SERVER_NAME>
+```
+
+ToolHive resolves, verifies, and pulls the candidate image **before** touching
+the running workload, then stops the existing workload and starts a new one on
+the candidate image. There is no automatic rollback: if recreation fails after
+the existing workload is stopped, recovery is a forward operation. For an
+interactive session, the command prints what would change and prompts for
+confirmation before applying.
+
+If the candidate declares new environment variables or secrets that the workload
+does not yet supply, pass them with `--env` or `--secret`:
+
+```bash
+thv upgrade apply <SERVER_NAME> --env NEW_FLAG=true --secret api-key,target=API_KEY
+```
+
+To preview the planned changes without applying them:
+
+```bash
+thv upgrade apply <SERVER_NAME> --dry-run
+```
+
+To skip the confirmation prompt, pass `--yes`. When stdin is not a TTY (for
+example, in a script), the prompt is skipped automatically. In either case, the
+command fails if a required value is missing.
+
 ## Next steps
 
 - [Organize servers into groups](./group-management.mdx) to manage related
@@ -177,3 +263,5 @@ This will always prompt for re-authentication, even if valid tokens exist.
 - [`thv stop` command reference](../reference/cli/thv_stop.md)
 - [`thv start` command reference](../reference/cli/thv_start.md)
 - [`thv rm` command reference](../reference/cli/thv_rm.md)
+- [`thv upgrade check` command reference](../reference/cli/thv_upgrade_check.md)
+- [`thv upgrade apply` command reference](../reference/cli/thv_upgrade_apply.md)
diff --git a/docs/toolhive/guides-cli/test-mcp-servers.mdx b/docs/toolhive/guides-cli/test-mcp-servers.mdx
@@ -51,9 +51,9 @@ you can interactively test the MCP server's tools, prompts, and resources.
 
 ## `thv mcp` commands
 
-ToolHive also includes several
-[`thv mcp` commands](../reference/cli/thv_mcp_list.md) to test and validate MCP
-servers. You can list the MCP server's tools, prompts, and resources:
+ToolHive also includes several [`thv mcp` commands](../reference/cli/thv_mcp.md)
+to test and validate MCP servers. You can list the MCP server's tools, prompts,
+and resources:
 
 ```bash
 thv mcp list tools --server <SERVER_NAME_OR_URL>
@@ -78,6 +78,37 @@ directly, like `thv mcp list tools --server http://localhost:12345/mcp`.
 
 :::
 
+### Invoke a tool
+
+`thv mcp list` shows _what_ a server exposes, but not how it behaves. To invoke
+a tool directly from the CLI and inspect its result without opening the
+Inspector, use `thv mcp call`:
+
+```bash
+thv mcp call <TOOL_NAME> --server <SERVER_NAME_OR_URL>
+```
+
+Pass arguments as a JSON object via `--args` (inline) or `--args-file` (file
+path; use `-` to read from stdin). The two flags are mutually exclusive, and the
+parsed value must be a JSON object. If you supply neither flag, the tool is
+called with no arguments.
+
+For example, to call the `fetch` tool on a `fetch` MCP server:
+
+```bash
+thv mcp call fetch --server fetch --args '{"url":"https://example.com"}'
+```
+
+By default, the command exits non-zero when the tool reports an error
+(`CallToolResult.IsError=true`); pass `--ignore-tool-error` to exit zero in that
+case. Transport and protocol failures always exit non-zero.
+
+Add `--format json` to print the full `CallToolResult` instead of the default
+text rendering. This is useful for piping output into other tools or capturing
+structured content in scripts.
+
+The `--transport` and `--timeout` flags work the same way as for `thv mcp list`.
+
 ## ToolHive playground
 
 While the MCP Inspector and `thv mcp` commands are great for basic functional
@@ -103,3 +134,4 @@ about the playground's features and how to get started.
 
 - [`thv inspector` command reference](../reference/cli/thv_inspector.md)
 - [`thv mcp list` command reference](../reference/cli/thv_mcp_list.md)
+- [`thv mcp call` command reference](../reference/cli/thv_mcp_call.md)
diff --git a/docs/toolhive/guides-k8s/auth-k8s.mdx b/docs/toolhive/guides-k8s/auth-k8s.mdx
@@ -544,14 +544,15 @@ kubectl apply -f embedded-auth-config.yaml
 
 **Configuration reference:**
 
-| Field                  | Description                                                                                                                                                                                                                                                                                                               |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `issuer`               | HTTPS URL identifying this authorization server. Appears in the `iss` claim of issued JWTs.                                                                                                                                                                                                                               |
-| `signingKeySecretRefs` | References to Secrets containing JWT signing keys. First key is active; additional keys support rotation.                                                                                                                                                                                                                 |
-| `hmacSecretRefs`       | References to Secrets with symmetric keys for signing authorization codes and refresh tokens.                                                                                                                                                                                                                             |
-| `tokenLifespans`       | Configurable durations for access tokens (default: 1h), refresh tokens (default: 168h), and auth codes (default: 10m).                                                                                                                                                                                                    |
-| `upstreamProviders`    | Configuration for upstream identity providers. MCPServer and MCPRemoteProxy support one provider; VirtualMCPServer supports multiple providers for sequential authentication.                                                                                                                                             |
-| `baselineClientScopes` | Optional list of OAuth 2.0 scopes merged into every DCR-registered client's scope set. Use this when MCP clients register with a narrowed `scope` field but then request wider scopes at `/oauth/authorize`. See [Baseline scopes for DCR clients](../concepts/embedded-auth-server.mdx#baseline-scopes-for-dcr-clients). |
+| Field                  | Description                                                                                                                                                                                                                                                                                                                                                                                    |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `issuer`               | HTTPS URL identifying this authorization server. Appears in the `iss` claim of issued JWTs.                                                                                                                                                                                                                                                                                                    |
+| `signingKeySecretRefs` | References to Secrets containing JWT signing keys. First key is active; additional keys support rotation.                                                                                                                                                                                                                                                                                      |
+| `hmacSecretRefs`       | References to Secrets with symmetric keys for signing authorization codes and refresh tokens.                                                                                                                                                                                                                                                                                                  |
+| `tokenLifespans`       | Configurable durations for access tokens (default: 1h), refresh tokens (default: 168h), and auth codes (default: 10m).                                                                                                                                                                                                                                                                         |
+| `upstreamProviders`    | Configuration for upstream identity providers. MCPServer and MCPRemoteProxy support one provider; VirtualMCPServer supports multiple providers for sequential authentication.                                                                                                                                                                                                                  |
+| `baselineClientScopes` | Optional list of OAuth 2.0 scopes merged into every DCR-registered client's scope set. Use this when MCP clients register with a narrowed `scope` field but then request wider scopes at `/oauth/authorize`. See [Baseline scopes for DCR clients](../concepts/embedded-auth-server.mdx#baseline-scopes-for-dcr-clients).                                                                      |
+| `cimd`                 | Optional Client ID Metadata Document (CIMD) configuration. When `cimd.enabled` is `true`, the auth server accepts HTTPS URLs as `client_id` values and resolves them via CIMD, letting clients (for example, VS Code) authenticate without prior Dynamic Client Registration. See [Client ID Metadata Document (CIMD)](../concepts/embedded-auth-server.mdx#client-id-metadata-document-cimd). |
 
 **Step 5: Create the MCPOIDCConfig and MCPServer resources**
 

diff --git a/docs/toolhive/reference/cli/thv.md b/docs/toolhive/reference/cli/thv.md
@@ -58,6 +58,7 @@ thv [flags]
 * [thv status](thv_status.md)	 - Show detailed status of an MCP server
 * [thv stop](thv_stop.md)	 - Stop one or more MCP servers
 * [thv tui](thv_tui.md)	 - Open the interactive TUI dashboard (experimental)
+* [thv upgrade](thv_upgrade.md)	 - Manage upgrades for MCP server workloads
 * [thv version](thv_version.md)	 - Show the version of ToolHive
 * [thv vmcp](thv_vmcp.md)	 - Run and manage a Virtual MCP Server locally
 
diff --git a/docs/toolhive/reference/cli/thv_client_register.md b/docs/toolhive/reference/cli/thv_client_register.md
@@ -38,7 +38,7 @@ Valid clients:
   - lm-studio: LM Studio application
   - mistral-vibe: Mistral Vibe IDE
   - opencode: OpenCode editor
-  - roo-code: VS Code Roo Code extension
+  - roo-code: VS Code Roo Code extension (deprecated)
   - trae: Trae IDE
   - vscode: Visual Studio Code
   - vscode-insider: Visual Studio Code Insiders

diff --git a/docs/toolhive/reference/cli/thv_client_remove.md b/docs/toolhive/reference/cli/thv_client_remove.md
@@ -38,7 +38,7 @@ Valid clients:
   - lm-studio: LM Studio application
   - mistral-vibe: Mistral Vibe IDE
   - opencode: OpenCode editor
-  - roo-code: VS Code Roo Code extension
+  - roo-code: VS Code Roo Code extension (deprecated)
   - trae: Trae IDE
   - vscode: Visual Studio Code
   - vscode-insider: Visual Studio Code Insiders

diff --git a/docs/toolhive/reference/cli/thv_list.md b/docs/toolhive/reference/cli/thv_list.md
@@ -41,6 +41,7 @@ thv list [flags]
 
 ```
   -a, --all                 Show all workloads (default shows just running)
+      --check-upgrades      Check each workload for available upgrades against its source registry (performs a registry lookup)
       --format string       Output format (json, text, mcpservers) (default "text")
       --group string        Filter by group
   -h, --help                help for list

diff --git a/docs/toolhive/reference/cli/thv_mcp.md b/docs/toolhive/reference/cli/thv_mcp.md
@@ -32,6 +32,7 @@ The mcp command provides subcommands to interact with MCP (Model Context Protoco
 ### SEE ALSO
 
 * [thv](thv.md)	 - ToolHive (thv) is a lightweight, secure, and fast manager for MCP servers
+* [thv mcp call](thv_mcp_call.md)	 - Invoke a tool on an MCP server
 * [thv mcp list](thv_mcp_list.md)	 - List MCP server capabilities
 * [thv mcp serve](thv_mcp_serve.md)	 - 🧪 EXPERIMENTAL: Start an MCP server to control ToolHive
 
diff --git a/docs/toolhive/reference/cli/thv_mcp_call.md b/docs/toolhive/reference/cli/thv_mcp_call.md
@@ -0,0 +1,54 @@
+---
+title: thv mcp call
+hide_title: true
+description: Reference for ToolHive CLI command `thv mcp call`
+last_update:
+  author: autogenerated
+slug: thv_mcp_call
+mdx:
+  format: md
+---
+
+## thv mcp call
+
+Invoke a tool on an MCP server
+
+### Synopsis
+
+Invoke a tool on an MCP server. The server is connected, initialized,
+the tool is called with the supplied arguments, and the result is printed.
+
+Arguments are supplied as a JSON object via --args or --args-file. If neither
+flag is set, the tool is called with an empty argument object.
+
+By default, the command exits with a non-zero status when the tool reports an
+error (CallToolResult.IsError=true). Use --ignore-tool-error to exit zero in
+that case; transport and protocol failures always exit non-zero.
+
+```
+thv mcp call <tool-name> [flags]
+```
+
+### Options
+
+```
+      --args string         Tool arguments as a JSON object literal
+      --args-file string    Path to a file containing a JSON object of tool arguments (use '-' to read from stdin)
+      --format string       Output format (json, text) (default "text")
+  -h, --help                help for call
+      --ignore-tool-error   Exit zero even when the tool reports an error (default is non-zero)
+      --server string       MCP server URL or name from ToolHive registry (required)
+      --timeout duration    Connection timeout (default 30s)
+      --transport string    Transport type (auto, sse, streamable-http) (default "auto")
+```
+
+### Options inherited from parent commands
+
+```
+      --debug   Enable debug mode
+```
+
+### SEE ALSO
+
+* [thv mcp](thv_mcp.md)	 - Interact with MCP servers for debugging
+
diff --git a/docs/toolhive/reference/cli/thv_upgrade.md b/docs/toolhive/reference/cli/thv_upgrade.md
@@ -0,0 +1,41 @@
+---
+title: thv upgrade
+hide_title: true
+description: Reference for ToolHive CLI command `thv upgrade`
+last_update:
+  author: autogenerated
+slug: thv_upgrade
+mdx:
+  format: md
+---
+
+## thv upgrade
+
+Manage upgrades for MCP server workloads
+
+### Synopsis
+
+Inspect and apply upgrades for registry-sourced MCP server workloads.
+
+Upgrade checks compare each workload's current image and configuration against
+the metadata reported by its source registry. Checks are an offline metadata
+comparison and never pull images.
+
+### Options
+
+```
+  -h, --help   help for upgrade
+```
+
+### Options inherited from parent commands
+
+```
+      --debug   Enable debug mode
+```
+
+### SEE ALSO
+
+* [thv](thv.md)	 - ToolHive (thv) is a lightweight, secure, and fast manager for MCP servers
+* [thv upgrade apply](thv_upgrade_apply.md)	 - Apply an available upgrade to a workload
+* [thv upgrade check](thv_upgrade_check.md)	 - Check workloads for available upgrades
+