Skip to main content

Customize tools

ToolHive lets you customize which tools from a running MCP server are available 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?​

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
  • Clarify tool purpose: Edit tool names and descriptions to make them more understandable for your specific use case
Registry match required

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.

Access tool customization​

To customize tools for a running MCP server:

  1. Open the MCP Servers page.
  2. Find the server you want to customize and click the menu (︙) on its card.
  3. 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.

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.
  2. 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
  3. 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.

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.

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.
  2. Click the Edit button next to the tool.
  3. 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.
  4. 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.

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 and optionally edit their names and descriptions.
  2. After clicking Apply, your settings are saved to the server configuration.
  3. The ToolHive proxy intercepts tool discovery requests from AI clients.
  4. Only enabled tools appear in the client's tool list, with your custom names and descriptions if you've set them.
  5. 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 with customized names and descriptions 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.
  2. Disable all tools except those related to pull requests (like create_pull_request, get_pull_request, list_pull_requests).
  3. 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).
  2. Customize tools in each group to match the environment's needs.
  3. 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.
  2. Click Edit on tools with unclear names.
  3. Change the tool name to something more descriptive (for example, rename list_commits_test to List Commits).
  4. Update the description to clarify what the tool does in your context.
  5. Click Save, then Apply.
  6. Your AI clients now see clearer, more intuitive tool names and descriptions.

Reset to defaults​

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.
  2. Clear the Tool and Description fields (leave them empty).
  3. Click Save.
  4. 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.
  2. Manually enable all tools using the toggle switches.
  3. Click Apply to save your changes.