diff --git a/docs/toolhive/guides-cli/manage-mcp-servers.md b/docs/toolhive/guides-cli/manage-mcp-servers.md index d0aab926..2237d3a8 100644 --- a/docs/toolhive/guides-cli/manage-mcp-servers.md +++ b/docs/toolhive/guides-cli/manage-mcp-servers.md @@ -17,7 +17,10 @@ To see all currently running MCP servers: thv list ``` -This shows the server name, status, transport method, port, and URL. +This shows the server name, package, status, url, port, tool type, group, and +created at. Remote servers display their target URL in the URL column. The word +'remote' is indicated in both the package and tool type columns, making it easy +to identify remote servers. To include stopped servers in the list: @@ -27,7 +30,9 @@ thv list --all ### View server logs -To view the logs of a running or stopped MCP server, use the +#### Containerized servers + +To view the logs of a running or stopped containerized MCP server, use the [`thv logs`](../reference/cli/thv_logs.md) command. You can optionally follow the logs with the `--follow` option, which shows the most recent log entries and updates in real time. @@ -36,7 +41,11 @@ updates in real time. thv logs [--follow] ``` -Logs are stored in the ToolHive application directory. The path depends on your +#### Remote servers + +The thv logs command only works with local containers. For remote MCP servers, +there’s no container to read logs from, so you’ll need to check the log files +directly in the ToolHive application directory. The path depends on your platform: - **macOS**: `~/Library/Application Support/toolhive/logs/.log` @@ -60,7 +69,9 @@ thv stop ``` This stops the server and the associated proxy process, removes the MCP server's -entry from your configured clients, but keeps the container for future use. +entry from your configured clients, but keeps the container for future use. For +remote servers, this terminates the proxy process but preserves the +configuration. Add the `--group` flag to stop all servers in a specific group: @@ -78,6 +89,12 @@ To restart a stopped MCP server and add it back to your configured clients: thv restart ``` +For remote servers, restarting will: + +1. Recreate the proxy process +2. Re-establish connection to the remote server +3. Re-authenticate with the remote server (triggers new OAuth flow) + Add the `--group` flag to restart all servers in a specific group: ```bash @@ -94,7 +111,8 @@ thv rm This removes the container and cleans up the MCP server's entry in your configured clients. If the server is still running, it will be stopped as part -of the removal. +of the removal. For remote servers, this removes the proxy process, +configuration, and stored authentication tokens. Add the `--group` flag to remove all servers in a specific group: @@ -110,6 +128,18 @@ won't clean up the MCP server's entry in your configured clients. Use ::: +### Remote server authentication + +Remote servers with OAuth authentication will automatically refresh tokens when +they expire during normal operation. However, restarting a remote server always +triggers a new OAuth authentication flow: + +```bash +thv restart +``` + +This will always prompt for re-authentication, even if valid tokens exist. + ## Related information - [`thv list` command reference](../reference/cli/thv_list.md) diff --git a/docs/toolhive/guides-cli/run-mcp-servers.mdx b/docs/toolhive/guides-cli/run-mcp-servers.mdx index 107ab6d9..7d81af9a 100644 --- a/docs/toolhive/guides-cli/run-mcp-servers.mdx +++ b/docs/toolhive/guides-cli/run-mcp-servers.mdx @@ -17,16 +17,60 @@ want to run. The server name is the same as its name in the registry. thv run ``` -For example, to run the `fetch` server, which is a simple MCP server that -fetches website contents: +The ToolHive registry contains both local containerized MCP servers and remote +MCP servers. ToolHive automatically handles the appropriate setup based on the +server type. + +### Local containerized servers + +For example, to run the `fetch` server, which is a local containerized MCP +server that fetches website contents: ```bash thv run fetch ``` +### Remote MCP servers + +Remote MCP servers in the registry don't run as local containers but instead use +ToolHive's transparent HTTP proxy to forward requests to remote servers. For +example: + +```bash +thv run neon +thv run stripe +``` + +When you run a remote server from the registry, ToolHive uses the pre-configured +remote URL and authentication settings. + +:::note[Naming convention] + +Remote MCP servers use the `-remote` suffix **when they have a local +containerized counterpart** to distinguish between the two versions. For +example: + +- `notion-remote` indicates this is the remote version of a server that also has + a local `notion` version +- `neon` and `stripe` don't have local counterparts, so they don't use the + `-remote` suffix + +To run a remote notion mcp server, you should use the `notion-remote` name. + +```bash +thv run notion-remote +``` + +Use `thv search ` or `thv registry list` to discover available servers. + +::: + :::info[What's happening?] -When you run an MCP server from the registry, ToolHive: +When you run an MCP server from the registry, ToolHive handles different server +types automatically: + +**For local containerized servers:** 1. Pulls the image and launches a container using the configuration from the registry. @@ -38,10 +82,21 @@ When you run an MCP server from the registry, ToolHive: toolhive-name: ``` +**For remote MCP servers:** + +1. Uses the pre-configured remote URL from the registry. +2. Automatically detects if the remote server requires authentication. +3. Handles OAuth/OIDC authentication flows if needed. +4. Starts an HTTP proxy process on a random port to forward client requests to + the remote server. +5. Manages the server like any other ToolHive workload. No container is created + for remote MCP servers. + ::: See [Run a custom MCP server](#run-a-custom-mcp-server) to run a server that is -not in the registry. +not in the registry, or [Run a remote MCP server](#run-a-remote-mcp-server) for +more details about remote server configuration. ## Customize server settings @@ -538,6 +593,146 @@ thv run uvx://some-package thv run --ca-cert /path/to/special-ca.crt uvx://other-package ``` +## Run a remote MCP server + +You can run remote MCP servers directly by providing their URL. This allows you +to connect to MCP servers hosted elsewhere without needing to manage containers +locally. ToolHive creates a transparent proxy that handles authentication and +forwards requests to the remote server. + +### Basic remote server setup + +To run a remote MCP server, simply provide its URL: + +```bash +thv run [--name ] +``` + +For example: + +```bash +thv run https://api.example.com/mcp +``` + +If you don't specify a name with `--name`, ToolHive will automatically derive a +name from the URL by extracting the main domain name (e.g., `notion` from +`https://api.notion.com/mcp`). + +By default, remote servers use the `streamable-http` transport. If the server +uses Server-Sent Events (SSE), specify the transport flag: + +```bash +thv run https://api.example.com/sse --transport sse +``` + +:::info[What's happening?] + +When you run a remote MCP server, ToolHive: + +1. Automatically detects if the remote server requires authentication. +2. Handles OAuth/OIDC authentication flows if needed. +3. Starts an HTTP proxy process on a random port to forward client requests to + the remote server. +4. Manages the server like any other ToolHive workload. No container is created + for remote MCP servers. + +::: + +### Authentication setup + +Many remote MCP servers require authentication. ToolHive supports automatic +authentication detection and OAuth/OIDC flows. + +#### Auto-detect authentication + +ToolHive can automatically detect if a remote server requires authentication by +examining the server's response headers and status codes: + +```bash +thv run https://protected-api.com/mcp --name my-server +``` + +If authentication is required, ToolHive will prompt you to complete the OAuth +flow. When no client credentials are provided, ToolHive automatically registers +an OAuth client with the authorization server using RFC 7591 dynamic client +registration, eliminating the need to pre-configure client ID and secret. + +#### OIDC authentication + +For servers using OpenID Connect (OIDC), provide the issuer URL, client ID, and +client secret obtained from the application provider: + +```bash +thv run https://api.example.com/mcp \ + --name my-server \ + --remote-auth-issuer https://auth.example.com \ + --remote-auth-client-id my-client-id \ + --remote-auth-client-secret my-client-secret +``` + +#### OAuth2 authentication + +For servers using OAuth2, specify the authorization and token URLs along with +the client ID and secret obtained from the application provider: + +```bash +thv run https://api.example.com/mcp \ + --name my-server \ + --remote-auth-authorize-url https://auth.example.com/oauth/authorize \ + --remote-auth-token-url https://auth.example.com/oauth/token \ + --remote-auth-client-id my-client-id \ + --remote-auth-client-secret my-client-secret +``` + +#### Automatic token refresh + +ToolHive automatically handles OAuth token refresh for remote MCP servers. When +you authenticate with a remote server, ToolHive stores both the access token and +refresh token securely. The refresh token is used to automatically obtain new +access tokens when they expire, ensuring uninterrupted service without requiring +manual re-authentication. + +### Advanced remote server configuration + +#### OAuth scopes and parameters + +Specify custom OAuth scopes for the authentication flow: + +```bash +thv run https://api.example.com/mcp \ + ... \ + --remote-auth-scopes read,write,admin +``` + +#### Custom authentication timeout + +Adjust the authentication timeout for slow networks: + +```bash +thv run https://api.example.com/mcp \ + ... \ + --remote-auth-timeout 2m +``` + +#### Skip browser authentication + +For headless environments, skip the browser-based OAuth flow: + +```bash +thv run https://api.example.com/mcp \ + ... \ + --remote-auth-skip-browser +``` + +### Remote server management + +Remote MCP servers are managed like any other ToolHive workload: + +- **List servers**: `thv list` shows remote servers with their target URLs +- **View logs**: `thv logs ` shows proxy and authentication logs +- **Stop/restart**: `thv stop ` and `thv restart ` +- **Remove**: `thv rm ` removes the proxy and configuration + ## Share and reuse server configurations ToolHive allows you to export a server's configuration and run servers using @@ -657,3 +852,55 @@ If a server crashes or exits unexpectedly: 4. Verify the server's configuration and arguments + +
+Remote server authentication fails + +If a remote MCP server authentication fails: + +1. Check the server logs for authentication errors (see + [View server logs](./manage-mcp-servers.md#view-server-logs) for the correct + log file path on your platform) + +2. Verify the issuer URL is correct and accessible + +3. Check if the OAuth client ID and secret are valid + +4. Ensure the remote server supports the OAuth flow you're using + +5. Try re-authenticating by restarting the server: + + ```bash + thv restart + ``` + +
+ +
+Remote server connection issues + +If you can't connect to a remote MCP server: + +1. Verify the remote server URL is correct and accessible + +2. Check your network connectivity: + + ```bash + curl -I https://api.example.com/mcp + ``` + +3. Check if the remote server requires specific headers or authentication + +4. Review the server logs for connection errors: + + ```bash + thv logs + ``` + +5. Try running with debug mode for more detailed logs: + + ```bash + thv run --debug https://api.example.com/mcp --name my-server + ``` + +