From 54057b499b1384a10ceef0b59d657b634972ca43 Mon Sep 17 00:00:00 2001 From: Daniel Kantor Date: Wed, 8 Apr 2026 11:22:18 +0200 Subject: [PATCH 1/4] better explanation for Linux support in MCP optimizer --- docs/toolhive/guides-ui/mcp-optimizer.mdx | 8 ++-- docs/toolhive/tutorials/mcp-optimizer.mdx | 57 ++++++++++++++++++++++- 2 files changed, 58 insertions(+), 7 deletions(-) diff --git a/docs/toolhive/guides-ui/mcp-optimizer.mdx b/docs/toolhive/guides-ui/mcp-optimizer.mdx index b0a7bb56..ebaa6951 100644 --- a/docs/toolhive/guides-ui/mcp-optimizer.mdx +++ b/docs/toolhive/guides-ui/mcp-optimizer.mdx @@ -26,14 +26,12 @@ tutorial: :::note[Limitations] -MCP Optimizer does not currently work on Linux hosts or with Podman Desktop on -Windows. Supported configurations: +MCP Optimizer does not currently work with Podman Desktop on Windows or with MCP +servers that have network isolation enabled. Supported configurations: - macOS with Docker Desktop, Podman Desktop, or Rancher Desktop - Windows with Docker Desktop or Rancher Desktop - -MCP Optimizer also does not currently work with MCP servers that have network -isolation enabled. +- Linux: see [Linux setup](../tutorials/mcp-optimizer.mdx#linux-setup) ::: diff --git a/docs/toolhive/tutorials/mcp-optimizer.mdx b/docs/toolhive/tutorials/mcp-optimizer.mdx index 1eee184f..c9f6f4df 100644 --- a/docs/toolhive/tutorials/mcp-optimizer.mdx +++ b/docs/toolhive/tutorials/mcp-optimizer.mdx @@ -72,7 +72,7 @@ flowchart TB - One of the following container runtimes: - macOS: Docker Desktop, Podman Desktop, or Rancher Desktop (using dockerd) - Windows: Docker Desktop or Rancher Desktop (using dockerd) - - Linux: Not currently supported + - Linux: any container runtime (see [Linux setup](#linux-setup)) - ToolHive UI version 0.12.0 or later ## Step 1: Install MCP servers in a ToolHive group @@ -211,7 +211,8 @@ reconnects them to the MCP Optimizer group. The ToolHive UI is the recommended way to set up MCP Optimizer, but you can also -do it manually with the ToolHive CLI. +do it manually with the ToolHive CLI. If you are on Linux with native +containers, see [Linux setup](#linux-setup) instead. **Step 3.1: Run the API server** @@ -312,6 +313,58 @@ To check your token savings, you can ask the optimizer: - "How many tokens did I save using MCP Optimizer?" +## Linux setup + +The setup depends on which type of container runtime you are using. + +### VM-based container runtimes + +If you are using a container runtime that runs containers inside a virtual +machine (such as Docker Desktop for Linux), the setup is the same as on macOS +and Windows. No additional configuration is needed - follow the UI or CLI tabs +in the steps above. + +### Native containers (Docker, Podman, Rancher Desktop, and others) + +Before running the commands below, complete +[Step 1](#step-1-install-mcp-servers-in-a-toolhive-group) and +[Step 2](#step-2-connect-your-ai-client) using the CLI tabs. + +Most Linux container runtimes run containers natively on the host kernel. +Because containers run directly on the host kernel, `host.docker.internal` is +not automatically configured - unlike on macOS and Windows, where Docker Desktop +sets it up to let containers reach the host from inside a virtual machine. +Instead, you need to use the CLI and pass a couple of extra flags: + +```bash +# Create a dedicated group for the optimizer +thv group create optimizer + +# Run mcp-optimizer with host networking +thv run --group optimizer --network host \ + -e TOOLHIVE_HOST=127.0.0.1 \ + -e ALLOWED_GROUPS=default \ + mcp-optimizer +``` + +- `--network host` lets the container reach the host directly, achieving the + same result as the automatic bridge Docker Desktop sets up on macOS and + Windows. +- `TOOLHIVE_HOST` tells `mcp-optimizer` to connect to `127.0.0.1` instead of + `host.docker.internal`. +- `ALLOWED_GROUPS` tells the optimizer which group's MCP servers to discover, + index, and route requests to. Replace `default` with the name of the group you + want to optimize. + +To change which groups MCP Optimizer can optimize after initial setup, remove +the workload and run the command again with the updated `ALLOWED_GROUPS` value +(see [Remove a server](../guides-cli/manage-mcp-servers.mdx#remove-a-server)), +or edit the configuration directly via the ToolHive UI (see +[Manage MCP servers](../guides-ui/run-mcp-servers.mdx#manage-mcp-servers)). + +Scroll up to [Step 4: Sample prompts](#step-4-sample-prompts) to see how to +verify the setup. + ## What's next? Now that you've set up MCP Optimizer, consider exploring these next steps: From a9b2920411e8e4d848d8c446fe1bfd61355ad585 Mon Sep 17 00:00:00 2001 From: Daniel Kantor Date: Wed, 8 Apr 2026 11:32:19 +0200 Subject: [PATCH 2/4] fix dash style --- docs/toolhive/tutorials/mcp-optimizer.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/toolhive/tutorials/mcp-optimizer.mdx b/docs/toolhive/tutorials/mcp-optimizer.mdx index b88621c2..3dcda688 100644 --- a/docs/toolhive/tutorials/mcp-optimizer.mdx +++ b/docs/toolhive/tutorials/mcp-optimizer.mdx @@ -322,7 +322,7 @@ The setup depends on which type of container runtime you are using. If you are using a container runtime that runs containers inside a virtual machine (such as Docker Desktop for Linux), the setup is the same as on macOS -and Windows. No additional configuration is needed - follow the UI or CLI tabs +and Windows. No additional configuration is needed — follow the UI or CLI tabs in the steps above. ### Native containers (Docker, Podman, Rancher Desktop, and others) @@ -333,7 +333,7 @@ Before running the commands below, complete Most Linux container runtimes run containers natively on the host kernel. Because containers run directly on the host kernel, `host.docker.internal` is -not automatically configured - unlike on macOS and Windows, where Docker Desktop +not automatically configured — unlike on macOS and Windows, where Docker Desktop sets it up to let containers reach the host from inside a virtual machine. Instead, you need to use the CLI and pass a couple of extra flags: From f15f0f61b96cf13fa7d3307f1b4c206c042a7b4d Mon Sep 17 00:00:00 2001 From: Daniel Kantor Date: Wed, 8 Apr 2026 11:40:03 +0200 Subject: [PATCH 3/4] point to existing cli docs about running server --- docs/toolhive/tutorials/mcp-optimizer.mdx | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/docs/toolhive/tutorials/mcp-optimizer.mdx b/docs/toolhive/tutorials/mcp-optimizer.mdx index 3dcda688..aae3af7a 100644 --- a/docs/toolhive/tutorials/mcp-optimizer.mdx +++ b/docs/toolhive/tutorials/mcp-optimizer.mdx @@ -331,6 +331,19 @@ Before running the commands below, complete [Step 1](#step-1-install-mcp-servers-in-a-toolhive-group) and [Step 2](#step-2-connect-your-ai-client) using the CLI tabs. +:::note + +Before running the command below: + +- The ToolHive API server must be running. See + [Step 3.1](#step-3-enable-mcp-optimizer) for details. +- Create a dedicated group for the optimizer by following + [Step 3.2](#step-3-enable-mcp-optimizer) up to (but not including) the + `thv run mcp-optimizer` command — you will use the Linux-specific command + below instead. + +::: + Most Linux container runtimes run containers natively on the host kernel. Because containers run directly on the host kernel, `host.docker.internal` is not automatically configured — unlike on macOS and Windows, where Docker Desktop @@ -338,9 +351,6 @@ sets it up to let containers reach the host from inside a virtual machine. Instead, you need to use the CLI and pass a couple of extra flags: ```bash -# Create a dedicated group for the optimizer -thv group create optimizer - # Run mcp-optimizer with host networking thv run --group optimizer --network host \ -e TOOLHIVE_HOST=127.0.0.1 \ From 975ba9a658af7c25e7190e279e7906ba75af80ae Mon Sep 17 00:00:00 2001 From: Daniel Kantor Date: Wed, 8 Apr 2026 13:13:15 +0200 Subject: [PATCH 4/4] simplify note --- docs/toolhive/tutorials/mcp-optimizer.mdx | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/docs/toolhive/tutorials/mcp-optimizer.mdx b/docs/toolhive/tutorials/mcp-optimizer.mdx index aae3af7a..416b698f 100644 --- a/docs/toolhive/tutorials/mcp-optimizer.mdx +++ b/docs/toolhive/tutorials/mcp-optimizer.mdx @@ -333,14 +333,10 @@ Before running the commands below, complete :::note -Before running the command below: - -- The ToolHive API server must be running. See - [Step 3.1](#step-3-enable-mcp-optimizer) for details. -- Create a dedicated group for the optimizer by following - [Step 3.2](#step-3-enable-mcp-optimizer) up to (but not including) the - `thv run mcp-optimizer` command — you will use the Linux-specific command - below instead. +Follow the CLI tab in [Step 3](#step-3-enable-mcp-optimizer) first — it covers +starting the API server, creating the optimizer group, and reconfiguring your +client. When you reach the `thv run mcp-optimizer` command, use the +Linux-specific command below instead. :::