ci: adds the remote mcp server section

Author: amirejaz

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 <SERVER_NAME>
 ```
 
 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 <SERVER_NAME>
 ```
 
+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 <SERVER_NAME>
 
 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 <REMOTE_SERVER_NAME>
+```
+
+This will always prompt for re-authentication, even if valid tokens exist.
+
 ## Related information
 
 - [`thv list` command reference](../reference/cli/thv_list.md)

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 <SERVER_NAME>
 ```
 
-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: <SERVER_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 <URL> [--name <SERVER_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 <SERVER_NAME>` shows proxy and authentication logs
+- **Stop/restart**: `thv stop <SERVER_NAME>` and `thv restart <SERVER_NAME>`
+- **Remove**: `thv rm <SERVER_NAME>` 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
 
 </details>
+
+<details>
+<summary>Remote server authentication fails</summary>
+
+If a remote MCP server authentication fails:
+
+1. Check the server logs for authentication errors:
+
+   ```bash
+   thv logs <SERVER_NAME>
+   ```
+
+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 <SERVER_NAME>
+   ```
+
+</details>
+
+<details>
+<summary>Remote server connection issues</summary>
+
+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 <SERVER_NAME>
+   ```
+
+5. Try running with debug mode for more detailed logs:
+
+   ```bash
+   thv run --debug https://api.example.com/mcp --name my-server
+   ```
+
+</details>