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..7de0756 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,45 @@ 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"] + } + } +} +``` + +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)