From 3457281f776ca24c780882366e32b1e5ce43d542 Mon Sep 17 00:00:00 2001 From: Jakub Hrozek Date: Wed, 28 Jan 2026 10:54:25 +0000 Subject: [PATCH 1/2] Document header injection for remote MCP servers Add "Inject custom headers" section to the remote server configuration guide covering the new --remote-forward-headers and --remote-forward-headers-secret flags. --- docs/toolhive/guides-cli/run-mcp-servers.mdx | 57 ++++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/docs/toolhive/guides-cli/run-mcp-servers.mdx b/docs/toolhive/guides-cli/run-mcp-servers.mdx index 3488b7e4..1029834e 100644 --- a/docs/toolhive/guides-cli/run-mcp-servers.mdx +++ b/docs/toolhive/guides-cli/run-mcp-servers.mdx @@ -769,6 +769,63 @@ thv run https://api.example.com/mcp \ --remote-auth-skip-browser ``` +#### Inject custom headers + +Some remote MCP servers require custom headers for tenant identification, API +keys, or other purposes. ToolHive can inject headers into every request +forwarded to the remote server. + +To add plaintext headers, use the `--remote-forward-headers` flag: + +```bash +thv run https://api.example.com/mcp \ + --name my-server \ + --remote-forward-headers "X-Tenant-ID=tenant123" \ + --remote-forward-headers "X-Custom-Header=value" +``` + +For sensitive values like API keys, use the `--remote-forward-headers-secret` +flag to reference values stored in ToolHive's secrets manager: + +```bash +# First, store the secret (enter the value when prompted) +thv secret set my-api-key + +# Then reference it by name +thv run https://api.example.com/mcp \ + --name my-server \ + --remote-forward-headers-secret "X-Api-Key=my-api-key" +``` + +You can combine plaintext and secret-backed headers in a single command: + +```bash +thv run https://api.example.com/mcp \ + --name my-server \ + --remote-forward-headers "X-Tenant-ID=tenant123" \ + --remote-forward-headers-secret "X-Api-Key=my-api-key" +``` + +:::warning[Security considerations] + +- Plaintext header values are stored in the server's configuration file. For + sensitive values (API keys, tokens), always use + `--remote-forward-headers-secret`. +- Secret-backed header values are resolved at runtime and never stored in + configuration files. +- Certain headers cannot be configured for security reasons, including `Host`, + `Connection`, `Transfer-Encoding`, and proxy-related headers like + `X-Forwarded-For`. + +::: + +:::tip + +The [`thv proxy`](../reference/cli/thv_proxy.md) command also supports these +flags for standalone proxy scenarios where you don't need workload management. + +::: + ### Remote server management Remote MCP servers are managed like any other ToolHive workload: From 8a9f57f5b3f9c93ea0af4c89cd2ff54639f07e6a Mon Sep 17 00:00:00 2001 From: Jakub Hrozek Date: Wed, 28 Jan 2026 21:48:59 +0000 Subject: [PATCH 2/2] Remove tip about thv proxy command The thv proxy command lacks narrative documentation explaining when to use it vs thv run, so referencing it here would confuse readers. --- docs/toolhive/guides-cli/run-mcp-servers.mdx | 7 ------- 1 file changed, 7 deletions(-) diff --git a/docs/toolhive/guides-cli/run-mcp-servers.mdx b/docs/toolhive/guides-cli/run-mcp-servers.mdx index 1029834e..f7a1ada3 100644 --- a/docs/toolhive/guides-cli/run-mcp-servers.mdx +++ b/docs/toolhive/guides-cli/run-mcp-servers.mdx @@ -819,13 +819,6 @@ thv run https://api.example.com/mcp \ ::: -:::tip - -The [`thv proxy`](../reference/cli/thv_proxy.md) command also supports these -flags for standalone proxy scenarios where you don't need workload management. - -::: - ### Remote server management Remote MCP servers are managed like any other ToolHive workload: