From 96306a76e6e0130b44d477c0652a0ab8a52a0fd0 Mon Sep 17 00:00:00 2001 From: amirejaz Date: Tue, 16 Sep 2025 11:58:43 +0100 Subject: [PATCH 01/10] ci: adds the remote mcp server section --- .../toolhive/guides-cli/manage-mcp-servers.md | 26 ++- docs/toolhive/guides-cli/run-mcp-servers.mdx | 220 +++++++++++++++++- 2 files changed, 239 insertions(+), 7 deletions(-) diff --git a/docs/toolhive/guides-cli/manage-mcp-servers.md b/docs/toolhive/guides-cli/manage-mcp-servers.md index d0aab926..5229b3d8 100644 --- a/docs/toolhive/guides-cli/manage-mcp-servers.md +++ b/docs/toolhive/guides-cli/manage-mcp-servers.md @@ -17,7 +17,8 @@ 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 will show their target URL in url, and remote in package and tool type columns making it easy to identify them. To include stopped servers in the list: @@ -60,7 +61,8 @@ 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 +80,11 @@ 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 +101,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 +118,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..0e4f0d7a 100644 --- a/docs/toolhive/guides-cli/run-mcp-servers.mdx +++ b/docs/toolhive/guides-cli/run-mcp-servers.mdx @@ -17,17 +17,34 @@ 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 + +For remote MCP servers in the registry, such as the Neon or Stripe servers: + +```bash +thv run neon +thv run stripe +``` + :::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. 2. Starts an HTTP proxy process on a random port to forward client requests to @@ -38,10 +55,18 @@ When you run an MCP server from the registry, ToolHive: toolhive-name: ``` +**For remote MCP servers:** +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 conatainer 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 +563,139 @@ 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 --name my-remote-server +``` + +:::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 conatainer 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. + +#### OAuth/OIDC authentication + +For servers requiring OAuth or OIDC authentication, you can provide the issuer URL: + +```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 +``` + +#### Dynamic client registration + +When no client credentials are provided, ToolHive automatically registers an OAuth client +with the authorization server using RFC 7591 dynamic client registration: + +```bash +thv run https://api.example.com/mcp --name my-server +``` + +This eliminates the need to pre-configure client ID and secret, making it easier to +connect to remote MCP servers. + +#### 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. + +#### Custom OAuth endpoints + +For non-OIDC OAuth servers, you can specify custom authorization and token endpoints: + +```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 +``` + +### 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 +815,57 @@ 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: + + ```bash + thv logs + ``` + +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 + ``` + +
From ba2d2818611d3b14071e1a9eede6c8801bea887b Mon Sep 17 00:00:00 2001 From: amirejaz Date: Tue, 16 Sep 2025 13:09:58 +0100 Subject: [PATCH 02/10] added naming convention and default transport --- docs/toolhive/guides-cli/run-mcp-servers.mdx | 30 ++++++++++++++++---- 1 file changed, 25 insertions(+), 5 deletions(-) diff --git a/docs/toolhive/guides-cli/run-mcp-servers.mdx b/docs/toolhive/guides-cli/run-mcp-servers.mdx index 0e4f0d7a..1ed17e37 100644 --- a/docs/toolhive/guides-cli/run-mcp-servers.mdx +++ b/docs/toolhive/guides-cli/run-mcp-servers.mdx @@ -32,13 +32,32 @@ thv run fetch ### Remote MCP servers -For remote MCP servers in the registry, such as the Neon or Stripe 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. By default, remote servers use the `streamable-http` transport. If the server uses Server-Sent Events (SSE), specify the transport flag: + +```bash +thv run --transport sse +``` + +:::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: +- `github-remote` indicates this is the remote version of a server that also has a local `github` version +- `neon` and `stripe` don't have local counterparts, so they don't use the `-remote` suffix + +To run a remote github mcp server, you should use the `github-remote` name. + +```bash +thv run github-remote +``` +::: + :::info[What's happening?] When you run an MCP server from the registry, ToolHive handles different server @@ -56,11 +75,12 @@ types automatically: ``` **For remote MCP servers:** -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 +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. -4. Manages the server like any other ToolHive workload. No conatainer is created for remote MCP servers. +5. Manages the server like any other ToolHive workload. No container is created for remote MCP servers. ::: From 440eba5c6c019c0cfbf843876c139cf228bebcba Mon Sep 17 00:00:00 2001 From: amirejaz Date: Tue, 16 Sep 2025 13:45:43 +0100 Subject: [PATCH 03/10] fixed authentication section --- .../toolhive/guides-cli/manage-mcp-servers.md | 2 +- docs/toolhive/guides-cli/run-mcp-servers.mdx | 52 ++++++++----------- 2 files changed, 23 insertions(+), 31 deletions(-) diff --git a/docs/toolhive/guides-cli/manage-mcp-servers.md b/docs/toolhive/guides-cli/manage-mcp-servers.md index 5229b3d8..f5ade496 100644 --- a/docs/toolhive/guides-cli/manage-mcp-servers.md +++ b/docs/toolhive/guides-cli/manage-mcp-servers.md @@ -18,7 +18,7 @@ thv list ``` This shows the server name, package, status, url, port, tool type, group, and created at. Remote -servers will show their target URL in url, and remote in package and tool type columns making it easy to identify them. +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: diff --git a/docs/toolhive/guides-cli/run-mcp-servers.mdx b/docs/toolhive/guides-cli/run-mcp-servers.mdx index 1ed17e37..f199775c 100644 --- a/docs/toolhive/guides-cli/run-mcp-servers.mdx +++ b/docs/toolhive/guides-cli/run-mcp-servers.mdx @@ -39,11 +39,7 @@ 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. By default, remote servers use the `streamable-http` transport. If the server uses Server-Sent Events (SSE), specify the transport flag: - -```bash -thv run --transport sse -``` +When you run a remote server from the registry, ToolHive uses the pre-configured remote URL and authentication settings. :::note[Naming convention] @@ -601,7 +597,15 @@ thv run [--name ] For example: ```bash -thv run https://api.example.com/mcp --name my-remote-server +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?] @@ -612,7 +616,7 @@ When you run a remote MCP server, ToolHive: 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 conatainer is created for remote MCP servers. +4. Manages the server like any other ToolHive workload. No container is created for remote MCP servers. ::: @@ -630,11 +634,11 @@ examining the server's response headers and status codes: thv run https://protected-api.com/mcp --name my-server ``` -If authentication is required, ToolHive will prompt you to complete the OAuth flow. +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. -#### OAuth/OIDC authentication +#### OIDC authentication -For servers requiring OAuth or OIDC authentication, you can provide the issuer URL: +For servers using OpenID Connect (OIDC), you can provide the issuer URL: ```bash thv run https://api.example.com/mcp \ @@ -643,18 +647,19 @@ thv run https://api.example.com/mcp \ --remote-auth-client-id my-client-id ``` -#### Dynamic client registration +#### OAuth2 authentication -When no client credentials are provided, ToolHive automatically registers an OAuth client -with the authorization server using RFC 7591 dynamic client registration: +For servers using OAuth2, you can specify the authorization and token URLs manually: ```bash -thv run https://api.example.com/mcp --name my-server +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 ``` -This eliminates the need to pre-configure client ID and secret, making it easier to -connect to remote MCP servers. - #### Automatic token refresh ToolHive automatically handles OAuth token refresh for remote MCP servers. When you @@ -662,19 +667,6 @@ authenticate with a remote server, ToolHive stores both the access token and ref token securely. The refresh token is used to automatically obtain new access tokens when they expire, ensuring uninterrupted service without requiring manual re-authentication. -#### Custom OAuth endpoints - -For non-OIDC OAuth servers, you can specify custom authorization and token endpoints: - -```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 -``` - ### Advanced remote server configuration #### OAuth scopes and parameters From c61cb1bd6a2e3307289cf99f557bd00e1e14fa9e Mon Sep 17 00:00:00 2001 From: amirejaz Date: Tue, 16 Sep 2025 13:52:25 +0100 Subject: [PATCH 04/10] fix linting issue --- docs/toolhive/guides-cli/manage-mcp-servers.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/toolhive/guides-cli/manage-mcp-servers.md b/docs/toolhive/guides-cli/manage-mcp-servers.md index f5ade496..9460ad41 100644 --- a/docs/toolhive/guides-cli/manage-mcp-servers.md +++ b/docs/toolhive/guides-cli/manage-mcp-servers.md @@ -17,8 +17,10 @@ To see all currently running MCP servers: thv list ``` -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. +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: @@ -81,6 +83,7 @@ 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) From ea80d6bb141f4ad3b19b353689703d86be383c7d Mon Sep 17 00:00:00 2001 From: amirejaz Date: Tue, 16 Sep 2025 14:02:17 +0100 Subject: [PATCH 05/10] run prettier --- .../toolhive/guides-cli/manage-mcp-servers.md | 21 +++---- docs/toolhive/guides-cli/run-mcp-servers.mdx | 59 +++++++++++++------ 2 files changed, 51 insertions(+), 29 deletions(-) diff --git a/docs/toolhive/guides-cli/manage-mcp-servers.md b/docs/toolhive/guides-cli/manage-mcp-servers.md index 9460ad41..de6aca10 100644 --- a/docs/toolhive/guides-cli/manage-mcp-servers.md +++ b/docs/toolhive/guides-cli/manage-mcp-servers.md @@ -17,10 +17,10 @@ To see all currently running MCP servers: thv list ``` -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. +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: @@ -64,7 +64,8 @@ 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. For -remote servers, this terminates the proxy process but preserves the configuration. +remote servers, this terminates the proxy process but preserves the +configuration. Add the `--group` flag to stop all servers in a specific group: @@ -104,8 +105,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. For remote servers, this removes the proxy process, configuration, -and stored authentication tokens. +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: @@ -123,9 +124,9 @@ 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: +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 diff --git a/docs/toolhive/guides-cli/run-mcp-servers.mdx b/docs/toolhive/guides-cli/run-mcp-servers.mdx index f199775c..67228a2d 100644 --- a/docs/toolhive/guides-cli/run-mcp-servers.mdx +++ b/docs/toolhive/guides-cli/run-mcp-servers.mdx @@ -32,26 +32,35 @@ 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: +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. +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: -- `github-remote` indicates this is the remote version of a server that also has a local `github` version -- `neon` and `stripe` don't have local counterparts, so they don't use the `-remote` suffix +Remote MCP servers use the `-remote` suffix **when they have a local +containerized counterpart** to distinguish between the two versions. For +example: + +- `github-remote` indicates this is the remote version of a server that also has + a local `github` version +- `neon` and `stripe` don't have local counterparts, so they don't use the + `-remote` suffix To run a remote github mcp server, you should use the `github-remote` name. ```bash thv run github-remote ``` + ::: :::info[What's happening?] @@ -60,6 +69,7 @@ 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. 2. Starts an HTTP proxy process on a random port to forward client requests to @@ -71,12 +81,14 @@ types automatically: ``` **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. +5. Manages the server like any other ToolHive workload. No container is created + for remote MCP servers. ::: @@ -581,10 +593,10 @@ 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. +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 @@ -600,9 +612,12 @@ For example: 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`). +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: +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 @@ -616,7 +631,8 @@ When you run a remote MCP server, ToolHive: 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. +4. Manages the server like any other ToolHive workload. No container is created + for remote MCP servers. ::: @@ -634,7 +650,10 @@ examining the server's response headers and status codes: 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. +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 @@ -649,7 +668,8 @@ thv run https://api.example.com/mcp \ #### OAuth2 authentication -For servers using OAuth2, you can specify the authorization and token URLs manually: +For servers using OAuth2, you can specify the authorization and token URLs +manually: ```bash thv run https://api.example.com/mcp \ @@ -662,10 +682,11 @@ thv run https://api.example.com/mcp \ #### 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. +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 From 8a3ec586ad5282202e329e4b28c8098f97d2d2cd Mon Sep 17 00:00:00 2001 From: amirejaz Date: Tue, 16 Sep 2025 14:07:51 +0100 Subject: [PATCH 06/10] used horizontal dots --- docs/toolhive/guides-cli/run-mcp-servers.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/toolhive/guides-cli/run-mcp-servers.mdx b/docs/toolhive/guides-cli/run-mcp-servers.mdx index 67228a2d..558e1698 100644 --- a/docs/toolhive/guides-cli/run-mcp-servers.mdx +++ b/docs/toolhive/guides-cli/run-mcp-servers.mdx @@ -696,7 +696,7 @@ Specify custom OAuth scopes for the authentication flow: ```bash thv run https://api.example.com/mcp \ - ⋮ \ + ... \ --remote-auth-scopes read,write,admin ``` @@ -706,7 +706,7 @@ Adjust the authentication timeout for slow networks: ```bash thv run https://api.example.com/mcp \ - ⋮ \ + ... \ --remote-auth-timeout 2m ``` @@ -716,7 +716,7 @@ For headless environments, skip the browser-based OAuth flow: ```bash thv run https://api.example.com/mcp \ - ⋮ \ + ... \ --remote-auth-skip-browser ``` From 7f124636b3b9e732a2e6835cdada03b4e883a0bd Mon Sep 17 00:00:00 2001 From: amirejaz Date: Tue, 16 Sep 2025 15:02:52 +0100 Subject: [PATCH 07/10] changed remote server example --- docs/toolhive/guides-cli/run-mcp-servers.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/toolhive/guides-cli/run-mcp-servers.mdx b/docs/toolhive/guides-cli/run-mcp-servers.mdx index 558e1698..c2979834 100644 --- a/docs/toolhive/guides-cli/run-mcp-servers.mdx +++ b/docs/toolhive/guides-cli/run-mcp-servers.mdx @@ -50,15 +50,15 @@ Remote MCP servers use the `-remote` suffix **when they have a local containerized counterpart** to distinguish between the two versions. For example: -- `github-remote` indicates this is the remote version of a server that also has - a local `github` version +- `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 github mcp server, you should use the `github-remote` name. +To run a remote notion mcp server, you should use the `notion-remote` name. ```bash -thv run github-remote +thv run notion-remote ``` ::: From 7db5228e8e0b5b814428d1bf7b9ebe07f37a9cf6 Mon Sep 17 00:00:00 2001 From: amirejaz Date: Tue, 16 Sep 2025 15:29:35 +0100 Subject: [PATCH 08/10] added client secret param --- docs/toolhive/guides-cli/run-mcp-servers.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/toolhive/guides-cli/run-mcp-servers.mdx b/docs/toolhive/guides-cli/run-mcp-servers.mdx index c2979834..5485a642 100644 --- a/docs/toolhive/guides-cli/run-mcp-servers.mdx +++ b/docs/toolhive/guides-cli/run-mcp-servers.mdx @@ -664,6 +664,7 @@ 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 From 7b906666ec06c30b58ddb934bc8cc01e182024e5 Mon Sep 17 00:00:00 2001 From: amirejaz Date: Tue, 16 Sep 2025 17:34:50 +0100 Subject: [PATCH 09/10] improve the language and logging guide --- .../toolhive/guides-cli/manage-mcp-servers.md | 11 ++++++++--- docs/toolhive/guides-cli/run-mcp-servers.mdx | 19 +++++++++---------- 2 files changed, 17 insertions(+), 13 deletions(-) diff --git a/docs/toolhive/guides-cli/manage-mcp-servers.md b/docs/toolhive/guides-cli/manage-mcp-servers.md index de6aca10..f694493a 100644 --- a/docs/toolhive/guides-cli/manage-mcp-servers.md +++ b/docs/toolhive/guides-cli/manage-mcp-servers.md @@ -30,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. @@ -39,8 +41,11 @@ updates in real time. thv logs [--follow] ``` -Logs are stored in the ToolHive application directory. The path depends on your -platform: +#### 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` - **Linux**: `~/.local/share/toolhive/logs/.log` diff --git a/docs/toolhive/guides-cli/run-mcp-servers.mdx b/docs/toolhive/guides-cli/run-mcp-servers.mdx index 5485a642..82e63646 100644 --- a/docs/toolhive/guides-cli/run-mcp-servers.mdx +++ b/docs/toolhive/guides-cli/run-mcp-servers.mdx @@ -33,7 +33,7 @@ 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 +ToolHive's transparent HTTP proxy to forward requests to remote servers. For example: ```bash @@ -61,6 +61,8 @@ To run a remote notion mcp server, you should use the `notion-remote` name. thv run notion-remote ``` +Use `thv search ` or `thv registry list` to discover available servers. + ::: :::info[What's happening?] @@ -657,20 +659,21 @@ registration, eliminating the need to pre-configure client ID and secret. #### OIDC authentication -For servers using OpenID Connect (OIDC), you can provide the issuer URL: +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-id my-client-id \ --remote-auth-client-secret my-client-secret ``` #### OAuth2 authentication -For servers using OAuth2, you can specify the authorization and token URLs -manually: +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 \ @@ -855,11 +858,7 @@ If a server crashes or exits unexpectedly: If a remote MCP server authentication fails: -1. Check the server logs for authentication errors: - - ```bash - thv logs - ``` +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 From 0a96038504713661e958be55d21adff8243293f6 Mon Sep 17 00:00:00 2001 From: amirejaz Date: Tue, 16 Sep 2025 17:36:59 +0100 Subject: [PATCH 10/10] run prettier --- docs/toolhive/guides-cli/manage-mcp-servers.md | 3 ++- docs/toolhive/guides-cli/run-mcp-servers.mdx | 4 +++- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/toolhive/guides-cli/manage-mcp-servers.md b/docs/toolhive/guides-cli/manage-mcp-servers.md index f694493a..2237d3a8 100644 --- a/docs/toolhive/guides-cli/manage-mcp-servers.md +++ b/docs/toolhive/guides-cli/manage-mcp-servers.md @@ -45,7 +45,8 @@ thv logs [--follow] 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: +directly in the ToolHive application directory. The path depends on your +platform: - **macOS**: `~/Library/Application Support/toolhive/logs/.log` - **Linux**: `~/.local/share/toolhive/logs/.log` diff --git a/docs/toolhive/guides-cli/run-mcp-servers.mdx b/docs/toolhive/guides-cli/run-mcp-servers.mdx index 82e63646..7d81af9a 100644 --- a/docs/toolhive/guides-cli/run-mcp-servers.mdx +++ b/docs/toolhive/guides-cli/run-mcp-servers.mdx @@ -858,7 +858,9 @@ If a server crashes or exits unexpectedly: 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) +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