diff --git a/docs/toolhive/guides-cli/run-mcp-servers.mdx b/docs/toolhive/guides-cli/run-mcp-servers.mdx index e08a58ad..61c1d9d0 100644 --- a/docs/toolhive/guides-cli/run-mcp-servers.mdx +++ b/docs/toolhive/guides-cli/run-mcp-servers.mdx @@ -238,6 +238,109 @@ 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 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": "./fetch-audit.log" +} +``` + +When you set `logFile`, ToolHive appends audit events to that file instead of +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 + +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. + +::: + +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. 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: + +- `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 + +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. + +::: + ### Run a server on a specific port ToolHive creates a reverse proxy on a random port that forwards requests to the @@ -889,14 +992,22 @@ 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 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 +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 +1021,50 @@ 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 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 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 + `telemetryConfigRef` to the `MCPServer`. + +`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 +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