From 933f23a816d2941f547b4a9eef51241b80383a35 Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Thu, 11 Jun 2026 23:18:07 -0400 Subject: [PATCH 1/4] Document audit, k8s export, and image verification Fill three high-priority CLI flag gaps from issue #654 in the Run MCP servers guide: - Audit logging: explain --enable-audit (built-in defaults) versus --audit-config (custom config file), what events are captured, where events go, and the audit config fields. - Export to Kubernetes: document thv export --format k8s alongside the existing JSON export, including the MCPServer manifest output and the secrets, OIDC, and telemetry settings that must be configured separately. - Image verification: document the --image-verification flag, its warn/enabled/disabled values, the warn default, and the behavior for servers with and without provenance information. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/toolhive/guides-cli/run-mcp-servers.mdx | 154 ++++++++++++++++++- 1 file changed, 150 insertions(+), 4 deletions(-) diff --git a/docs/toolhive/guides-cli/run-mcp-servers.mdx b/docs/toolhive/guides-cli/run-mcp-servers.mdx index e08a58ad..eccd98e0 100644 --- a/docs/toolhive/guides-cli/run-mcp-servers.mdx +++ b/docs/toolhive/guides-cli/run-mcp-servers.mdx @@ -238,6 +238,104 @@ to ensure the server functions correctly. ::: +### Enable audit logging + +ToolHive can record an audit trail of the MCP activity that flows through a +server's proxy. Audit events capture interactions such as client initialization, +`tools/list` and `tools/call` requests, resource reads, prompt requests, and +notifications, along with metadata like the timestamp, component name, and +outcome. + +To turn on audit logging with ToolHive's built-in defaults, use the +`--enable-audit` flag: + +```bash +thv run --enable-audit +``` + +The default configuration records each event type but omits the request and +response payloads to protect potentially sensitive data. Audit events are +written to the server's logs, so you can view them with `thv logs`: + +```bash +thv logs +``` + +Each event is emitted as a JSON object on its own line, which makes the output +easy to filter or forward to a log aggregator. + +For finer control, supply your own configuration file with the `--audit-config` +flag instead: + +```bash +thv run --audit-config ./audit.json +``` + +A configuration file lets you choose which event types to record, whether to +include request or response data, and where to send the audit log. For example: + +```json title="audit.json" +{ + "component": "fetch-server", + "includeRequestData": true, + "includeResponseData": false, + "maxDataSize": 2048, + "logFile": "/var/log/toolhive/fetch-audit.log" +} +``` + +When you set `logFile`, ToolHive appends audit events to that file instead of +the server's standard logs. Leave it unset to keep events in the logs viewed by +`thv logs`. + +:::note + +The `--enable-audit` and `--audit-config` flags are independent. Use +`--enable-audit` for the built-in defaults, or `--audit-config` to load your own +settings. When you pass `--audit-config`, you don't also need `--enable-audit`. + +::: + +Setting `includeRequestData` or `includeResponseData` to `true` can capture +sensitive arguments or results in the audit log. Enable these options only when +you understand the privacy implications, and adjust `maxDataSize` to limit how +much of each payload is recorded. + +### Verify container image signatures + +For MCP servers that run from a container image, ToolHive can check the image's +signature and provenance before launching it. Servers in the ToolHive registry +include provenance information that ToolHive uses to confirm the image was built +and signed as expected. + +Use the `--image-verification` flag to control this behavior. It accepts three +values: + +- `warn` (default): verify the image and log a warning if verification fails or + the server has no provenance information, but run the server anyway. +- `enabled`: verify the image and refuse to run the server if verification fails + or no provenance information is available. +- `disabled`: skip image verification entirely. + +```bash +thv run --image-verification enabled +``` + +For example, to enforce verification when running the `fetch` server: + +```bash +thv run --image-verification enabled fetch +``` + +:::note + +Image verification applies only to servers that have provenance information, +which currently means servers from the ToolHive registry. For a custom image +without provenance data, `warn` and `enabled` behave differently: `warn` runs +the server with a warning, while `enabled` refuses to run it. + +::: + ### Run a server on a specific port ToolHive creates a reverse proxy on a random port that forwards requests to the @@ -889,14 +987,21 @@ previously exported configurations. This is useful for: ### Export a server configuration -To export a running server's configuration to a file, use the -[`thv export`](../reference/cli/thv_export.md) command: +To export a server's configuration to a file, use the +[`thv export`](../reference/cli/thv_export.md) command. The `--format` flag +controls the output format and accepts two values: `json` (the default) and +`k8s`. ```bash -thv export +thv export [--format json|k8s] ``` -For example, to export the configuration of a running server named "fetch": +#### Export as ToolHive configuration (JSON) + +By default, `thv export` writes a ToolHive run configuration as JSON. This is +the format you use with `thv run --from-config` to recreate the same server. + +For example, to export the configuration of a server named "fetch": ```bash thv export fetch ./fetch-config.json @@ -910,6 +1015,47 @@ This creates a JSON file containing all the server's configuration, including: - Network settings - Transport configuration +#### Export as a Kubernetes resource + +To deploy the same server with the ToolHive Kubernetes operator, export it as an +`MCPServer` custom resource by setting `--format k8s`: + +```bash +thv export fetch ./fetch.yaml --format k8s +``` + +This generates a YAML manifest that you can apply to a cluster running the +operator: + +```yaml title="fetch.yaml" +apiVersion: toolhive.stacklok.dev/v1beta1 +kind: MCPServer +metadata: + name: fetch +spec: + image: ghcr.io/stackloklabs/gofetch/server:latest + transport: stdio + proxyMode: streamable-http +``` + +Some settings can't be represented inline in the `MCPServer` resource and aren't +included in the exported manifest. If the server uses any of the following, +`thv export` prints a warning and you must configure these separately before +applying the manifest: + +- **Secrets**: create the corresponding Kubernetes secrets in your cluster. +- **OIDC authentication**: create an `MCPOIDCConfig` resource and add an + `oidcConfigRef` to the `MCPServer`. +- **Telemetry**: create an `MCPTelemetryConfig` resource and add a + `telemetryConfigRef` to the `MCPServer`. + +Remote MCP servers can't be exported to Kubernetes, since the operator runs +servers as containers. + +See [Run MCP servers in Kubernetes](../guides-k8s/run-mcp-k8s.mdx) and the +[`MCPServer` CRD reference](../reference/crds/mcpserver.mdx) for details on +deploying and configuring servers with the operator. + ### Run a server from an exported configuration To run a server using a previously exported configuration, use the From 38a55c959384388430aec39ed4ac00ed311c480a Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Thu, 11 Jun 2026 23:35:34 -0400 Subject: [PATCH 2/4] Address review feedback on audit and export docs Apply Copilot review comments: name the eventTypes/excludeEventTypes audit fields and use a writable logFile path, clarify that either audit flag enables logging, fix the image-verification note contradiction, clarify thv export operates on an existing workload, and correct the Kubernetes secrets guidance to reference spec.secrets. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/toolhive/guides-cli/run-mcp-servers.mdx | 48 +++++++++++--------- 1 file changed, 27 insertions(+), 21 deletions(-) diff --git a/docs/toolhive/guides-cli/run-mcp-servers.mdx b/docs/toolhive/guides-cli/run-mcp-servers.mdx index eccd98e0..59f599a5 100644 --- a/docs/toolhive/guides-cli/run-mcp-servers.mdx +++ b/docs/toolhive/guides-cli/run-mcp-servers.mdx @@ -271,28 +271,31 @@ flag instead: thv run --audit-config ./audit.json ``` -A configuration file lets you choose which event types to record, whether to -include request or response data, and where to send the audit log. For example: +A configuration file lets you select which event types to record with +`eventTypes` (or exclude specific types with `excludeEventTypes`), choose +whether to include request or response data, and set where to send the audit +log. For example: ```json title="audit.json" { "component": "fetch-server", + "eventTypes": ["mcp_tool_call", "mcp_resource_read"], "includeRequestData": true, "includeResponseData": false, "maxDataSize": 2048, - "logFile": "/var/log/toolhive/fetch-audit.log" + "logFile": "./fetch-audit.log" } ``` When you set `logFile`, ToolHive appends audit events to that file instead of -the server's standard logs. Leave it unset to keep events in the logs viewed by -`thv logs`. +the server's standard logs. Use a path that the user running `thv` can write to. +Leave it unset to keep events in the logs viewed by `thv logs`. :::note -The `--enable-audit` and `--audit-config` flags are independent. Use -`--enable-audit` for the built-in defaults, or `--audit-config` to load your own -settings. When you pass `--audit-config`, you don't also need `--enable-audit`. +Use either flag to turn on audit logging: `--enable-audit` for the built-in +defaults, or `--audit-config` to load your own settings. `--audit-config` +enables auditing on its own, so you don't need to pass `--enable-audit` as well. ::: @@ -329,10 +332,10 @@ thv run --image-verification enabled fetch :::note -Image verification applies only to servers that have provenance information, -which currently means servers from the ToolHive registry. For a custom image -without provenance data, `warn` and `enabled` behave differently: `warn` runs -the server with a warning, while `enabled` refuses to run it. +Successful verification requires provenance information, which currently means +servers from the ToolHive registry. A custom image without provenance data is +treated as a verification failure, so the modes diverge: `warn` runs the server +with a warning, while `enabled` refuses to run it. ::: @@ -987,10 +990,11 @@ previously exported configurations. This is useful for: ### Export a server configuration -To export a server's configuration to a file, use the -[`thv export`](../reference/cli/thv_export.md) command. The `--format` flag -controls the output format and accepts two values: `json` (the default) and -`k8s`. +To export the saved run configuration of a server you've already created, use +the [`thv export`](../reference/cli/thv_export.md) command. ToolHive exports the +stored configuration of an existing workload, so the server must have been run +or created first. The `--format` flag controls the output format and accepts two +values: `json` (the default) and `k8s`. ```bash thv export [--format json|k8s] @@ -1038,12 +1042,14 @@ spec: proxyMode: streamable-http ``` -Some settings can't be represented inline in the `MCPServer` resource and aren't -included in the exported manifest. If the server uses any of the following, -`thv export` prints a warning and you must configure these separately before -applying the manifest: +Some settings aren't included in the exported manifest, because their values +live outside the run configuration or require a separate resource. If the server +uses any of the following, `thv export` prints a warning and you must configure +these separately before applying the manifest: -- **Secrets**: create the corresponding Kubernetes secrets in your cluster. +- **Secrets**: create the corresponding Kubernetes Secret objects in your + cluster, then reference them from the `MCPServer` under `spec.secrets` (each + entry takes a secret `name`, a `key`, and an optional `targetEnvName`). - **OIDC authentication**: create an `MCPOIDCConfig` resource and add an `oidcConfigRef` to the `MCPServer`. - **Telemetry**: create an `MCPTelemetryConfig` resource and add a From d60d39800f748cd3d6f91f4b88ce9021882aa1ac Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Fri, 12 Jun 2026 00:02:16 -0400 Subject: [PATCH 3/4] Clarify registry provenance is not universal The image verification section implied every registry server includes provenance information. Clarify that provenance is per-server (checkable via thv registry info) and note the effect of --image- verification enabled on servers without it, in neutral terms. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/toolhive/guides-cli/run-mcp-servers.mdx | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/toolhive/guides-cli/run-mcp-servers.mdx b/docs/toolhive/guides-cli/run-mcp-servers.mdx index 59f599a5..8002552f 100644 --- a/docs/toolhive/guides-cli/run-mcp-servers.mdx +++ b/docs/toolhive/guides-cli/run-mcp-servers.mdx @@ -307,9 +307,10 @@ much of each payload is recorded. ### Verify container image signatures For MCP servers that run from a container image, ToolHive can check the image's -signature and provenance before launching it. Servers in the ToolHive registry -include provenance information that ToolHive uses to confirm the image was built -and signed as expected. +signature and provenance before launching it. Some registry servers publish +provenance information that ToolHive uses to confirm the image was built and +signed as expected. To see whether a given server has it, check the +`Has Provenance` field in the output of `thv registry info `. Use the `--image-verification` flag to control this behavior. It accepts three values: @@ -332,10 +333,11 @@ thv run --image-verification enabled fetch :::note -Successful verification requires provenance information, which currently means -servers from the ToolHive registry. A custom image without provenance data is -treated as a verification failure, so the modes diverge: `warn` runs the server -with a warning, while `enabled` refuses to run it. +Verification succeeds only for servers that include provenance information, and +not every server does. When a server has no provenance data, `warn` runs it with +a warning while `enabled` declines to run it. If you set `enabled`, keep in mind +that it stops servers without provenance, not only servers that fail +verification. ::: From 1c1d673a8e5d7bfc3fc1091921bab35216a4435b Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Fri, 12 Jun 2026 00:07:15 -0400 Subject: [PATCH 4/4] Correct reason remote servers can't export to k8s Exporting remote servers to Kubernetes is unsupported because thv export doesn't handle it, not because the operator can't run remote servers. The operator supports remote servers via the MCPRemoteProxy resource. Reword and link to the remote MCP proxy guide. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/toolhive/guides-cli/run-mcp-servers.mdx | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/toolhive/guides-cli/run-mcp-servers.mdx b/docs/toolhive/guides-cli/run-mcp-servers.mdx index 8002552f..61c1d9d0 100644 --- a/docs/toolhive/guides-cli/run-mcp-servers.mdx +++ b/docs/toolhive/guides-cli/run-mcp-servers.mdx @@ -1057,8 +1057,9 @@ these separately before applying the manifest: - **Telemetry**: create an `MCPTelemetryConfig` resource and add a `telemetryConfigRef` to the `MCPServer`. -Remote MCP servers can't be exported to Kubernetes, since the operator runs -servers as containers. +`thv export` doesn't support exporting remote MCP servers to Kubernetes. To run +a remote server with the operator, configure an +[`MCPRemoteProxy`](../guides-k8s/remote-mcp-proxy.mdx) resource directly. See [Run MCP servers in Kubernetes](../guides-k8s/run-mcp-k8s.mdx) and the [`MCPServer` CRD reference](../reference/crds/mcpserver.mdx) for details on