Skip to main content

Optimize MCP tool 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.

Status

The MCP Optimizer is currently experimental. If you try it out, please share your feedback on the Stacklok Discord community.

Learn more about the MCP Optimizer, its benefits, and how it works in the tutorial: Reduce token usage with MCP Optimizer.

Enable MCP Optimizer​

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.

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.