From 5ca0465cd9b0ae4bd1d802ea580ae2643e9c98f8 Mon Sep 17 00:00:00 2001 From: Eleftheria Stein-Kousathana Date: Thu, 2 Oct 2025 13:59:12 +0200 Subject: [PATCH 1/2] Add docs for inbound network isolation --- .../guides-cli/custom-permissions.mdx | 6 +- .../toolhive/guides-cli/network-isolation.mdx | 57 +++++++++++++++++-- 2 files changed, 58 insertions(+), 5 deletions(-) diff --git a/docs/toolhive/guides-cli/custom-permissions.mdx b/docs/toolhive/guides-cli/custom-permissions.mdx index ef190e0..9768ca9 100644 --- a/docs/toolhive/guides-cli/custom-permissions.mdx +++ b/docs/toolhive/guides-cli/custom-permissions.mdx @@ -32,7 +32,11 @@ Profiles are defined in JSON format and can include the following properties: - `read`: List of paths on your host file system that the MCP server can read - `write`: List of file system paths that the MCP server can write to (this also implies read access) -- `network`: Network access rules for outbound connections: +- `network`: Network access rules for inbound and outbound connections: + - `inbound`: Inbound network access rules, which include: + - `allow_host`: List of allowed hostnames that can send traffic to the MCP + server. If not specified, only the container's own hostname, `localhost`, + and `127.0.0.1` are allowed. - `outbound`: Outbound network access rules, which include: - `insecure_allow_all`: If set to `true`, allows unrestricted outbound network access. This isn't recommended for production use. diff --git a/docs/toolhive/guides-cli/network-isolation.mdx b/docs/toolhive/guides-cli/network-isolation.mdx index a7df68f..f17e397 100644 --- a/docs/toolhive/guides-cli/network-isolation.mdx +++ b/docs/toolhive/guides-cli/network-isolation.mdx @@ -242,11 +242,17 @@ without editing a profile file. ## Accessing other workloads on the same container network +ToolHive allows you to configure both outbound and inbound network access for +MCP servers. 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, or when other containers need to communicate with your MCP +server. + +### Outbound access: MCP server to other workloads + To allow an MCP server to access other workloads on the same network, you need -to configure network isolation to include 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. +to configure outbound network isolation to include the appropriate hostnames and +ports. For example, in Docker environments, you can add `host.docker.internal` to access services on the host. `host.docker.internal` is a special hostname @@ -273,6 +279,49 @@ Run the MCP server with this profile: thv run --isolate-network --permission-profile ./internal-access-profile.json ``` +### Inbound access: Other containers to MCP server + +By default, the ingress proxy only allows traffic from the container's own +hostname, `localhost`, and `127.0.0.1`. If you need to allow other containers or +workloads to communicate with your MCP server, configure the +`network.inbound.allow_host` setting in your permission profile. + +This is useful when: + +- Other containers need to call your MCP server's API +- You're running multiple services that need to communicate with each other +- You need to allow traffic from specific internal hostnames or domains + +Create a permission profile that allows specific inbound hostnames: + +```json title="inbound-access-profile.json" +{ + "network": { + "inbound": { + "allow_host": ["host.docker.internal", "localhost"] + } + } +} +``` + +This profile: + +- Allows inbound traffic from `host.docker.internal` and `localhost` + +Run the MCP server with this profile: + +```bash +thv run --isolate-network --permission-profile ./inbound-access-profile.json +``` + +:::info + +If no `network.inbound` configuration is specified, the ingress proxy uses the +default behavior of allowing traffic only from the container's own hostname, +`localhost`, and `127.0.0.1`. + +::: + ## Related information - [`thv run` command reference](../reference/cli/thv_run.md) From 69eeab83d15837edcefe45f45ed4a8722b4e3032 Mon Sep 17 00:00:00 2001 From: Eleftheria Stein-Kousathana Date: Thu, 2 Oct 2025 16:51:31 +0200 Subject: [PATCH 2/2] Update docs/toolhive/guides-cli/network-isolation.mdx Co-authored-by: Dan Barr --- docs/toolhive/guides-cli/network-isolation.mdx | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/toolhive/guides-cli/network-isolation.mdx b/docs/toolhive/guides-cli/network-isolation.mdx index f17e397..7de0756 100644 --- a/docs/toolhive/guides-cli/network-isolation.mdx +++ b/docs/toolhive/guides-cli/network-isolation.mdx @@ -304,10 +304,6 @@ Create a permission profile that allows specific inbound hostnames: } ``` -This profile: - -- Allows inbound traffic from `host.docker.internal` and `localhost` - Run the MCP server with this profile: ```bash