thv proxy

Create a transparent proxy for an MCP server with authentication support

Synopsis

Create a transparent HTTP proxy that forwards requests to an MCP server endpoint.

This command starts a standalone proxy without creating a workload, providing:

Transparent request forwarding to the target MCP server
Optional OAuth/OIDC authentication to remote MCP servers
Automatic authentication detection via WWW-Authenticate headers
OIDC-based access control for incoming proxy requests
Secure credential handling via files or environment variables
Dynamic client registration (RFC 7591) for automatic OAuth client setup

Authentication modes

The proxy supports multiple authentication scenarios:

No Authentication: Simple transparent forwarding
Outgoing Authentication: Authenticate to remote MCP servers using OAuth/OIDC
Incoming Authentication: Protect the proxy endpoint with OIDC validation
Bidirectional: Both incoming and outgoing authentication

OAuth client secret sources

OAuth client secrets can be provided via (in order of precedence):

--remote-auth-client-secret flag (not recommended for production)
--remote-auth-client-secret-file flag (secure file-based approach)
TOOLHIVE_REMOTE_OAUTH_CLIENT_SECRET environment variable

Dynamic client registration

When no client credentials are provided, the proxy automatically registers an OAuth client with the authorization server using RFC 7591 dynamic client registration:

No need to pre-configure client ID and secret
Automatically discovers registration endpoint via OIDC
Supports PKCE flow for enhanced security

Examples

Basic transparent proxy:

thv proxy my-server --target-uri http://localhost:8080

Proxy with OIDC authentication to remote server:

thv proxy my-server --target-uri https://api.example.com \
  --remote-auth --remote-auth-issuer https://auth.example.com \
  --remote-auth-client-id my-client-id \
  --remote-auth-client-secret-file /path/to/secret

Proxy with non-OIDC OAuth authentication to remote server:

thv proxy my-server --target-uri https://api.example.com \
  --remote-auth \
  --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-file /path/to/secret

Proxy with OIDC protection for incoming requests:

thv proxy my-server --target-uri http://localhost:8080 \
  --oidc-issuer https://auth.example.com \
  --oidc-audience my-audience

Auto-detect authentication requirements:

thv proxy my-server --target-uri https://protected-api.com \
  --remote-auth-client-id my-client-id

Dynamic client registration (automatic OAuth client setup):

thv proxy my-server --target-uri https://protected-api.com \
  --remote-auth --remote-auth-issuer https://auth.example.com

thv proxy [flags] SERVER_NAME

Options

  -h, --help                                    help for proxy
      --host string                             Host for the HTTP proxy to listen on (IP or hostname) (default "127.0.0.1")
      --oidc-audience string                    Expected audience for the token
      --oidc-client-id string                   OIDC client ID
      --oidc-client-secret string               OIDC client secret (optional, for introspection)
      --oidc-introspection-url string           URL for token introspection endpoint
      --oidc-issuer string                      OIDC issuer URL (e.g., https://accounts.google.com)
      --oidc-jwks-url string                    URL to fetch the JWKS from
      --port int                                Port for the HTTP proxy to listen on (host port)
      --remote-auth                             Enable OAuth/OIDC authentication to remote MCP server
      --remote-auth-authorize-url string        OAuth authorization endpoint URL (alternative to --remote-auth-issuer for non-OIDC OAuth)
      --remote-auth-callback-port int           Port for OAuth callback server during remote authentication (default 8666)
      --remote-auth-client-id string            OAuth client ID for remote server authentication
      --remote-auth-client-secret string        OAuth client secret for remote server authentication (optional for PKCE)
      --remote-auth-client-secret-file string   Path to file containing OAuth client secret (alternative to --remote-auth-client-secret)
      --remote-auth-issuer string               OAuth/OIDC issuer URL for remote server authentication (e.g., https://accounts.google.com)
      --remote-auth-scopes strings              OAuth scopes to request for remote server authentication (defaults: OIDC uses 'openid,profile,email')
      --remote-auth-skip-browser                Skip opening browser for remote server OAuth flow
      --remote-auth-timeout duration            Timeout for OAuth authentication flow (e.g., 30s, 1m, 2m30s) (default 30s)
      --remote-auth-token-url string            OAuth token endpoint URL (alternative to --remote-auth-issuer for non-OIDC OAuth)
      --resource-url string                     Explicit resource URL for OAuth discovery endpoint (RFC 9728)
      --target-uri string                       URI for the target MCP server (e.g., http://localhost:8080) (required)

Options inherited from parent commands

      --debug   Enable debug mode

thv proxy​

Synopsis​

Authentication modes​

OAuth client secret sources​

Dynamic client registration​

Examples​

Options​

Options inherited from parent commands​

SEE ALSO​