From 0990f77f97bb4adb4911b446f090b2e2fcaef656 Mon Sep 17 00:00:00 2001 From: Samuele Verzi Date: Tue, 28 Oct 2025 15:38:51 +0100 Subject: [PATCH 1/3] feat(ui-guides): add customize tools --- docs/toolhive/guides-ui/customize-tools.mdx | 134 ++++++++++++++++++++ sidebars.ts | 1 + 2 files changed, 135 insertions(+) create mode 100644 docs/toolhive/guides-ui/customize-tools.mdx diff --git a/docs/toolhive/guides-ui/customize-tools.mdx b/docs/toolhive/guides-ui/customize-tools.mdx new file mode 100644 index 0000000..a437711 --- /dev/null +++ b/docs/toolhive/guides-ui/customize-tools.mdx @@ -0,0 +1,134 @@ +--- +title: Customize tools +description: + Select which tools from an MCP server are available to your AI clients using + the ToolHive UI. +--- + +ToolHive lets you customize which tools from a running MCP server are available +to your AI clients. This gives you fine-grained control over the capabilities +exposed by each server, helping you create focused tool sets and reduce +complexity for your AI workflows. + +## Why customize tools? + +Customizing tools helps you: + +- **Reduce complexity**: Hide tools that aren't relevant to your workflow, + making it easier for AI clients to select the right tool +- **Improve performance**: Fewer tools mean faster tool selection and reduced + token usage in AI interactions +- **Enhance security**: Limit exposure to only the tools you need, reducing the + risk of unintended actions +- **Create focused environments**: Tailor tool availability to specific tasks or + projects + +:::info[Registry servers only] + +Tool customization is available only for MCP servers installed from the +registry. Custom local and remote MCP servers do not support this feature. + +::: + +## Access tool customization + +To customize tools for a running MCP server: + +1. Open the **MCP Servers** page. +1. Find the server you want to customize and click the menu (︙) on its card. +1. Select **Customize Tools** from the dropdown menu. + +The customize tools page displays all available tools from the MCP server, each +with a toggle switch and description. + +:::note[Server must be running] + +The MCP server must be running to view and customize tools. If the server is +stopped when you access the customize tools page, you'll see a message prompting +you to start the server first. + +::: + +## Enable or disable tools + +On the customize tools page: + +1. Review the list of available tools and their descriptions. +1. Use the toggle switches to enable or disable individual tools: + - **Green (enabled)**: The tool is available to AI clients + - **Gray (disabled)**: The tool is hidden from AI clients +1. Click **Apply** to save your changes. + +The ToolHive proxy filters out disabled tools when AI clients connect to the +server. Clients only see and can only call the tools you've enabled. + +:::warning[At least one tool required] + +You must keep at least one tool enabled. ToolHive prevents you from disabling +all tools on a server, as this would make the server non-functional. + +::: + +## How filtering works + +When you customize tools: + +1. You toggle tools on or off using the switches. +1. After clicking **Apply**, your settings are saved to the server + configuration. +1. The ToolHive proxy intercepts tool discovery requests from AI clients. +1. Only enabled tools appear in the client's tool list. +1. If a client attempts to call a disabled tool directly, the proxy blocks the + request. + +This filtering happens transparently without requiring any changes to your AI +client configuration. Your clients automatically see the updated tool list the +next time they connect. + +:::tip + +If you change tool settings while a client is connected, you may need to restart +the client session to see the updated tool list. Some clients cache tool lists +and don't automatically refresh. + +::: + +## Example workflows + +### Focus on specific GitHub operations + +If you're using the GitHub MCP server but only need pull request tools: + +1. Open **Customize Tools** for the GitHub server. +1. Disable all tools except those related to pull requests (like + `create_pull_request`, `get_pull_request`, `list_pull_requests`). +1. Your AI clients now see only pull request tools, making it easier to work + with GitHub PRs without distraction from issue, branch, or repository tools. + +### Create environment-specific tool sets + +If you're running the same MCP server in different groups for different +environments: + +1. Copy the server to multiple groups (see + [Organize servers into groups](./group-management.mdx)). +1. Customize tools in each group to match the environment's needs. +1. For example, enable only read-only tools in a production group, while + allowing all tools in a development group. + +## Reset to defaults + +To restore all tools to their default enabled state: + +1. Open the customize tools page for the server. +1. Manually enable all tools using the toggle switches. +1. Click **Apply** to save your changes. + +There is no automatic "reset all" button, but you can quickly enable all tools +by toggling each switch and clicking **Apply**. + +## Related information + +- [Run MCP servers](./run-mcp-servers.mdx) +- [Organize servers into groups](./group-management.mdx) +- [Client configuration](./client-configuration.mdx) diff --git a/sidebars.ts b/sidebars.ts index 1c641b2..d4e324d 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -62,6 +62,7 @@ const sidebars: SidebarsConfig = { 'toolhive/guides-ui/group-management', 'toolhive/guides-ui/secrets-management', 'toolhive/guides-ui/network-isolation', + 'toolhive/guides-ui/customize-tools', ], }, 'toolhive/guides-ui/client-configuration', From 38fc2f547c6a2b22fb2153b23fa3a74fb7c3950d Mon Sep 17 00:00:00 2001 From: Samuele Verzi Date: Thu, 6 Nov 2025 16:14:22 +0100 Subject: [PATCH 2/3] feat: add tool override for customize tools --- docs/toolhive/guides-ui/customize-tools.mdx | 95 ++++++++++++++++++--- 1 file changed, 81 insertions(+), 14 deletions(-) diff --git a/docs/toolhive/guides-ui/customize-tools.mdx b/docs/toolhive/guides-ui/customize-tools.mdx index a437711..220b5bd 100644 --- a/docs/toolhive/guides-ui/customize-tools.mdx +++ b/docs/toolhive/guides-ui/customize-tools.mdx @@ -6,9 +6,10 @@ description: --- ToolHive lets you customize which tools from a running MCP server are available -to your AI clients. This gives you fine-grained control over the capabilities -exposed by each server, helping you create focused tool sets and reduce -complexity for your AI workflows. +to your AI clients. You can enable or disable individual tools, and customize +their names and descriptions. This gives you fine-grained control over the +capabilities exposed by each server, helping you create focused tool sets and +reduce complexity for your AI workflows. ## Why customize tools? @@ -22,11 +23,18 @@ Customizing tools helps you: risk of unintended actions - **Create focused environments**: Tailor tool availability to specific tasks or projects +- **Clarify tool purpose**: Edit tool names and descriptions to make them more + understandable for your specific use case -:::info[Registry servers only] +:::info[Registry match required] -Tool customization is available only for MCP servers installed from the -registry. Custom local and remote MCP servers do not support this feature. +Tool customization is only available for MCP servers that match an entry in the +registry. This includes: + +- Servers installed directly from the registry +- Custom servers with a docker image or URL that matches a registry entry + +Custom servers that don't match any registry entry do not support this feature. ::: @@ -69,21 +77,59 @@ all tools on a server, as this would make the server non-functional. ::: +## Edit tool names and descriptions + +You can customize the name and description of any tool to make it more suitable +for your workflow. This is useful when the default tool name or description is +unclear, or when you want to adapt the tool's presentation to your specific use +case. + +To edit a tool: + +1. On the customize tools page, find the tool you want to edit. +1. Click the **Edit** button next to the tool. +1. In the dialog that opens: + - Edit the **Tool** field to change the tool's name. + - Edit the **Description** field to customize the tool's description. + - The original values are shown as helper text for reference. + - Leave either field empty to reset it to the original value. +1. Click **Save** to apply your changes, or **Cancel** to discard them. + +Tools with custom names or descriptions are marked with a wrench icon to +indicate they have custom overrides applied. The icon color indicates the +status: + +- **Orange**: The tool has unsaved custom overrides +- **Primary color**: The tool has saved custom overrides + +Your customizations are preserved even if you disable and re-enable the tool. + +:::tip[Unsaved custom overrides] + +If you customize a tool's name or description but haven't clicked **Apply** on +the main page, a tooltip appears indicating "This tool has unsaved custom +overrides". Click **Apply** to save both your tool selection changes and custom +overrides. + +::: + ## How filtering works When you customize tools: -1. You toggle tools on or off using the switches. +1. You toggle tools on or off using the switches and optionally edit their names + and descriptions. 1. After clicking **Apply**, your settings are saved to the server configuration. 1. The ToolHive proxy intercepts tool discovery requests from AI clients. -1. Only enabled tools appear in the client's tool list. +1. Only enabled tools appear in the client's tool list, with your custom names + and descriptions if you've set them. 1. If a client attempts to call a disabled tool directly, the proxy blocks the request. This filtering happens transparently without requiring any changes to your AI -client configuration. Your clients automatically see the updated tool list the -next time they connect. +client configuration. Your clients automatically see the updated tool list with +customized names and descriptions the next time they connect. :::tip @@ -116,17 +162,38 @@ environments: 1. For example, enable only read-only tools in a production group, while allowing all tools in a development group. +### Clarify technical tool names + +If an MCP server exposes tools with technical or unclear names: + +1. Open **Customize Tools** for the server. +1. Click **Edit** on tools with unclear names. +1. Change the tool name to something more descriptive (for example, rename + `list_commits_test` to `List Commits`). +1. Update the description to clarify what the tool does in your context. +1. Click **Save**, then **Apply**. +1. Your AI clients now see clearer, more intuitive tool names and descriptions. + ## Reset to defaults -To restore all tools to their default enabled state: +To restore all tools to their default enabled state and remove custom overrides: + +**To reset an individual tool's name or description:** + +1. Click the **Edit** button next to the tool. +1. Clear the **Tool** and **Description** fields (leave them empty). +1. Click **Save**. +1. Click **Apply** to save your changes. + +The tool name and description revert to their original values, and the wrench +icon is removed. + +**To enable all tools:** 1. Open the customize tools page for the server. 1. Manually enable all tools using the toggle switches. 1. Click **Apply** to save your changes. -There is no automatic "reset all" button, but you can quickly enable all tools -by toggling each switch and clicking **Apply**. - ## Related information - [Run MCP servers](./run-mcp-servers.mdx) From 9224592fd111931405f9eea12b59bad622fd45bc Mon Sep 17 00:00:00 2001 From: Samuele Verzi Date: Thu, 6 Nov 2025 16:14:44 +0100 Subject: [PATCH 3/3] feat: reference customize tools in other guides --- docs/toolhive/guides-ui/group-management.mdx | 12 ++++++++++++ docs/toolhive/guides-ui/playground.mdx | 9 +++++++++ docs/toolhive/guides-ui/registry.mdx | 2 ++ docs/toolhive/guides-ui/run-mcp-servers.mdx | 2 ++ 4 files changed, 25 insertions(+) diff --git a/docs/toolhive/guides-ui/group-management.mdx b/docs/toolhive/guides-ui/group-management.mdx index db5688a..5b4c85e 100644 --- a/docs/toolhive/guides-ui/group-management.mdx +++ b/docs/toolhive/guides-ui/group-management.mdx @@ -132,6 +132,18 @@ You cannot delete the `default` group. 4. Use a different client or manually configure clients to access the "production" group when needed. +### Create environment-specific tool sets + +If you're running the same MCP server in different groups for different +environments: + +1. Copy the server to multiple groups (see + [Copy a server to a different group](#copy-a-server-to-a-different-group)). +2. Customize tools in each group to match the environment's needs (see + [Customize tools](./customize-tools.mdx)). +3. For example, enable only read-only tools in a production group, while + allowing all tools in a development group. + ### Project-based organization 1. Create groups for each project: "webapp-frontend", "webapp-backend", and diff --git a/docs/toolhive/guides-ui/playground.mdx b/docs/toolhive/guides-ui/playground.mdx index ca0eebe..ac16a28 100644 --- a/docs/toolhive/guides-ui/playground.mdx +++ b/docs/toolhive/guides-ui/playground.mdx @@ -77,6 +77,15 @@ To start using the playground: - The `toolhive mcp` server is included by default, providing management capabilities +:::tip + +For more control over tool availability, use +[Customize tools](./customize-tools.mdx) to permanently configure which tools +are enabled for each registry server. The playground tool selection is temporary +and only affects your testing session. + +::: + 4. **Start testing**: Begin chatting with your chosen AI model. The model will have access to all enabled MCP tools and can execute them based on your requests. diff --git a/docs/toolhive/guides-ui/registry.mdx b/docs/toolhive/guides-ui/registry.mdx index eb67404..93ecd79 100644 --- a/docs/toolhive/guides-ui/registry.mdx +++ b/docs/toolhive/guides-ui/registry.mdx @@ -86,6 +86,8 @@ After exploring the registry and finding servers you want to use: - **Install servers**: Click on servers from the registry to install and configure them for your environment +- **Customize tools**: Selectively enable or disable tools from installed + registry servers to create focused tool sets - **Manage running servers**: Use the **MCP Servers** section to start, stop, and monitor your installed servers - **Create custom registries**: Set up your own private registry for diff --git a/docs/toolhive/guides-ui/run-mcp-servers.mdx b/docs/toolhive/guides-ui/run-mcp-servers.mdx index 33610e7..d1d3d4e 100644 --- a/docs/toolhive/guides-ui/run-mcp-servers.mdx +++ b/docs/toolhive/guides-ui/run-mcp-servers.mdx @@ -487,6 +487,8 @@ automatically the next time you launch the application. - Connect ToolHive to AI clients like GitHub Copilot or Cursor using the [client configuration guide](./client-configuration.mdx). +- Customize which tools are available from registry servers using the + [customize tools guide](./customize-tools.mdx). - Learn more about [secrets management](./secrets-management.mdx) to securely manage API tokens and other sensitive data. - Test your MCP servers using the [playground](./playground.mdx) to validate