diff --git a/docs/toolhive/guides-cli/client-configuration.mdx b/docs/toolhive/guides-cli/client-configuration.mdx index 63ce406a..a333496d 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,29 +222,29 @@ 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.
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. +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.
diff --git a/docs/toolhive/guides-cli/run-mcp-servers.mdx b/docs/toolhive/guides-cli/run-mcp-servers.mdx index efb910c0..8440500b 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 @@ -935,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 new file mode 100644 index 00000000..37b70a69 --- /dev/null +++ b/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 +``` + +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`. + +::: + +## 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) 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', {