---
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](thv.md)	 - ToolHive (thv) is a lightweight, secure, and fast manager for MCP servers
* [thv proxy stdio](thv_proxy_stdio.md)	 - Create a stdio-based proxy for an MCP server
* [thv proxy tunnel](thv_proxy_tunnel.md)	 - Create a tunnel proxy for exposing internal endpoints

