From 00287cdac9943d64f89cb9a35117f4b44ead7e91 Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Fri, 17 Oct 2025 15:08:04 -0400 Subject: [PATCH 1/3] Add MCP testing guide for CLI Signed-off-by: Dan Barr <6922515+danbarr@users.noreply.github.com> --- .../guides-cli/client-configuration.mdx | 25 +++--- docs/toolhive/guides-cli/run-mcp-servers.mdx | 7 +- docs/toolhive/guides-cli/test-mcp-servers.mdx | 82 +++++++++++++++++++ sidebars.ts | 1 + 4 files changed, 98 insertions(+), 17 deletions(-) create mode 100644 docs/toolhive/guides-cli/test-mcp-servers.mdx diff --git a/docs/toolhive/guides-cli/client-configuration.mdx b/docs/toolhive/guides-cli/client-configuration.mdx index 63ce406a..625afcf9 100644 --- a/docs/toolhive/guides-cli/client-configuration.mdx +++ b/docs/toolhive/guides-cli/client-configuration.mdx @@ -188,20 +188,16 @@ If your client can't connect to the MCP server: thv list ``` + See [Test MCP servers](./test-mcp-servers.mdx) for help testing the MCP + server's availability. + 2. Check if the client is registered: ```bash thv client status ``` -3. Make sure the URL is correct and accessible. Use `curl` to test the - connection: - - ```bash - curl - ``` - -4. Restart your client application. +3. Restart your client application. @@ -214,10 +210,11 @@ If your client connects to the MCP server but tools aren't available: ```bash thv list - - curl ``` + See [Test MCP servers](./test-mcp-servers.mdx) for help testing the MCP + server's functionality. + 2. Check the MCP server logs: ```bash @@ -225,11 +222,9 @@ If your client connects to the MCP server but tools aren't available: ``` 3. Make sure you properly configured the MCP server in your client. -4. For Visual Studio Code, make sure you started the MCP server in the settings - (see the VS Code with Copilot section in the - [Client compatibility reference](../reference/client-compatibility.mdx#vs-code-with-copilot)). -5. If you've implemented authentication for your MCP server, make sure the - client has the necessary permissions to access the tools. +4. If the MCP server requires authentication or has authorization policies + applied, make sure the client has the necessary permissions to access the + tools. diff --git a/docs/toolhive/guides-cli/run-mcp-servers.mdx b/docs/toolhive/guides-cli/run-mcp-servers.mdx index efb910c0..1f1f5026 100644 --- a/docs/toolhive/guides-cli/run-mcp-servers.mdx +++ b/docs/toolhive/guides-cli/run-mcp-servers.mdx @@ -820,14 +820,17 @@ The configuration file must contain all server settings. See [Monitor and manage MCP servers](./manage-mcp-servers.mdx) to monitor and control your servers. +[Test your MCP server](./test-mcp-servers.mdx) using the MCP Inspector or +`thv mcp` commands. + ## Related information - [`thv run` command reference](../reference/cli/thv_run.md) - [Client configuration](./client-configuration.mdx) - [Secrets management](./secrets-management.mdx) - [Custom permissions](./custom-permissions.mdx) -- [File system access](./filesystem-access.mdx) -- [Network isolation](./network-isolation.mdx) + - [File system access](./filesystem-access.mdx) + - [Network isolation](./network-isolation.mdx) ## Troubleshooting diff --git a/docs/toolhive/guides-cli/test-mcp-servers.mdx b/docs/toolhive/guides-cli/test-mcp-servers.mdx new file mode 100644 index 00000000..d0f333b1 --- /dev/null +++ b/docs/toolhive/guides-cli/test-mcp-servers.mdx @@ -0,0 +1,82 @@ +--- +title: Test MCP servers +description: Learn how to test and validate MCP servers using the Toolhive CLI. +--- + +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](https://modelcontextprotocol.io/docs/tools/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: + +```bash +thv inspector +``` + +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: + +```bash +thv run fetch +thv inspector fetch +``` + +The output will look like this: + +```text +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= +``` + +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](../reference/cli/thv_mcp_list.md) to test and validate MCP +servers. You can list the MCP server's tools, prompts, and resources: + +```bash +thv mcp list tools --server +thv mcp list prompts --server +thv mcp list resources --server +``` + +Replace `` 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](https://github.com/stacklok/toolhive/issues/2035). + +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`. + +::: + +## Related information + +- [`thv inspector` command reference](../reference/cli/thv_inspector.md) +- [`thv mcp list` command reference](../reference/cli/thv_mcp_list.md) diff --git a/sidebars.ts b/sidebars.ts index 7cd3c87b..7c334a1b 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -114,6 +114,7 @@ const sidebars: SidebarsConfig = { ], }, 'toolhive/guides-cli/telemetry-and-metrics', + 'toolhive/guides-cli/test-mcp-servers', 'toolhive/guides-cli/build-containers', 'toolhive/guides-cli/advanced-cicd', { From 8f278eb310106b036068d3302fb09463a8945e69 Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Fri, 17 Oct 2025 15:31:00 -0400 Subject: [PATCH 2/3] Clarify localhost networking troubleshooting Signed-off-by: Dan Barr <6922515+danbarr@users.noreply.github.com> --- .../guides-cli/client-configuration.mdx | 26 ++++++++++--------- docs/toolhive/guides-cli/run-mcp-servers.mdx | 18 +++++++++++++ docs/toolhive/guides-cli/test-mcp-servers.mdx | 13 ++++++++++ 3 files changed, 45 insertions(+), 12 deletions(-) diff --git a/docs/toolhive/guides-cli/client-configuration.mdx b/docs/toolhive/guides-cli/client-configuration.mdx index 625afcf9..a333496d 100644 --- a/docs/toolhive/guides-cli/client-configuration.mdx +++ b/docs/toolhive/guides-cli/client-configuration.mdx @@ -231,18 +231,20 @@ If your client connects to the MCP server but tools aren't available:
Containerized client can't connect to MCP server -If you're running an MCP client inside a container and it can't connect to an -MCP server running on the same host, make sure you use the correct host address. -The ToolHive proxy is a standard OS process, so it listens on the host's network -interface. - -For example, on Docker Desktop, use `host.docker.internal` instead of -`localhost`. On Linux Docker environments, you may need to use the host's IP -address or configure the container's network to use `host` mode for proper -connectivity. - -Refer to your containerization platform's documentation for details on how to -configure network access between containers and the host. +When your MCP client runs in a container (like containerized LibreChat), it +can't reach the ToolHive proxy on your host machine using `localhost` due to +container network isolation. The ToolHive proxy runs as an OS process on the +host and provides access to containerized MCP servers. + +Configure your containerized client to use the appropriate host address for your +platform: + +- **Docker Desktop (macOS/Windows)**: `host.docker.internal` +- **Podman Desktop**: `host.containers.internal` +- **Docker Engine (Linux)**: `172.17.0.1` (or your custom bridge gateway IP) + +For example, change the MCP server URL from `http://localhost:8080/mcp` to +`http://host.docker.internal:8080/mcp` in your client configuration.
diff --git a/docs/toolhive/guides-cli/run-mcp-servers.mdx b/docs/toolhive/guides-cli/run-mcp-servers.mdx index 1f1f5026..8440500b 100644 --- a/docs/toolhive/guides-cli/run-mcp-servers.mdx +++ b/docs/toolhive/guides-cli/run-mcp-servers.mdx @@ -938,3 +938,21 @@ If you can't connect to a remote MCP server: ``` + +
+MCP server can't connect to services on the same host + +When ToolHive runs MCP servers in containers, they can't reach services on your +host machine using `localhost` due to container network isolation. + +Replace `localhost` in your MCP server configuration with the appropriate host +address for your platform: + +- **Docker Desktop (macOS/Windows)**: `host.docker.internal` +- **Podman Desktop**: `host.containers.internal` +- **Docker Engine (Linux)**: `172.17.0.1` (or your custom bridge gateway IP) + +For example, change `http://localhost:3000` to +`http://host.docker.internal:3000`. + +
diff --git a/docs/toolhive/guides-cli/test-mcp-servers.mdx b/docs/toolhive/guides-cli/test-mcp-servers.mdx index d0f333b1..fe5c6035 100644 --- a/docs/toolhive/guides-cli/test-mcp-servers.mdx +++ b/docs/toolhive/guides-cli/test-mcp-servers.mdx @@ -76,6 +76,19 @@ 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](../guides-ui/playground.mdx) to learn +about the playground's features and how to get started. + ## Related information - [`thv inspector` command reference](../reference/cli/thv_inspector.md) From 2c99e8be9d6ea1cefd6acf118e1b177523f16102 Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Mon, 20 Oct 2025 15:06:35 -0400 Subject: [PATCH 3/3] Fix typo Signed-off-by: Dan Barr <6922515+danbarr@users.noreply.github.com> --- docs/toolhive/guides-cli/test-mcp-servers.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/toolhive/guides-cli/test-mcp-servers.mdx b/docs/toolhive/guides-cli/test-mcp-servers.mdx index fe5c6035..37b70a69 100644 --- a/docs/toolhive/guides-cli/test-mcp-servers.mdx +++ b/docs/toolhive/guides-cli/test-mcp-servers.mdx @@ -1,6 +1,6 @@ --- title: Test MCP servers -description: Learn how to test and validate MCP servers using the Toolhive CLI. +description: Learn how to test and validate MCP servers using the ToolHive CLI. --- ToolHive includes several commands to help you test and validate MCP servers.