Skip to content
Merged
Changes from all commits
Commits
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
56 changes: 56 additions & 0 deletions docs/toolhive/guides-cli/run-mcp-servers.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -207,6 +207,62 @@ If the server comes from the registry, ToolHive can validate the tool names
against the list advertised in the image reference. An error is returned in case
ToolHive cannot find one of the specified tools.

### Override tool names and descriptions

With ToolHive you can modify how tools exposed by an MCP server are exposed to
clients. In particular, tool names and descriptions can be changed.

This is useful when you want to guide an agent toward calling a specific tool
for particular questions.

One common use case is running multiple copies of the same MCP server with
different [network access levels](./network-isolation.mdx)—one for internal
resources and another for public internet access. By overriding the tool names
and descriptions, you can help your agent choose the right server for each task.

For example, the `fetch` MCP server exposes a single `fetch` tool with a
description like:

```
"Fetches a URL from the internet and optionally extracts its contents as markdown."
```

To override this, create a configuration file with one entry under
`toolsOverride` for each tool you want to modify:

```json
{
"toolsOverride": {
"fetch": {
"name": "toolhive-docs-fetch",
"description": "Fetches a URL from https://docs.stacklok.com/toolhive website."
}
}
}
```

Then pass this file to [`thv run`](../reference/cli/thv_run.md):

```sh
thv run --tools-override override.json fetch
```

The key in the override object is the _original tool name_, while the `name`
field contains the _new name_ that clients will see.

:::info

Take care when using `--tools` and `--tools-override` together in the same
command.

Tool filtering and tool overrides work independently: filtering limits access to
a subset of tools, while overrides change how those tools appear to clients.

When using both options, `--tools` must reference the _overridden names_ (the
new names you define) since those are what clients will see.

:::

## Run a custom MCP server

To run an MCP server that isn't in the registry, you can use a
Expand Down