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
21 changes: 6 additions & 15 deletions docs/toolhive/guides-mcp/context7.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -71,19 +71,15 @@ thv run context7-remote
```

Alternatively, run the local containerized MCP server with the default
configuration (you don't need an API key for basic usage):
configuration (you don't need an API key for basic usage). ToolHive
[isolates the server's network access](../guides-cli/network-isolation.mdx) by
default, using the registry's default profile, which restricts access to
`context7.com`:

```bash
thv run context7
```

Enable [network isolation](../guides-cli/network-isolation.mdx) using the
default profile from the registry to restrict the server's network access:

```bash
thv run --isolate-network context7
```

If you have a Context7 API key for higher rate limits, create a secret named
`context7` containing your API key and run the server with the `--secret` flag:

Expand All @@ -92,12 +88,6 @@ thv secret set context7
thv run --secret context7,target=CONTEXT7_API_KEY context7
```

Combine API key with network isolation:

```bash
thv run --secret context7,target=CONTEXT7_API_KEY --isolate-network context7
```

</TabItem>
<TabItem value='k8s' label='Kubernetes'>

Expand Down Expand Up @@ -174,4 +164,5 @@ Here are practical prompts you can use with the Context7 MCP server:
- Register for an API key at
[context7.com/dashboard](https://context7.com/dashboard) if you plan to make
frequent requests or need higher rate limits.
- Enable network isolation to restrict the server's outbound access.
- Network isolation restricts the server's outbound access to `context7.com` by
default.
20 changes: 13 additions & 7 deletions docs/toolhive/guides-mcp/fetch.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -33,13 +33,16 @@ allowed hosts and ports.
</TabItem>
<TabItem value='cli' label='CLI'>

Run with the default configuration:
Run with the default configuration. ToolHive
[isolates the server's network access](../guides-cli/network-isolation.mdx) by
default; the registry's default profile for `fetch` allows all outbound HTTPS
traffic, since the server needs to reach arbitrary websites:

```bash
thv run fetch
```

To control which website resources the server can access, create a custom
To restrict which website resources the server can access, create a custom
permission profile:

```json title="fetch-profile.json"
Expand All @@ -58,11 +61,13 @@ permission profile:
}
```

Then run the server with the profile and
[enable network isolation](../guides-cli/network-isolation.mdx):
Docker gateway addresses like `host.docker.internal` are blocked by an explicit
deny in the egress proxy by default, even when they're listed in `allow_host`.
Add the `--allow-docker-gateway` flag to remove that deny, then run the server
with the profile:

```bash
thv run --isolate-network --permission-profile fetch-profile.json fetch
thv run --allow-docker-gateway --permission-profile fetch-profile.json fetch
```

</TabItem>
Expand Down Expand Up @@ -102,7 +107,8 @@ Here are some sample prompts you can use to interact with the Fetch MCP server:

## Recommended practices

- Use network isolation to restrict the server's outbound network access to the
specific hosts and ports required for your use case.
- Customize the network isolation permission profile to restrict the server's
outbound network access to the specific hosts and ports required for your use
case, since the default profile allows all outbound HTTPS traffic.
- Enable [telemetry](../guides-cli/telemetry-and-metrics.mdx) to monitor tool
usage including URL access for security and auditing purposes.
11 changes: 6 additions & 5 deletions docs/toolhive/guides-mcp/filesystem.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -95,10 +95,11 @@ thv run \

:::tip

Since the server does not require any network access, add the
`--isolate-network --permission-profile none` flags to completely restrict its
outbound network access (see the
[network isolation guide](../guides-cli/network-isolation.mdx)).
The server does not require any network access, and ToolHive
[isolates its network access](../guides-cli/network-isolation.mdx) by default
using the registry's profile, which already blocks all outbound traffic. No
extra flags are needed, but you can pass `--permission-profile none` explicitly
if you want to make that restriction obvious in your command.

:::

Expand Down Expand Up @@ -168,5 +169,5 @@ server:
minimize resource usage and improve performance.
- Use read-only mounts for directories or files that do not need to be modified
by the AI agent to prevent accidental changes.
- Enable network isolation to restrict the server's outbound network access,
- Network isolation blocks the server's outbound network access by default,
since the filesystem MCP server does not require any network connectivity.
25 changes: 8 additions & 17 deletions docs/toolhive/guides-mcp/github.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -70,13 +70,10 @@ gh auth token | thv secret set github
thv run --secret github,target=GITHUB_PERSONAL_ACCESS_TOKEN github
```

Enable [network isolation](../guides-cli/network-isolation.mdx) using the
default profile from the registry (appropriate for `github.com`) to restrict the
server's network access:

```bash
thv run --isolate-network github
```
ToolHive
[isolates the server's network access](../guides-cli/network-isolation.mdx) by
default, using the registry's default profile, which restricts access to
subdomains of `github.com` and `githubusercontent.com`.

Limit the active toolsets (useful to avoid context overload) and enable
read-only mode. Refer to the
Expand All @@ -87,12 +84,6 @@ for the current list of toolsets.
thv run -e GITHUB_TOOLSETS=repos,issues,pull_requests -e GITHUB_READ_ONLY=1 github
```

Enable the MCP server's dynamic tool discovery feature (currently in beta):

```bash
thv run -e GITHUB_DYNAMIC_TOOLSETS=1 github
```

:::info[GitHub Enterprise]

Create a custom permission profile for your GitHub Enterprise instance:
Expand All @@ -114,7 +105,7 @@ Then run the server with the profile:
```bash
thv run \
-e GITHUB_HOST=https://github.your-enterprise.com \
--isolate-network --permission-profile github-enterprise-profile.json \
--permission-profile github-enterprise-profile.json \
github
```

Expand Down Expand Up @@ -204,6 +195,6 @@ Here are some sample prompts you can use to interact with the GitHub MCP server:
for your use case.
- Regularly rotate your GitHub personal access token and update the secret in
ToolHive.
- Enable network isolation to restrict the server's outbound network access.
- Limit the active toolsets to reduce context overload and improve performance,
or use dynamic tool discovery if supported by your client.
- Network isolation restricts the server's outbound access to subdomains of
`github.com` and `githubusercontent.com` by default.
- Limit the active toolsets to reduce context overload and improve performance.
15 changes: 9 additions & 6 deletions docs/toolhive/guides-mcp/grafana.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -82,9 +82,11 @@ thv run \
grafana
```

Enable [network isolation](../guides-cli/network-isolation.mdx) to restrict the
server's network access. Create a permission profile with your Grafana instance
domain:
ToolHive
[isolates the server's network access](../guides-cli/network-isolation.mdx) by
default, but since the registry can't predict your Grafana instance's domain,
the default profile allows all outbound HTTPS traffic. Create a permission
profile with your Grafana instance domain to restrict access:

```json title="grafana-profile.json"
{
Expand All @@ -104,7 +106,7 @@ Then run with the custom profile:
thv run \
-e GRAFANA_URL=https://myinstance.grafana.net \
--secret grafana-token,target=GRAFANA_SERVICE_ACCOUNT_TOKEN \
--isolate-network --permission-profile grafana-profile.json \
--permission-profile grafana-profile.json \
grafana
```

Expand Down Expand Up @@ -217,8 +219,9 @@ server:
RBAC scopes to limit access to only the datasources, dashboards, and features
required for your specific use case.
- Regularly rotate service account tokens and update the secrets in ToolHive.
- Enable network isolation to restrict the server's outbound network access to
your Grafana instance domain only.
- Customize the network isolation permission profile to restrict the server's
outbound network access to your Grafana instance domain only, since the
default profile allows all outbound HTTPS traffic.
- For dashboards with large JSON configurations, use the `get_dashboard_summary`
or `get_dashboard_property` tools to minimize context window usage instead of
retrieving the full dashboard with `get_dashboard_by_uid`.
Expand Down
17 changes: 10 additions & 7 deletions docs/toolhive/guides-mcp/k8s.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -88,9 +88,11 @@ thv run --volume $HOME/.kube:/home/nonroot/.kube:ro \
k8s
```

Enable [network isolation](../guides-cli/network-isolation.mdx) to restrict
network access to your Kubernetes cluster only. Create a custom permission
profile:
ToolHive
[isolates the server's network access](../guides-cli/network-isolation.mdx) by
default, but since the registry can't predict your cluster's API server
endpoint, the default profile allows all outbound HTTPS traffic. Create a custom
permission profile to restrict network access to your cluster only:

```json title="k8s-cluster-profile.json"
{
Expand All @@ -104,11 +106,11 @@ profile:
}
```

Then run with network isolation:
Then run with the custom profile:

```bash
thv run --volume $HOME/.kube:/home/nonroot/.kube:ro \
--isolate-network --permission-profile k8s-cluster-profile.json \
--permission-profile k8s-cluster-profile.json \
k8s
```

Expand Down Expand Up @@ -208,8 +210,9 @@ server:
(`--read-write=true`) when necessary and in controlled environments.
- **Implement proper RBAC**: When using service accounts, follow the principle
of least privilege and grant only the minimum permissions required.
- **Enable network isolation**: Restrict network access to your Kubernetes API
endpoints only, especially in production environments.
- **Customize network isolation**: Restrict network access to your Kubernetes
API endpoints only, especially in production environments, since the default
profile allows all outbound HTTPS traffic.
- **Monitor resource usage**: The server includes built-in rate limiting, but
monitor your cluster's API server load when using with AI agents.
- **Disable resource discovery in large clusters**: Use
Expand Down
15 changes: 6 additions & 9 deletions docs/toolhive/guides-mcp/osv.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -52,13 +52,10 @@ Run with the default configuration:
thv run osv
```

Enable [network isolation](../guides-cli/network-isolation.mdx) using the
default profile from the registry to restrict the server's network access to
only the OSV API:

```bash
thv run --isolate-network osv
```
ToolHive
[isolates the server's network access](../guides-cli/network-isolation.mdx) by
default, using the registry's default profile, which restricts access to only
the OSV API (`api.osv.dev`).

</TabItem>
<TabItem value='k8s' label='Kubernetes'>
Expand Down Expand Up @@ -109,8 +106,8 @@ Here are some sample prompts you can use to interact with the OSV MCP server:
- **Use batch queries** when checking multiple packages to reduce API calls and
improve performance. The batch query tool can handle multiple packages in a
single request.
- **Enable network isolation** to restrict the server's network access to only
the OSV API endpoints, improving security posture.
- **Network isolation** restricts the server's network access to only the OSV
API endpoints by default, improving security posture.
- **Specify ecosystems accurately** (npm, PyPI, Go, Maven, etc.) to ensure
accurate vulnerability matching and reduce false positives.
- **Use package URLs (PURLs)** when available for more precise package
Expand Down
Loading