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 diff --git a/docs/toolhive/guides-ui/configure-mcp-servers.mdx b/docs/toolhive/guides-ui/configure-mcp-servers.mdx index 7b2d6e90..590d7121 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,10 +126,12 @@ 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 +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 81884d5c..1503c978 100644 --- a/docs/toolhive/guides-ui/network-isolation.mdx +++ b/docs/toolhive/guides-ui/network-isolation.mdx @@ -11,14 +11,19 @@ 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. + +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 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 +39,43 @@ hardcoded connections). ::: -## Enabling network isolation +## Configuring network access + +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 access** tab in the +configuration form and choose one of three modes: + +- **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. + +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**. -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. +### Restricting proxied traffic -During the MCP server installation, select the **Network isolation** tab in the -configuration form. Click the toggle to enable it. +When you choose **Isolate behind an HTTP proxy**, the **Allowed destinations** +options appear: -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: +- **Anywhere**: allow HTTP and HTTPS traffic to any destination. +- **Selected destinations**: only allow the specific hosts and ports you list + below. + +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: - **Allowed hosts**:\ A list of hostnames or IP addresses that the MCP server is allowed to access. @@ -69,18 +98,33 @@ 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 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 -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. 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.