Skip to content

Deprecate MCP Optimizer in UI, remove UI tabs from tutorial #717

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
danbarr merged 2 commits into from
Apr 15, 2026
Merged

Deprecate MCP Optimizer in UI, remove UI tabs from tutorial #717

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5df7e14
Add deprecation notice to UI Optimizer guide
danbarr Apr 15, 2026
2a87b9e
Update tutorial with note and remove UI tab
danbarr Apr 15, 2026
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
20 changes: 13 additions & 7 deletions docs/toolhive/guides-ui/mcp-optimizer.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,20 +4,26 @@ description:
Enable the MCP Optimizer to enhance tool selection and reduce token usage.
---

:::danger[Deprecated - removal on April 22, 2026]

Comment thread
danbarr marked this conversation as resolved.
The MCP Optimizer in the ToolHive UI is deprecated and will be removed on April
22, 2026. The optimizer is now built into
[Virtual MCP Server (vMCP)](../guides-vmcp/optimizer.mdx), which provides the
same tool filtering and token reduction at the team level with no per-user
configuration needed.

For details on the migration, see the
[announcement blog post](https://stacklok.com/blog/mcp-optimizer-is-now-built-into-the-stacklok-platform/).
Comment thread
danbarr marked this conversation as resolved.

:::

## 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).
Expand Down
124 changes: 18 additions & 106 deletions docs/toolhive/tutorials/mcp-optimizer.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,10 +12,13 @@ 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]
:::note[Moving to vMCP]

The MCP Optimizer is currently experimental. If you try it out, please share
your feedback on the [Stacklok Discord community](https://discord.gg/stacklok).
The optimizer is now integrated into
[Virtual MCP Server (vMCP)](../guides-vmcp/optimizer.mdx), which provides the
same tool filtering and token reduction at the team level. You can deploy it in
Kubernetes today, and a local experience is coming soon. This tutorial covers
the standalone CLI approach in the meantime.
Comment thread
danbarr marked this conversation as resolved.

:::

Expand Down Expand Up @@ -74,38 +77,16 @@ flowchart TB
- macOS: Docker Desktop, Podman Desktop, or Rancher Desktop (using dockerd)
- Windows: Docker Desktop or Rancher Desktop (using dockerd)
- Linux: any container runtime (see [Linux setup](#linux-setup))
- ToolHive UI version 0.12.0 or later
- ToolHive CLI

## Step 1: Install MCP servers in a ToolHive group

Before you can use MCP Optimizer, you need to have one or more MCP servers
running in a ToolHive group. If you don't have any MCP servers set up yet,
follow these steps:

<Tabs groupId='mode' queryString='mode'>
<TabItem value='ui' label='ToolHive UI' default>

1. Open the ToolHive UI and go to the **MCP Servers** screen
2. Ensure you're in the `default` group (or create a new group if desired)
3. Run one or more MCP servers by clicking the **Add an MCP Server** button and
selecting from the registry or using a custom server image

For this tutorial, you can run the following example MCP servers:
- `github`: Provides tools for interacting with GitHub repositories
([guide](../guides-mcp/github.mdx?mode=ui))
- `fetch`: Provides a web search tool to fetch recent news articles
- `time`: Provides a tool to get the current time in various time zones

4. Wait for the MCP servers to start and become healthy

See the [Run MCP servers](../guides-ui/run-mcp-servers.mdx) guide for more
details.

</TabItem>
<TabItem value='cli' label='ToolHive CLI'>

Run one or more MCP servers in the `default` group using the ToolHive CLI. For
this tutorial, you can run the following example MCP servers:
Run one or more MCP servers in the `default` group. For this tutorial, you can
run the following example MCP servers:

- `github`: Provides tools for interacting with GitHub repositories
([guide](../guides-mcp/github.mdx?mode=cli))
Expand All @@ -127,9 +108,6 @@ Verify the MCP servers are running:
thv list
```

</TabItem>
</Tabs>

## Step 2: Connect your AI client

Connect your AI client to the ToolHive group where the MCP servers are running
Expand All @@ -143,19 +121,6 @@ the groups to avoid unpredictable behavior.

:::

<Tabs groupId='mode' queryString='mode'>
<TabItem value='ui' label='ToolHive UI' default>

Open the ToolHive UI and use the **Manage Clients** button on the main MCP
Servers screen to register your AI client with the appropriate group (for
example, `default`).

See the [Client configuration](../guides-ui/client-configuration.mdx) guide for
more details.

</TabItem>
<TabItem value='cli' label='ToolHive CLI'>

Run the following command to register your AI client with the ToolHive group
where the MCP servers are running (for example, `default`):

Expand All @@ -166,55 +131,14 @@ thv client setup
See the [Client configuration](../guides-cli/client-configuration.mdx) guide for
more details.

</TabItem>
</Tabs>

Open your AI client and verify that it is connected to the correct MCP servers.
If you installed the `github`, `fetch`, and `time` servers, you should see
almost 50 tools available.

## Step 3: Enable MCP Optimizer

<Tabs groupId='mode' queryString='mode'>
<TabItem value='ui' label='ToolHive UI' default>

The ToolHive UI automates the setup of the MCP Optimizer.

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
`default` group and use the **Manage Clients** button to register it.

Open your AI client and check its MCP configuration. You should see a single MCP
server named `toolhive-mcp-optimizer`.

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

:::

</TabItem>
<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. If you are on Linux with native
containers, follow the steps below but see [Linux setup](#linux-setup) for the
modified `thv run` command.
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**

Expand Down Expand Up @@ -291,9 +215,6 @@ flowchart TB
client x-. 🚫 .-x def
```

</TabItem>
</Tabs>

## Step 4: Sample prompts

After you configure and run MCP Optimizer, you can use the same prompts you
Expand Down Expand Up @@ -323,14 +244,13 @@ 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
in the steps above.
and Windows. No additional configuration is needed - follow the steps above.
Comment thread
danbarr marked this conversation as resolved.

### Native containers (Docker, Podman, Rancher Desktop, and others)

:::note

Before running the command below, complete the following using the CLI tabs:
Before running the command below, complete the following:

1. [Step 1](#step-1-install-mcp-servers-in-a-toolhive-group) - install your MCP
servers
Expand Down Expand Up @@ -371,28 +291,20 @@ thv run --group optimizer --network host \

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 [Remove a server](../guides-cli/manage-mcp-servers.mdx#remove-a-server)).

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:

- Experiment with different MCP servers to see how MCP Optimizer enhances tool
selection and reduces token usage
- Monitor the performance and effectiveness of MCP Optimizer in your AI
applications
- Use the [ToolHive Playground](../guides-ui/playground.mdx) to test and refine
your prompts with MCP Optimizer
- Provide feedback on your experience with MCP Optimizer on the
[Stacklok Discord community](https://discord.gg/stacklok)
- Explore the [vMCP optimizer](../guides-vmcp/optimizer.mdx) for team-level
optimization in Kubernetes

## Related information

- [MCP Optimizer UI guide](../guides-ui/mcp-optimizer.mdx)
- [Optimize tool discovery in vMCP](../guides-vmcp/optimizer.mdx) - Kubernetes
operator approach
- [Organize MCP servers into groups](../guides-ui/group-management.mdx)
- [Optimizing LLM context](../concepts/tool-optimization.mdx) - background on
tool filtering and context pollution