Add MCP testing guide for CLI

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 <MCP_SERVER_URL>
-   ```
-
-4. Restart your client application.
+3. Restart your client application.
 
 </details>
 
@@ -214,40 +210,41 @@ If your client connects to the MCP server but tools aren't available:
 
    ```bash
    thv list
-
-   curl <MCP_SERVER_URL>
    ```
 
+   See [Test MCP servers](./test-mcp-servers.mdx) for help testing the MCP
+   server's functionality.
+
 2. Check the MCP server logs:
 
    ```bash
    thv logs <SERVER_NAME>
    ```
 
 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.
 
 </details>
 
 <details>
 <summary>Containerized client can't connect to MCP server</summary>
 
-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.
+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:
 
-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.
+- **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)
 
-Refer to your containerization platform's documentation for details on how to
-configure network access between containers and the host.
+For example, change the MCP server URL from `http://localhost:8080/mcp` to
+`http://host.docker.internal:8080/mcp` in your client configuration.
 
 </details>
 

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
 
@@ -935,3 +938,21 @@ If you can't connect to a remote MCP server:
    ```
 
 </details>
+
+<details>
+<summary>MCP server can't connect to services on the same host</summary>
+
+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`.
+
+</details>

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

@@ -0,0 +1,95 @@
+---
+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 <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:
+
+```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=<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](../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 <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](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`.
+
+:::
+
+## 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)
+- [`thv mcp list` command reference](../reference/cli/thv_mcp_list.md)

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',
         {