Skip to content

thv_proxy.md

Latest commit

 

History

History
150 lines (114 loc) · 8.02 KB

thv_proxy.md

File metadata and controls

150 lines (114 loc) · 8.02 KB
title thv proxy
hide_title true
description Reference for ToolHive CLI command `thv proxy`
last_update
author
autogenerated
slug thv_proxy
mdx
format
md

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:

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

OAuth client secret sources

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

  1. --remote-auth-client-secret flag (not recommended for production)
  2. --remote-auth-client-secret-file flag (secure file-based approach)
  3. 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
      --oidc-scopes strings                         OAuth scopes to advertise in the well-known endpoint (RFC 9728, defaults to 'openid' if not specified)
      --port int                                    Port for the HTTP proxy to listen on (host port)
      --remote-auth                                 Enable OAuth/OIDC authentication to remote MCP server (default false)
      --remote-auth-authorize-url string            OAuth authorization endpoint URL (alternative to --remote-auth-issuer for non-OIDC OAuth)
      --remote-auth-bearer-token string             Bearer token for remote server authentication (alternative to OAuth)
      --remote-auth-bearer-token-file string        Path to file containing bearer token (alternative to --remote-auth-bearer-token)
      --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 (optional if the authorization server supports dynamic client registration (RFC 7591))
      --remote-auth-client-secret string            OAuth client secret for remote server authentication (optional if the authorization server supports dynamic client registration (RFC 7591) or if using PKCE)
      --remote-auth-client-secret-file string       Path to file containing OAuth client secret (alternative to --remote-auth-client-secret) (optional if the authorization server supports dynamic client registration (RFC 7591) or if using PKCE)
      --remote-auth-issuer string                   OAuth/OIDC issuer URL for remote server authentication (e.g., https://accounts.google.com)
      --remote-auth-resource string                 OAuth 2.0 resource indicator (RFC 8707)
      --remote-auth-scope-param-name string         Override the query parameter name for scopes in the authorization URL (e.g., 'user_scope' for Slack OAuth)
      --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 (default false)
      --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)
      --remote-forward-headers stringArray          Headers to inject into requests to remote server (format: Name=Value, can be repeated)
      --remote-forward-headers-secret stringArray   Headers with secret values from ToolHive secrets manager (format: Name=secret-name, can be repeated)
      --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)
      --token-exchange-audience string              Target audience for exchanged tokens
      --token-exchange-client-id string             OAuth client ID for token exchange operations
      --token-exchange-client-secret string         OAuth client secret for token exchange operations
      --token-exchange-client-secret-file string    Path to file containing OAuth client secret for token exchange (alternative to --token-exchange-client-secret)
      --token-exchange-header-name string           Custom header name for injecting exchanged token (default: replaces Authorization header)
      --token-exchange-scopes strings               Scopes to request for exchanged tokens
      --token-exchange-subject-token-type string    Type of subject token to exchange. Accepts: access_token (default), id_token (required for Google STS)
      --token-exchange-url string                   OAuth 2.0 token exchange endpoint URL (enables token exchange when provided)

Options inherited from parent commands

      --debug   Enable debug mode

SEE ALSO

  • thv - ToolHive (thv) is a lightweight, secure, and fast manager for MCP servers
  • thv proxy stdio - Create a stdio-based proxy for an MCP server
  • thv proxy tunnel - Create a tunnel proxy for exposing internal endpoints