Add MCP Optimizer docs (#266)

Signed-off-by: Dan Barr <6922515+danbarr@users.noreply.github.com>
Co-authored-by: Dan Barr <6922515+danbarr@users.noreply.github.com>

Author: danbarr

docs/toolhive/guides-cli/run-mcp-servers.mdx

@@ -185,7 +185,7 @@ The group must exist before you can run a server in it.
 
 :::
 
-See [Organize servers with groups](./group-management.mdx) to learn more about
+See [Organize servers into groups](./group-management.mdx) to learn more about
 organizing servers and configuring client access.
 
 ### Mount a local file or directory

docs/toolhive/guides-mcp/meta-mcp.mdx

@@ -19,7 +19,7 @@ updates the list.
 
 If you organize your MCP servers into groups, you can configure client access
 per group. This lets you control which servers each client can access. See
-[Organize servers with groups](./group-management.mdx) for details.
+[Organize servers into groups](./group-management.mdx) for details.
 
 :::
 
@@ -82,4 +82,4 @@ for some common examples.
 
 - [Client compatibility](../reference/client-compatibility.mdx)
 - [Run MCP servers](./run-mcp-servers.mdx)
-- [Organize servers with groups](./group-management.mdx)
+- [Organize servers into groups](./group-management.mdx)

docs/toolhive/guides-ui/client-configuration.mdx

@@ -0,0 +1,121 @@
+---
+title: Optimize MCP tool usage
+description:
+  Enable the MCP Optimizer to enhance tool selection and reduce token usage.
+---
+
+## Overview
+
+The ToolHive MCP Optimizer acts as an intelligent intermediary between AI
+clients and MCP servers. It provides tool discovery, unified access to multiple
+MCP servers through a single endpoint, and intelligent routing of requests to
+appropriate MCP tools.
+
+:::info[Status]
+
+The MCP Optimizer is currently experimental. If you try it out, please share
+your feedback on the [Stacklok Discord community](https://discord.gg/stacklok).
+
+:::
+
+Learn more about the MCP Optimizer, its benefits, and how it works in the
+tutorial:
+[Reduce token usage with MCP Optimizer](../tutorials/mcp-optimizer.mdx).
+
+## Enable MCP Optimizer
+
+:::note[Limitations]
+
+MCP Optimizer does not currently work on Linux hosts or with Podman Desktop on
+Windows. 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.
+
+:::
+
+To enable the MCP Optimizer in the ToolHive UI:
+
+1. Open the **Settings** (⚙️) screen and enable **MCP Optimizer** under
+   **Experimental Features**
+2. Click the **Configure** button on the notification that pops up, or go to the
+   main **MCP Servers** screen and click **MCP Optimizer** in the left sidebar
+3. Select the group that contains the MCP servers you want to optimize and click
+   **Apply Changes**
+
+ToolHive automatically updates clients that were registered with the selected
+group to use the MCP Optimizer. If you want to connect a new client, go to the
+group which is enabled for optimization and use the **Manage Clients** button to
+register it.
+
+For best results, connect your client to only the optimized group. If you
+connect it to multiple groups, ensure there is no overlap in MCP servers between
+the groups to avoid unpredictable behavior.
+
+:::info[What's happening?]
+
+When you enable MCP Optimizer, ToolHive automatically creates an internal group
+and runs the `mcp-optimizer` MCP server in that group.
+
+The MCP Optimizer server discovers the MCP servers in the selected group and
+builds an index of their tools for intelligent routing. Automatic polling keeps
+the index up to date as servers are added or removed from the optimized group.
+
+ToolHive also disconnects your AI clients from the original MCP server group and
+reconnects them to the MCP Optimizer group.
+
+:::
+
+## Customize MCP Optimizer settings
+
+To update the MCP Optimizer's default settings, click the **Advanced** menu and
+select **Customize MCP Optimizer configuration**. This opens a form where you
+can modify the `mcp-optimizer` MCP server's configuration.
+
+:::note
+
+Changes to the MCP Optimizer configuration might cause the feature to stop
+working correctly. Only modify these settings if you understand their
+implications.
+
+Generally, you should only need to change the Docker image tag and the
+environment variables detailed below.
+
+:::
+
+You can customize the MCP Optimizer's behavior using the following environment
+variables:
+
+- `MAX_TOOLS_TO_RETURN`: Number of tools to return from `find_tool` (default:
+  `8`)
+- `TOOL_DISTANCE_THRESHOLD`: Distance threshold for tool similarity (default:
+  `1.0`)
+- `MAX_TOOL_RESPONSE_TOKENS`: Maximum number of tokens to return from
+  `call_tool` (default: `None`)
+- `WORKLOAD_POLLING_INTERVAL`: Polling interval for running MCP servers, in
+  seconds (default: `60`)
+- `REGISTRY_POLLING_INTERVAL`: Polling interval for ToolHive registry, in
+  seconds (default: `86400`, 24 hours)
+
+## Disable MCP Optimizer
+
+To disable the MCP Optimizer, open the **Settings** (⚙️) screen and disable the
+**MCP Optimizer** option under the **Experimental Features** section.
+
+ToolHive stops and removes the MCP Optimizer server and reconnects your clients
+to the original MCP server group.
+
+## Troubleshooting
+
+If you encounter issues while using the MCP Optimizer, check the logs for
+debugging information. On the **MCP Optimizer** page, click the **Advanced**
+menu and select **MCP Optimizer logs**.
+
+## Related information
+
+- Tutorial:
+  [Reduce token usage with MCP Optimizer](../tutorials/mcp-optimizer.mdx)
+- [Organize MCP servers into groups](./group-management.mdx)