Support Remote MCP Servers with OAuth/OIDC Authentication

Overview

This PR adds support for running remote MCP servers using the thv run --remote command, similar to how local MCP servers are run. Remote MCP servers are treated as workloads managed via runconfigs, enabling full functionality such as client configuration, tool filtering, and import/export.

Key Features

1. Remote Server Support

• Command: thv run --remote <URL of MCP server>
• Transport Types: Uses existing transport types (SSE, streamable-http) - no new "remote" transport type
• Workload Management: Remote servers are managed as workloads via runconfigs
• Status Management: Remote servers appear in thv list command

2. OAuth/OIDC Authentication

• OAuth Flow: --remote-auth-client-id and --remote-auth-client-secret
• Custom OAuth Endpoints: --remote-auth-authorize-url and --remote-auth-token-url
• OIDC Discovery: Automatic discovery of OAuth endpoints via OIDC discovery documents
• Registry Integration: OAuth configuration from registry when running registry-based servers

3. Registry Support

• Remote Server Registry: Support for remote servers in the registry
• OAuth Configuration: Registry can provide OAuth endpoints, scopes, and parameters
• Conflict Resolution: Handles conflicts between local and remote servers with same name

Usage Examples

Basic Remote Server

# Run remote server with default transport
thv run --remote https://api.example.com/mcp/ --name example-server

# Run with specific transport
thv run --remote https://mcp.example.com --name example-server --transport streamable-http

OAuth/OIDC Authentication

# OAuth with client credentials (uses OIDC discovery)
thv run --remote https://api.example.com/mcp/ --name example-server \
  --remote-auth-client-id <client-id> \
  --remote-auth-client-secret <client-secret>

# Custom OAuth endpoints (bypasses OIDC discovery)
thv run --remote https://api.example.com/mcp/ --name example-server \
  --remote-auth-client-id <client-id> \
  --remote-auth-client-secret <client-secret> \
  --remote-auth-authorize-url https://example.com/oauth/authorize \
  --remote-auth-token-url https://example.com/oauth/token

Registry-Based Remote Servers

# Run from registry (uses registry OAuth configuration)
thv run example --name example-registry --remote-auth-client-id <client-id> --remote-auth-client-secret <client-secret>

# Registry provides OAuth endpoints automatically
thv run sample --name sample-registry --remote-auth-client-id <client-id> --remote-auth-client-secret <client-secret>

Server Management

# List all servers (including remote)
thv list

# Remove remote server (removes runconfig only)
thv rm example-server

# Stop remote server
thv stop example-server

Technical Implementation

Authentication Flow

1. OIDC Discovery → Discover OAuth endpoints via .well-known/openid_configuration
2. Provided OAuth Endpoints (user or registry) → Use explicit OAuth endpoints
3. Manual Authentication Detection → Check server for auth requirements
4. Clear Error Message → Guide user to provide OAuth endpoints or use registry

OIDC Discovery

• Discovery Endpoints: .well-known/openid_configuration and .well-known/oauth-authorization-server
• Automatic Endpoint Detection: Discovers authorization_endpoint and token_endpoint
• Fallback Patterns: Common OAuth endpoint patterns if discovery fails

Registry Integration

• Remote Server Metadata: RemoteServerMetadata struct with OAuth configuration
• OAuth Config: Registry can provide authorize_url, token_url, scopes, oauth_params
• Conflict Resolution: Comments out remote servers that conflict with local ones

Client Configuration

• Automatic Setup: Remote servers are automatically added to client configurations
• Proxy URLs: Clients connect to local proxy URLs (e.g., localhost:port)
• Transport Support: Supports SSE and streamable-http transports

Configuration

Registry Schema

Remote servers are defined in pkg/registry/data/registry.json:

{
  "remote_servers": {
    "example": {
      "url": "https://api.example.com/mcp/",
      "transport": "streamable-http",
      "oauth_config": {
        "authorize_url": "https://example.com/oauth/authorize",
        "token_url": "https://example.com/oauth/token",
        "scopes": ["openid", "profile", "email"],
        "callback_port": 8666
      }
    }
  }
}

RunConfig Structure

type RemoteAuthConfig struct {
    EnableRemoteAuth bool
    ClientID         string
    ClientSecret     string
    AuthorizeURL     string
    TokenURL         string
    Scopes           []string
    OAuthParams      map[string]string
    CallbackPort     int
    Timeout          time.Duration
}

Limitations

• No Dynamic Client Registration: Will be implemented in a separate PR
• Manual OAuth Configuration: Users must provide OAuth endpoints or use registry
• OIDC Discovery Only: Relies on OIDC discovery or explicit configuration

Next Steps

• Dynamic Client Registration: Will be implemented in a separate PR to support automatic OAuth endpoint discovery and client registration
• thv start, thv restart: Properly handle start and restart for remote mcp servers