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..cdbc334b 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` @@ -614,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 diff --git a/docs/toolhive/guides-cli/secrets-management.mdx b/docs/toolhive/guides-cli/secrets-management.mdx index 97e0c526..f0089330 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,36 @@ 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 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 ``. + +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. +