Skip to main content

Test MCP servers

ToolHive includes several commands to help you test and validate MCP servers. These commands ensure that your servers are functioning correctly. This is useful for:

  • Validating new MCP server installations
  • Troubleshooting existing MCP servers
  • Testing custom MCP servers during development

MCP Inspector​

The MCP Inspector is an interactive tool for testing and debugging MCP servers.

You can quickly launch the MCP Inspector and connect it to an MCP server running with ToolHive using the thv inspector command:

thv inspector <SERVER_NAME>

ToolHive downloads and runs the official Inspector container image and outputs the URL to open it in your web browser with the target MCP server's details pre-populated.

Example:

thv run fetch
thv inspector fetch

The output will look like this:

2:52PM	INFO	Pulling image: ghcr.io/modelcontextprotocol/inspector:0.17.0
2:52PM	INFO	Pull complete for image: ghcr.io/modelcontextprotocol/inspector:0.17.0
2:52PM	INFO	Waiting for MCP Inspector to be ready...
2:52PM	INFO	Connected to MCP server: fetch
2:52PM	INFO	Inspector UI is now available at http://localhost:6274?transport=streamable-http&serverUrl=http://host.docker.internal:21309/mcp&MCP_PROXY_AUTH_TOKEN=<RANDOM_TOKEN>

Open the provided URL in your web browser to access the MCP Inspector UI, where you can interactively test the MCP server's tools, prompts, and resources.

thv mcp commands​

ToolHive also includes several thv mcp commands to test and validate MCP servers. You can list the MCP server's tools, prompts, and resources:

thv mcp list tools --server <SERVER_NAME_OR_URL>
thv mcp list prompts --server <SERVER_NAME_OR_URL>
thv mcp list resources --server <SERVER_NAME_OR_URL>

Replace <SERVER_NAME_OR_URL> with either the MCP server name or its ToolHive proxy URL. You can find both values in the output of thv list.

Add the --format json flag to get the output in JSON format.

note

Currently, the thv mcp commands only support using server names for local MCP servers. For remote servers, you must use the full URL instead of the server name. You can track this issue on GitHub.

To use URLs instead of names, get the server URL from thv list and use it directly, like thv mcp list tools --server http://localhost:12345/mcp.

ToolHive playground​

While the MCP Inspector and thv mcp commands are great for basic functional testing and validating spec compliance, you may want to experiment with MCP servers in a more interactive way. It's also important to see how MCP servers perform in real-world scenarios with actual AI models.

The playground in the ToolHive UI lets you test different tools interactively and see how your MCP server responds to various prompts.

See Test MCP servers in the ToolHive UI to learn about the playground's features and how to get started.