Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion docs/toolhive/guides-cli/custom-permissions.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
53 changes: 49 additions & 4 deletions docs/toolhive/guides-cli/network-isolation.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -273,6 +279,45 @@ Run the MCP server with this profile:
thv run --isolate-network --permission-profile ./internal-access-profile.json <SERVER>
```

### 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 <SERVER>
```

:::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)
Expand Down