Configuration

Configuration

The proxy is configured by a JSON file, environment variables, or a mix of both. All values are validated with zod after merging; invalid configuration aborts startup with exit code 2.

Three ways to configure

1. JSON file at the path in MCP_PROXY_CONFIG.
2. Environment variables only (no file required).
3. A mix — env vars override file values, then validation runs on the merged result.

Env overrides are applied before schema parsing, so an env var can satisfy a required field even if the file omits it.

Example file

{
  "upstream": {
    "url": "https://mcp.example.com/mcp",
    "timeoutMs": 300000,
    "openServerStream": true,
    "protocolVersion": "2025-06-18"
  },
  "oauth2": {
    "grant": "authorization_code",
    "clientId": "my-client",
    "scope": "mcp:read mcp:write",
    "callbackPort": 53682
  },
  "log": { "level": "info" }
}

See config.example.json in the repository.

General

Field	Default	Description
allowInsecureHttp	false	Allow cleartext http:// to non-loopback hosts for config and discovered endpoints. See Security.

Upstream

Field	Default	Description
url	(required)	Upstream MCP streamable-HTTP endpoint. Must be https:// or a loopback http://.
timeoutMs	300000	Hard per-request deadline (ms, default 5 min). Aborts the upstream call after this many ms even if data is still trickling in. Should be ≥ your MCP client's tool-call timeout.
openServerStream	true	After initialize, open a GET text/event-stream channel for server-initiated notifications.
protocolVersion	(unset)	Value sent in the MCP-Protocol-Version header.

OAuth2 — common

These fields apply to both grant types. The grant field selects which grant is built (a zod discriminated union).

Field	Description
grant	client_credentials or authorization_code.
tokenUrl	Token endpoint URL. Optional if discovery is enabled.
clientId	OAuth2 client id (required).
clientSecret	OAuth2 client secret (optional for public clients).
scope	Space-separated scopes.
audience	audience form param (used by some IdPs, e.g. Auth0).
authStyle	"body" (default) or "header" (HTTP Basic auth).
refreshSkewSeconds	Refresh expires_in - skew seconds before expiry. Default 30.
extraParams	Map of additional form parameters sent to the token endpoint.

audience is only sent by the client_credentials grant. Both grants forward extraParams to the token endpoint; the interactive flow also forwards them on the authorize request.

OAuth2 — authorization_code specifics

Field	Default	Description
authorizationUrl	(discoverable)	IdP authorization endpoint.
interactive	true	Open a browser for first-time login.
callbackHost	127.0.0.1	Host the local callback listener binds to.
callbackPort	53682	Port the local callback listener binds to. Must match a redirect URI registered with your IdP.
callbackTimeoutSeconds	300	How long to wait for the user to complete the browser login.
redirectUri	derived	Override the auto-derived http://<host>:<port>/callback.
authorizationCode	(unset)	Pre-supply a one-shot code (skips the browser flow).
codeVerifier	(unset)	PKCE verifier matching a pre-supplied code.
refreshToken	(unset)	Pre-supply a refresh token (skips the browser flow entirely).
tokenCacheDir	per-OS config dir	Where the encrypted refresh-token cache lives.

The interactive flow, code exchange, and refresh-token cache are explained in OAuth2 Grants and Tokens.

Discovery

Field	Default	Description
enabled	true	Fetch RFC 9728 / RFC 8414 metadata from the upstream.

Disable with "discovery": { "enabled": false } or DISCOVERY_ENABLED=false. Full details on Discovery.

Logging

Field	Default	Description
level	"info"	One of trace, debug, info, warn, error, fatal.

All logs go to stderr; stdout is reserved for JSON-RPC. Secrets are redacted (see Security).

Environment variables

Every env var below maps onto a config field. Env vars win over file values.

Env var	Maps to
MCP_PROXY_CONFIG	Path to config JSON (optional).
UPSTREAM_URL	upstream.url
UPSTREAM_TIMEOUT_MS	upstream.timeoutMs
UPSTREAM_OPEN_SERVER_STREAM	upstream.openServerStream
UPSTREAM_PROTOCOL_VERSION	upstream.protocolVersion
LOG_LEVEL	log.level
OAUTH2_GRANT	oauth2.grant
OAUTH2_TOKEN_URL	oauth2.tokenUrl
OAUTH2_CLIENT_ID	oauth2.clientId
OAUTH2_CLIENT_SECRET	oauth2.clientSecret
OAUTH2_SCOPE	oauth2.scope
OAUTH2_AUDIENCE	oauth2.audience
OAUTH2_AUTH_STYLE	oauth2.authStyle
OAUTH2_REFRESH_SKEW_SECONDS	oauth2.refreshSkewSeconds
OAUTH2_EXTRA_PARAMS	oauth2.extraParams (JSON)
OAUTH2_AUTHORIZATION_URL	oauth2.authorizationUrl
OAUTH2_AUTHORIZATION_CODE	oauth2.authorizationCode
OAUTH2_CODE_VERIFIER	oauth2.codeVerifier
OAUTH2_REFRESH_TOKEN	oauth2.refreshToken
OAUTH2_REDIRECT_URI	oauth2.redirectUri
OAUTH2_INTERACTIVE	oauth2.interactive
OAUTH2_CALLBACK_HOST	oauth2.callbackHost
OAUTH2_CALLBACK_PORT	oauth2.callbackPort
OAUTH2_CALLBACK_TIMEOUT_SECONDS	oauth2.callbackTimeoutSeconds
OAUTH2_TOKEN_CACHE_DIR	oauth2.tokenCacheDir
DISCOVERY_ENABLED	discovery.enabled
ALLOW_INSECURE_HTTP	allowInsecureHttp

Value parsing notes

• Booleans accept true/false/1/0/yes/no/on/off (case-insensitive); anything else is treated as false.
• Integers (*_MS, ports, timeouts, skew) must be plain integers or startup fails with a clear error.
• OAUTH2_EXTRA_PARAMS must be valid JSON (an object of string values).
• Prefer env vars for secrets so they don't end up on disk.