Skip to content

Commit 5ca0465

Browse files
committed
Add docs for inbound network isolation
1 parent 4b6524e commit 5ca0465

File tree

2 files changed

+58
-5
lines changed

2 files changed

+58
-5
lines changed

docs/toolhive/guides-cli/custom-permissions.mdx

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,11 @@ Profiles are defined in JSON format and can include the following properties:
3232
- `read`: List of paths on your host file system that the MCP server can read
3333
- `write`: List of file system paths that the MCP server can write to (this also
3434
implies read access)
35-
- `network`: Network access rules for outbound connections:
35+
- `network`: Network access rules for inbound and outbound connections:
36+
- `inbound`: Inbound network access rules, which include:
37+
- `allow_host`: List of allowed hostnames that can send traffic to the MCP
38+
server. If not specified, only the container's own hostname, `localhost`,
39+
and `127.0.0.1` are allowed.
3640
- `outbound`: Outbound network access rules, which include:
3741
- `insecure_allow_all`: If set to `true`, allows unrestricted outbound
3842
network access. This isn't recommended for production use.

docs/toolhive/guides-cli/network-isolation.mdx

Lines changed: 53 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -242,11 +242,17 @@ without editing a profile file.
242242

243243
## Accessing other workloads on the same container network
244244

245+
ToolHive allows you to configure both outbound and inbound network access for
246+
MCP servers. This is commonly needed when your MCP server needs to communicate
247+
with databases, APIs, or other services that are running on your local host
248+
during development, or when other containers need to communicate with your MCP
249+
server.
250+
251+
### Outbound access: MCP server to other workloads
252+
245253
To allow an MCP server to access other workloads on the same network, you need
246-
to configure network isolation to include the appropriate hostnames and ports.
247-
This is commonly needed when your MCP server needs to communicate with
248-
databases, APIs, or other services that are running on your local host during
249-
development.
254+
to configure outbound network isolation to include the appropriate hostnames and
255+
ports.
250256

251257
For example, in Docker environments, you can add `host.docker.internal` to
252258
access services on the host. `host.docker.internal` is a special hostname
@@ -273,6 +279,49 @@ Run the MCP server with this profile:
273279
thv run --isolate-network --permission-profile ./internal-access-profile.json <SERVER>
274280
```
275281

282+
### Inbound access: Other containers to MCP server
283+
284+
By default, the ingress proxy only allows traffic from the container's own
285+
hostname, `localhost`, and `127.0.0.1`. If you need to allow other containers or
286+
workloads to communicate with your MCP server, configure the
287+
`network.inbound.allow_host` setting in your permission profile.
288+
289+
This is useful when:
290+
291+
- Other containers need to call your MCP server's API
292+
- You're running multiple services that need to communicate with each other
293+
- You need to allow traffic from specific internal hostnames or domains
294+
295+
Create a permission profile that allows specific inbound hostnames:
296+
297+
```json title="inbound-access-profile.json"
298+
{
299+
"network": {
300+
"inbound": {
301+
"allow_host": ["host.docker.internal", "localhost"]
302+
}
303+
}
304+
}
305+
```
306+
307+
This profile:
308+
309+
- Allows inbound traffic from `host.docker.internal` and `localhost`
310+
311+
Run the MCP server with this profile:
312+
313+
```bash
314+
thv run --isolate-network --permission-profile ./inbound-access-profile.json <SERVER>
315+
```
316+
317+
:::info
318+
319+
If no `network.inbound` configuration is specified, the ingress proxy uses the
320+
default behavior of allowing traffic only from the container's own hostname,
321+
`localhost`, and `127.0.0.1`.
322+
323+
:::
324+
276325
## Related information
277326

278327
- [`thv run` command reference](../reference/cli/thv_run.md)

0 commit comments

Comments
 (0)