From 8621c7fd3a4a50f0812b5981bee426cc67e560ab Mon Sep 17 00:00:00 2001 From: "renovate[bot]" <29139614+renovate[bot]@users.noreply.github.com> Date: Thu, 16 Jul 2026 18:08:22 +0000 Subject: [PATCH 1/4] Update stacklok/toolhive-studio to v0.38.0 Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> --- .github/upstream-projects.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/upstream-projects.yaml b/.github/upstream-projects.yaml index 2a2bace0..4001ede3 100644 --- a/.github/upstream-projects.yaml +++ b/.github/upstream-projects.yaml @@ -113,7 +113,7 @@ projects: - id: toolhive-studio repo: stacklok/toolhive-studio - version: v0.37.0 + version: v0.38.0 docs_paths: - docs/toolhive/guides-ui From cbbdef362179639ef3835a7e1570bdd2b4b161dd Mon Sep 17 00:00:00 2001 From: "claude[bot]" <41898282+claude[bot]@users.noreply.github.com> Date: Thu, 16 Jul 2026 18:30:51 +0000 Subject: [PATCH 2/4] Update UI docs for network access modes toolhive-studio v0.38.0 replaces the boolean network isolation toggle with a 3-way network access radio (none / host / proxy) and a nested allowed destinations radio (anywhere / selected). Rewrite the Studio network isolation guide and the configure-mcp-servers section to match the new UI and defaults. --- .../guides-ui/configure-mcp-servers.mdx | 12 +-- docs/toolhive/guides-ui/network-isolation.mdx | 87 ++++++++++++------- 2 files changed, 64 insertions(+), 35 deletions(-) diff --git a/docs/toolhive/guides-ui/configure-mcp-servers.mdx b/docs/toolhive/guides-ui/configure-mcp-servers.mdx index 7b2d6e90..2b24040c 100644 --- a/docs/toolhive/guides-ui/configure-mcp-servers.mdx +++ b/docs/toolhive/guides-ui/configure-mcp-servers.mdx @@ -2,7 +2,7 @@ title: Configure MCP servers description: Configure MCP server settings in the ToolHive UI, including names, groups, - ports, secrets, storage volumes, network isolation, and remote authentication. + ports, secrets, storage volumes, network access, and remote authentication. --- When you install an MCP server in the ToolHive UI, the configuration form @@ -126,11 +126,13 @@ form. This applies to both registry-installed servers and custom servers (Docker image or source package). -### Network isolation +### Network access -Restrict the MCP server's network access. This enhances security by limiting the -server's ability to communicate with external networks. See the -[Network isolation](./network-isolation.mdx) guide for details. +Choose how the MCP server reaches the network. The **Network access** tab lets +you pick between no isolation, host networking, or routing outbound HTTP and +HTTPS traffic through ToolHive's egress proxy so it can only reach the +destinations you allow. See the [Network isolation](./network-isolation.mdx) +guide for details. ## Options for remote servers diff --git a/docs/toolhive/guides-ui/network-isolation.mdx b/docs/toolhive/guides-ui/network-isolation.mdx index 81884d5c..3eef4f50 100644 --- a/docs/toolhive/guides-ui/network-isolation.mdx +++ b/docs/toolhive/guides-ui/network-isolation.mdx @@ -11,14 +11,15 @@ access APIs, download data, or communicate with other services. However, malicious or misconfigured servers can also exfiltrate sensitive data or download unwanted content. -When you install an MCP server in ToolHive, you can optionally enable _network -isolation_. This feature restricts the MCP server's network access to only the -resources you specify. +When you install an MCP server in ToolHive, you choose how the server reaches +the network. _Network isolation_ routes the server's outbound HTTP and HTTPS +traffic through an egress proxy that restricts it to the destinations you allow. :::note -Network isolation currently supports HTTP and HTTPS connections only. Other -protocols are not supported. +Network isolation supports HTTP and HTTPS connections only. Other protocols are +not filtered by the proxy; use **No isolation** or **Host networking** if your +server needs raw TCP or a non-HTTP protocol. ::: @@ -34,19 +35,42 @@ hardcoded connections). ::: -## Enabling network isolation +## Configuring network access -Network isolation is available for local MCP servers installed from the registry -or custom servers. It is not available for remote MCP servers, which are hosted -and outside of ToolHive. +Network access modes are available for local MCP servers installed from the +registry or custom servers. They do not apply to remote MCP servers, which are +hosted and reached over the internet outside of ToolHive's control. -During the MCP server installation, select the **Network isolation** tab in the -configuration form. Click the toggle to enable it. +During the MCP server installation, select the **Network access** tab in the +configuration form and choose one of three modes: -When you enable network isolation, any safe default configuration defined in the -registry is pre-loaded in the form. You can accept these defaults or customize -the settings to specify which hosts and ports the MCP server is allowed to -access: +- **No isolation**: the server has unrestricted outbound network access. Use + this for trusted servers or when your server needs a protocol other than HTTP + or HTTPS. +- **Host networking (Advanced)**: the server's container shares the host + machine's network namespace directly. No egress filtering is applied. Use this + only when you understand the security implications. +- **Isolate behind an HTTP proxy**: the server's outbound HTTP and HTTPS traffic + is routed through ToolHive's egress proxy, which only forwards connections to + the destinations you allow. + +Registry servers default to **Isolate behind an HTTP proxy** unless the registry +entry declares a different mode. Custom servers default to **No isolation**; +switch to the proxy mode to opt in. + +### Restricting proxied traffic + +When you choose **Isolate behind an HTTP proxy**, an **Allowed destinations** +radio appears: + +- **Anywhere**: allow HTTP and HTTPS traffic to any destination. +- **Selected destinations**: only allow the specific hosts and ports you list + below. + +If **Selected destinations** is chosen, any safe defaults defined by the +registry entry are pre-loaded in the form. You can accept these defaults or +customize the settings to specify which hosts and ports the MCP server is +allowed to access: - **Allowed hosts**:\ A list of hostnames or IP addresses that the MCP server is allowed to access. @@ -69,18 +93,18 @@ access: :::info[Important] -If you do not specify any allowed hosts or ports, the MCP server will not be -able to access any external resources, including the internet. This can be +If you choose **Selected destinations** but leave both allowed hosts and allowed +ports empty, the MCP server cannot reach any external resources. This can be useful for MCP servers that do not require network access or for testing -purposes. +purposes; the form displays a warning when this configuration is detected. ::: ## Example configuration -The configuration pictured below allows the MCP server to access -`api.github.com` and all subdomains of `githubusercontent.com` on port 443 -(HTTPS): +With **Isolate behind an HTTP proxy** and **Selected destinations** chosen, the +configuration pictured below allows the MCP server to access `api.github.com` +and all subdomains of `githubusercontent.com` on port 443 (HTTPS): MCP server can't reach an external service -1. Check your allowed hosts and ports. Open the server's settings and confirm - the hostname and port the server needs are listed. Network isolation only - supports HTTP and HTTPS, so direct TCP connections (databases, custom - protocols) won't work. +1. Check the network access mode and allowed destinations. Open the server's + settings, select the **Network access** tab, and confirm the mode is + appropriate for the server. If the server is set to **Isolate behind an HTTP + proxy** with **Selected destinations**, confirm the hostname and port the + server needs are listed. Proxied network isolation only supports HTTP and + HTTPS, so direct TCP connections (databases, custom protocols) won't work in + this mode. 2. Check the server logs from the **MCP servers** page. Select the server, open the logs panel, and look for connection errors or denied requests. From f58f03dc44388e8b2f0eb11397f661e755fda513 Mon Sep 17 00:00:00 2001 From: "claude[bot]" <41898282+claude[bot]@users.noreply.github.com> Date: Thu, 16 Jul 2026 18:35:41 +0000 Subject: [PATCH 3/4] Editorial polish for network access docs --- docs/toolhive/guides-ui/configure-mcp-servers.mdx | 7 +++---- docs/toolhive/guides-ui/network-isolation.mdx | 8 ++++---- 2 files changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/toolhive/guides-ui/configure-mcp-servers.mdx b/docs/toolhive/guides-ui/configure-mcp-servers.mdx index 2b24040c..6b83de4b 100644 --- a/docs/toolhive/guides-ui/configure-mcp-servers.mdx +++ b/docs/toolhive/guides-ui/configure-mcp-servers.mdx @@ -129,10 +129,9 @@ or source package). ### Network access Choose how the MCP server reaches the network. The **Network access** tab lets -you pick between no isolation, host networking, or routing outbound HTTP and -HTTPS traffic through ToolHive's egress proxy so it can only reach the -destinations you allow. See the [Network isolation](./network-isolation.mdx) -guide for details. +you pick between no isolation, host networking, and an HTTP proxy that restricts +outbound traffic to destinations you allow. See the +[Network isolation](./network-isolation.mdx) guide for details. ## Options for remote servers diff --git a/docs/toolhive/guides-ui/network-isolation.mdx b/docs/toolhive/guides-ui/network-isolation.mdx index 3eef4f50..b845fd58 100644 --- a/docs/toolhive/guides-ui/network-isolation.mdx +++ b/docs/toolhive/guides-ui/network-isolation.mdx @@ -60,14 +60,14 @@ switch to the proxy mode to opt in. ### Restricting proxied traffic -When you choose **Isolate behind an HTTP proxy**, an **Allowed destinations** -radio appears: +When you choose **Isolate behind an HTTP proxy**, the **Allowed destinations** +options appear: - **Anywhere**: allow HTTP and HTTPS traffic to any destination. - **Selected destinations**: only allow the specific hosts and ports you list below. -If **Selected destinations** is chosen, any safe defaults defined by the +When you choose **Selected destinations**, any safe defaults defined by the registry entry are pre-loaded in the form. You can accept these defaults or customize the settings to specify which hosts and ports the MCP server is allowed to access: @@ -96,7 +96,7 @@ allowed to access: If you choose **Selected destinations** but leave both allowed hosts and allowed ports empty, the MCP server cannot reach any external resources. This can be useful for MCP servers that do not require network access or for testing -purposes; the form displays a warning when this configuration is detected. +purposes; the form displays a warning in this case. ::: From 6cd0e3902b2c42b9d816db5f19b24843c296d886 Mon Sep 17 00:00:00 2001 From: "claude[bot]" <41898282+claude[bot]@users.noreply.github.com> Date: Thu, 16 Jul 2026 18:47:03 +0000 Subject: [PATCH 4/4] Fix UI network access defaults and host access Network isolation is enabled by default (matching the CLI since v0.30.1 and the REST API default), so both registry and custom servers start behind the HTTP proxy. Document the Allow host machine access option, which maps to allow_docker_gateway: Docker gateway addresses are blocked by an explicit deny even when all destinations are allowed, so the prior guidance to add host.docker.internal to the allowed hosts list was incorrect. Co-authored-by: Dan Barr Co-Authored-By: Claude Opus 4.8 (1M context) --- .../guides-ui/configure-mcp-servers.mdx | 7 ++- docs/toolhive/guides-ui/network-isolation.mdx | 55 +++++++++++++------ 2 files changed, 42 insertions(+), 20 deletions(-) diff --git a/docs/toolhive/guides-ui/configure-mcp-servers.mdx b/docs/toolhive/guides-ui/configure-mcp-servers.mdx index 6b83de4b..590d7121 100644 --- a/docs/toolhive/guides-ui/configure-mcp-servers.mdx +++ b/docs/toolhive/guides-ui/configure-mcp-servers.mdx @@ -128,9 +128,10 @@ or source package). ### Network access -Choose how the MCP server reaches the network. The **Network access** tab lets -you pick between no isolation, host networking, and an HTTP proxy that restricts -outbound traffic to destinations you allow. See the +Choose how the MCP server reaches the network. ToolHive enables network +isolation by default, routing outbound traffic through an HTTP proxy that +restricts it to the destinations you allow. The **Network access** tab lets you +keep this proxy, allow unrestricted access, or share the host network. See the [Network isolation](./network-isolation.mdx) guide for details. ## Options for remote servers diff --git a/docs/toolhive/guides-ui/network-isolation.mdx b/docs/toolhive/guides-ui/network-isolation.mdx index b845fd58..1503c978 100644 --- a/docs/toolhive/guides-ui/network-isolation.mdx +++ b/docs/toolhive/guides-ui/network-isolation.mdx @@ -15,6 +15,10 @@ When you install an MCP server in ToolHive, you choose how the server reaches the network. _Network isolation_ routes the server's outbound HTTP and HTTPS traffic through an egress proxy that restricts it to the destinations you allow. +By default, ToolHive enables network isolation for local MCP servers, matching +the ToolHive CLI. New servers start behind the HTTP proxy, and you can relax or +tighten this from the **Network access** tab as described below. + :::note Network isolation supports HTTP and HTTPS connections only. Other protocols are @@ -54,9 +58,10 @@ configuration form and choose one of three modes: is routed through ToolHive's egress proxy, which only forwards connections to the destinations you allow. -Registry servers default to **Isolate behind an HTTP proxy** unless the registry -entry declares a different mode. Custom servers default to **No isolation**; -switch to the proxy mode to opt in. +Both registry and custom servers default to **Isolate behind an HTTP proxy**, +because ToolHive enables network isolation by default. Registry servers pre-load +any allowed destinations declared in their registry entry. To give a server +unrestricted network access, switch to **No isolation**. ### Restricting proxied traffic @@ -100,6 +105,21 @@ purposes; the form displays a warning in this case. ::: +### Allowing host machine access + +When a server runs behind the HTTP proxy, ToolHive blocks connections to Docker +gateway addresses (`host.docker.internal`, `gateway.docker.internal`, and the +Docker bridge gateway IP) by default, even when you allow all destinations. +Reaching the host machine is a separate, more privileged opt-in. + +Enable **Allow host machine access** to let the server connect to these gateway +addresses. Turn this on when your MCP server needs to reach a service running on +your host machine, such as a database or a local development server. + +Host machine access is port-independent: once enabled, the gateway is reachable +on any port, regardless of the allowed ports you list. You don't need to add the +gateway hostname to the allowed hosts. + ## Example configuration With **Isolate behind an HTTP proxy** and **Selected destinations** chosen, the @@ -118,19 +138,19 @@ and all subdomains of `githubusercontent.com` on port 443 (HTTPS): ### Accessing other workloads on the same container network -To allow an MCP server to access other workloads on the same network, choose -**Isolate behind an HTTP proxy** with **Selected destinations**, then list the -appropriate hostnames and ports. This is commonly needed when your MCP server -needs to communicate with databases, APIs, or other services that are running on -your local host during development. +MCP servers often need to reach services running elsewhere during development, +such as databases, APIs, or other local servers. -For example, in Docker environments, you can add `host.docker.internal` to -access services on the host. `host.docker.internal` is a special hostname -provided by Docker that resolves to the host machine's IP address from within -containers. +To reach a service on your **host machine**, enable +[**Allow host machine access**](#allowing-host-machine-access). The server can +then connect to `host.docker.internal` (on macOS and Windows) or the Docker +bridge gateway IP (typically `172.17.0.1` on Linux) on any port. Because these +gateway addresses are blocked by default, adding them to the allowed hosts list +alone is not enough; you must enable this option. -- **Allowed hosts**: `host.docker.internal` -- **Allowed ports**: `3000` +To reach a service that is **not** on the host machine, add its hostname and +port to the allowed hosts and ports under **Selected destinations**, as +described in [Restricting proxied traffic](#restricting-proxied-traffic). ## Next steps @@ -154,9 +174,10 @@ containers. settings, select the **Network access** tab, and confirm the mode is appropriate for the server. If the server is set to **Isolate behind an HTTP proxy** with **Selected destinations**, confirm the hostname and port the - server needs are listed. Proxied network isolation only supports HTTP and - HTTPS, so direct TCP connections (databases, custom protocols) won't work in - this mode. + server needs are listed. If the server needs to reach a service on your host + machine, make sure **Allow host machine access** is enabled. Proxied network + isolation only supports HTTP and HTTPS, so direct TCP connections (databases, + custom protocols) won't work in this mode. 2. Check the server logs from the **MCP servers** page. Select the server, open the logs panel, and look for connection errors or denied requests.