Document v0.29.0 workload upgrade, mcp call, and CIMD

- Add "Check for and apply upgrades" section to the CLI manage
  guide covering thv upgrade check/apply and thv list
  --check-upgrades. Notes local-runtime scope, verify-then-pull
  ordering, and no-rollback behavior.
- Add a "thv mcp call" subsection to the CLI test guide
  explaining JSON args, mutually exclusive --args/--args-file,
  and --ignore-tool-error semantics.
- Add a Client ID Metadata Document (CIMD) section to the
  embedded auth server concept doc and a cimd row to the K8s
  embedded-auth-server configuration reference.

Author: github-actions[bot]

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

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 surface an upgrade column alongside `thv list` 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 (for example, in a script), pass `--yes`. In
+non-interactive shells the command runs non-interactively automatically and
+fails if any 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)

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)

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**