better explanation for Linux support in MCP optimizer (#675)

Author: kantord

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

docs/toolhive/tutorials/mcp-optimizer.mdx

@@ -73,7 +73,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
@@ -212,7 +212,9 @@ reconnects them to the MCP Optimizer group.
 <TabItem value='cli' label='ToolHive CLI'>
 
 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, follow the steps below but see [Linux setup](#linux-setup) for the
+modified `thv run` command.
 
 **Step 3.1: Run the API server**
 
@@ -313,6 +315,68 @@ 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)
+
+:::note
+
+Before running the command below, complete the following using the CLI tabs:
+
+1. [Step 1](#step-1-install-mcp-servers-in-a-toolhive-group) - install your MCP
+   servers
+2. [Step 2](#step-2-connect-your-ai-client) - connect your AI client
+3. [Step 3](#step-3-enable-mcp-optimizer) - start the API server, create the
+   optimizer group, and reconfigure your client. When you reach the
+   `thv run mcp-optimizer` command, 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
+sets it up to let containers reach the host from inside a virtual machine.
+Instead, you need to pass a couple of extra flags:
+
+```bash
+# 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_PORT` specifies the port the API server is listening on. If you
+  started it manually with a custom port in Step 3.1, pass
+  `-e TOOLHIVE_PORT=<PORT>` here as well. Omit it if you are using the ToolHive
+  UI to run the API server.
+- `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)).
+
+See [Step 4: Sample prompts](#step-4-sample-prompts) to verify the setup.
+
 ## What's next?
 
 Now that you've set up MCP Optimizer, consider exploring these next steps: