Skip to main content

Network isolation

Most MCP servers require network access to function properly, for example, to 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 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 not filtered by the proxy; use No isolation or Host networking if your server needs raw TCP or a non-HTTP protocol.

Proxy compatibility

Network isolation works by routing outbound traffic through an HTTP proxy. ToolHive automatically injects HTTP_PROXY, HTTPS_PROXY, and their lowercase equivalents into the MCP server container pointing to the egress proxy. The MCP server must respect these variables for outbound connections to succeed. ToolHive blocks outbound traffic from servers that bypass standard proxy environment variables (for example, servers that use raw TCP sockets or hardcoded connections).

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.

Restricting proxied traffic​

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.

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. This can include APIs, data sources, or other services that the MCP server needs to function properly.

    tip

    To allow access to all subdomains under a specific domain, add a leading period (.) in front of the hostname. For example, to allow access to all subdomains of github.com, enter .github.com in the allowed hosts list.

  • Allowed ports:
    A list of ports that the MCP server is allowed to use for outgoing connections. This can help prevent the MCP server from accessing unauthorized services or resources. For example, port 443 is the default port for HTTPS connections.

Important

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 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 configuration pictured below allows the MCP server to access api.github.com and all subdomains of githubusercontent.com on port 443 (HTTPS):

Network isolation configuration showing allowed hosts and portsNetwork isolation configuration showing allowed hosts and ports

Accessing other workloads on the same container network​

MCP servers often need to reach services running elsewhere during development, such as databases, APIs, or other local servers.

To reach a service on your host machine, enable Allow 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.

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.

Next steps​

Troubleshooting​

MCP server can't reach an external service

  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.

  3. If the logs show no outbound connection attempts at all, the server may not be respecting the HTTP_PROXY and HTTPS_PROXY environment variables that ToolHive injects. Servers that bypass standard proxy variables (for example, those using raw TCP sockets or hardcoded connections) will fail regardless of your allowed hosts configuration. See Network isolation troubleshooting in the CLI guide for more detail on diagnosing this.