From 53322d2e8e42cc0c0c54e57cfc1726b0c8c6c62f Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Fri, 12 Jun 2026 10:37:24 -0400 Subject: [PATCH 1/3] Document remaining medium-priority CLI gaps Close the medium-priority gaps from #654 that fit common workflows: - run-mcp-servers: --env-file/--env-file-dir, --publish, --foreground - manage-mcp-servers: thv status, thv logs prune, --foreground on start - secrets-management: environment secrets provider and the non-interactive thv secret provider command Co-Authored-By: Claude Opus 4.8 (1M context) --- .../guides-cli/manage-mcp-servers.mdx | 24 ++++++++++ docs/toolhive/guides-cli/run-mcp-servers.mdx | 44 +++++++++++++++++++ .../guides-cli/secrets-management.mdx | 41 ++++++++++++++++- 3 files changed, 107 insertions(+), 2 deletions(-) diff --git a/docs/toolhive/guides-cli/manage-mcp-servers.mdx b/docs/toolhive/guides-cli/manage-mcp-servers.mdx index 8a0358f8..ec561b76 100644 --- a/docs/toolhive/guides-cli/manage-mcp-servers.mdx +++ b/docs/toolhive/guides-cli/manage-mcp-servers.mdx @@ -37,6 +37,18 @@ To include stopped servers in the list: thv list --all ``` +### Check server status + +For detailed status of a single server, use +[`thv status`](../reference/cli/thv_status.md): + +```bash +thv status +``` + +This reports the server's state and details beyond the summary that `thv list` +shows. Add `--format json` for machine-readable output. + ### View server logs To view logs for an MCP server, use the @@ -75,6 +87,15 @@ directory. The path depends on your platform: The specific log file path is displayed when you start a server with [`thv run`](../reference/cli/thv_run.md). +#### Prune old log files + +Log files accumulate for servers that are no longer managed by ToolHive. To +delete those orphaned log files, run: + +```bash +thv logs prune +``` + ## Lifecycle management MCP servers can be started, stopped, restarted, and removed using the ToolHive @@ -122,6 +143,9 @@ Add the `--group` flag to start all servers in a specific group: thv start --group ``` +By default, the server runs in the background. Add `--foreground` (`-f`) to keep +it attached to your terminal until it exits, which is useful for debugging. + ### Remove a server To remove an MCP server: diff --git a/docs/toolhive/guides-cli/run-mcp-servers.mdx b/docs/toolhive/guides-cli/run-mcp-servers.mdx index eb4771fa..018959d0 100644 --- a/docs/toolhive/guides-cli/run-mcp-servers.mdx +++ b/docs/toolhive/guides-cli/run-mcp-servers.mdx @@ -165,6 +165,26 @@ thv run --secret github,target=GITHUB_PERSONAL_ACCESS_TOKEN github See [Secrets management](./secrets-management.mdx) to learn how to manage secrets in ToolHive. +### Pass environment variables + +Many MCP servers read non-sensitive configuration from environment variables. +Pass them individually with `-e` / `--env`: + +```bash +thv run -e = -e = +``` + +To load variables from a file instead, use `--env-file`. To load every file in a +directory, use `--env-file-dir`: + +```bash +thv run --env-file ./server.env +thv run --env-file-dir ./env.d +``` + +For sensitive values such as API tokens, use `--secret` instead, so the value is +resolved from your secrets provider rather than passed in plaintext. + ### Run a server within a group To run an MCP server within a specific group, use the `--group` option. This @@ -351,6 +371,17 @@ specific proxy port instead, use the `--proxy-port` flag: thv run --proxy-port ``` +To publish a container's own port directly to the host (separate from the proxy +port), use `--publish` (`-p`) with `hostPort:containerPort`. Repeat the flag for +multiple ports: + +```bash +thv run --publish 8090:8080 +``` + +Most servers only need the proxy port; use `--publish` when a server exposes an +additional port you need to reach directly. + ### Override the session timeout ToolHive's proxy evicts idle MCP sessions after 2 hours by default. To raise or @@ -364,6 +395,19 @@ thv run --session-ttl 4h Set a longer value when clients hold sessions open for long-running operations, or a shorter value to free resources faster. +### Run a server in the foreground + +By default, ToolHive runs the server in the background and returns control to +your shell. To keep the process attached to your terminal until the container +exits, use the `--foreground` (`-f`) flag: + +```bash +thv run --foreground +``` + +This is useful for debugging or when you want the server's lifecycle tied to the +current shell session. + ### Run a server exposing only selected tools ToolHive can filter the tools returned to the client as result of a `tools/list` diff --git a/docs/toolhive/guides-cli/secrets-management.mdx b/docs/toolhive/guides-cli/secrets-management.mdx index 97e0c526..77b2ed0a 100644 --- a/docs/toolhive/guides-cli/secrets-management.mdx +++ b/docs/toolhive/guides-cli/secrets-management.mdx @@ -16,14 +16,24 @@ workflow requirements: - `encrypted` - ToolHive encrypts secrets using a password stored in your operating system's keyring -- `1password` - ToolHive retrieves secrets from a 1Password vault +- `1password` - ToolHive retrieves secrets from a 1Password vault (read-only) +- `environment` - ToolHive reads secrets from `TOOLHIVE_SECRET_*` environment + variables (read-only), which suits CI/CD and other automated environments -You can use only one provider at a time. To select your preferred provider, run: +You can use only one provider at a time. To select your preferred provider +interactively, run: ```bash thv secret setup ``` +For scripted or non-interactive setups, set the provider directly with +[`thv secret provider`](../reference/cli/thv_secret_provider.md): + +```bash +thv secret provider environment +``` + If you plan to use 1Password, first set up a 1Password service account and obtain an API token. See the 1Password tab below for details. @@ -87,6 +97,33 @@ thv secret get op://MCPVault/github/password Run [`thv secret list`](../reference/cli/thv_secret_list.md) to see all secrets accessible to your service account, along with their URIs. + + + +:::note + +The environment provider is read-only. ToolHive reads secret values from +environment variables and can't create, list, or delete them. + +::: + +The environment provider reads each secret from an environment variable named +`TOOLHIVE_SECRET_`. Set the variable before running a `thv` command that +needs the secret, then reference the secret by ``. + +For example, to provide a secret named `github`: + +```bash +export TOOLHIVE_SECRET_github= +thv run --secret github,target=GITHUB_PERSONAL_ACCESS_TOKEN github +``` + +Because the values come from the environment, this provider suits CI/CD +pipelines and containerized deployments that inject secrets as environment +variables. Listing secrets isn't supported for security reasons, so +[`thv secret list`](../reference/cli/thv_secret_list.md) doesn't work with this +provider. + From 42004e5a9a0e385ef20464e093192bd4e70fa0e7 Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Fri, 12 Jun 2026 10:44:35 -0400 Subject: [PATCH 2/3] Clarify environment provider selection step Apply review feedback: point readers on the Environment tab to select the provider with thv secret provider, and drop the redundant 'list' from the read-only note since listing is covered separately. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/toolhive/guides-cli/secrets-management.mdx | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/toolhive/guides-cli/secrets-management.mdx b/docs/toolhive/guides-cli/secrets-management.mdx index 77b2ed0a..f0089330 100644 --- a/docs/toolhive/guides-cli/secrets-management.mdx +++ b/docs/toolhive/guides-cli/secrets-management.mdx @@ -103,10 +103,13 @@ accessible to your service account, along with their URIs. :::note The environment provider is read-only. ToolHive reads secret values from -environment variables and can't create, list, or delete them. +environment variables and can't create or delete them. ::: +Select this provider with `thv secret provider environment` before referencing +secrets. + The environment provider reads each secret from an environment variable named `TOOLHIVE_SECRET_`. Set the variable before running a `thv` command that needs the secret, then reference the secret by ``. From e84a4427526cab7d68715de820f3a0b69bd6cff7 Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Fri, 12 Jun 2026 10:51:43 -0400 Subject: [PATCH 3/3] Document runtime image flags on thv run Add --runtime-image and --runtime-add-package under protocol schemes in the run guide. These are thv run flags that customize the on-demand protocol-scheme build; they're not available on thv build. Corrects the misplaced build-guide section reverted from #933. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/toolhive/guides-cli/run-mcp-servers.mdx | 21 ++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/toolhive/guides-cli/run-mcp-servers.mdx b/docs/toolhive/guides-cli/run-mcp-servers.mdx index 018959d0..cdbc334b 100644 --- a/docs/toolhive/guides-cli/run-mcp-servers.mdx +++ b/docs/toolhive/guides-cli/run-mcp-servers.mdx @@ -658,6 +658,27 @@ thv run go:///path/to/my-go-project +#### Customize the build image + +Because ToolHive builds the image on demand for protocol schemes, you can +customize that build at run time. To override the default base image, use +`--runtime-image`: + +```bash +thv run --runtime-image node:20-alpine npx://@modelcontextprotocol/server-filesystem +``` + +To install additional OS packages into the builder and runtime stages, use +`--runtime-add-package`. Repeat the flag for multiple packages: + +```bash +thv run --runtime-add-package git --runtime-add-package ca-certificates \ + uvx://mcp-server-git +``` + +These flags apply only to protocol-scheme runs, since that's when ToolHive +builds the image. + ### Configure network transport When you run custom MCP servers using the SSE (`--transport sse`) or Streamable