Skip to content

Commit 36dfbe4

Browse files
committed
Add docs for new thv run --tools-override flag.
This change adds a small section under the "Run MCP servers" page documenting how to override filter names and descriptions. Fixes #127
1 parent 091fc41 commit 36dfbe4

File tree

1 file changed

+50
-0
lines changed

1 file changed

+50
-0
lines changed

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

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -207,6 +207,56 @@ If the server comes from the registry, ToolHive can validate the tool names
207207
against the list advertised in the image reference. An error is returned in case
208208
ToolHive cannot find one of the specified tools.
209209

210+
### Override tool names and descriptions
211+
212+
With ToolHive you can change modify how tools exposed by an MCP server are
213+
exposed to clients. In particular, tool names and descriptions can be changed.
214+
215+
This can be useful in cases where network policies are applied and tool
216+
descriptions need to reflect that, or to trick an Agent into calling a specific
217+
tool when some particular question is asked.
218+
219+
Taking the `fetch` MCP server as an example, which exposes a single `fetch` tool
220+
with the a description like
221+
`"Fetches a URL from the internet and optionally extracts its contents as markdown."`
222+
223+
You can now change it by supplying a file like the following
224+
225+
```json
226+
{
227+
"toolsOverride": {
228+
"fetch": {
229+
"name": "toolhive-docs-fetch",
230+
"description": "Fetches a URL from https://docs.stacklok.com/toolhive website."
231+
}
232+
}
233+
}
234+
```
235+
236+
Which must then be passed to `thv run`
237+
238+
```sh
239+
thv run --tools-override override.json fetch
240+
```
241+
242+
Note that the key of the nested object is the _actual name_ of the tool, while
243+
the value specified in the nested object is the _overridden name_ that the
244+
Client will see.
245+
246+
:::info
247+
248+
Additional care must be taken when using `--tools` and `-tools-override`
249+
together in the same command.
250+
251+
Tool Filtering and Tool Overrides are mostly orthogonal, with the former
252+
limiting access to a subset of filters, while the latter changes how the set
253+
looks like.
254+
255+
When you want to use both, `--tools` must refer to _overridden names_, i.e. the
256+
new names you get to define, since that's what the Client will eventually see.
257+
258+
:::
259+
210260
## Run a custom MCP server
211261

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

0 commit comments

Comments
 (0)