CLI Reference

Subcommands

mcpr [COMMAND] [OPTIONS]

Command	Description
run	Start proxy in foreground (default if omitted)
validate	Validate config file and exit
version	Print version info as JSON

Backward compat: mcpr --mcp http://... (no subcommand) still works and defaults to run.

Config priority: CLI args > environment variables > mcpr.toml > defaults

mcpr run

Start the proxy in the foreground. This is the default when no subcommand is given.

Proxy options

Flag	Description	Default
--mcp <URL>	Upstream MCP server URL	required
--widgets <URL|PATH>	Widget source — URL to proxy, or local path for static serving	—
--port <PORT>	Local proxy port	3000
--no-tunnel	Direct HTTP mode, no tunnel	false
--events	Emit structured JSON events to stdout	false
--csp <DOMAIN>	Extra CSP domains (repeatable)	—
--csp-mode <MODE>	CSP mode: extend (default) or override	extend
--cloud-token <TOKEN>	Cloud sync token (from cloud.mcpr.app)	—
--cloud-server <SLUG>	Server slug for cloud routing	—
--relay-url <URL>	Custom relay server URL	tunnel.mcpr.app

Runtime options

Flag	Description	Default
--tui	Force TUI dashboard on	auto-detect
--no-tui	Force TUI dashboard off (for Docker/CI)	false
--drain-timeout <SECS>	Graceful shutdown timeout	30
--log-format <FMT>	Stderr log format: json or pretty	json
--admin-bind <ADDR>	Admin API bind address (set to none to disable)	127.0.0.1:9901

Relay options

Run mcpr as a relay server instead of a proxy:

Flag	Description
--relay	Run in relay server mode
--relay-domain <DOMAIN>	Relay base domain (required in relay mode)
--auth-provider <URL>	External auth provider URL
--auth-provider-secret <SECRET>	Auth provider shared secret

mcpr validate

Validate a config file and exit with code 0 (valid) or 1 (errors).

Flag	Description	Default
-c, --config <PATH>	Config file to validate	./mcpr.toml
--dump	Dump resolved config after validation	false

mcpr validate
mcpr validate -c /etc/mcpr/mcpr.toml

mcpr version

Print version and build info as JSON.

mcpr version
# {"version":"0.3.0","target":"aarch64-apple-darwin"}

Environment variables

Variable	Description
MCPR_RELAY_URL	Custom relay server URL
MCPR_CLOUD_TOKEN	Cloud sync token (from cloud.mcpr.app)
MCPR_AUTH_PROVIDER	Auth provider URL (relay mode)
MCPR_AUTH_PROVIDER_SECRET	Auth provider shared secret (relay mode)
MCPR_NO_TUI	Set to 1 to disable TUI (set by default in Docker image)
MCPR_TUI	Set to 1 to force TUI on

Admin API

The admin API runs on a separate port (default 127.0.0.1:9901), designed for health probes and operational tooling.

Method	Path	Description
GET	/healthz	Liveness — 200 unless shutting down
GET	/ready	Readiness — 503 while draining or MCP upstream disconnected
GET	/version	Version info as JSON

Disable with --admin-bind none.

Signal handling

Signal	Action
SIGTERM	Graceful drain then shutdown (K8s sends this)
SIGINT	Same as SIGTERM

On receiving a shutdown signal, mcpr:

1. Marks /ready as 503
2. Stops accepting new connections
3. Waits for in-flight requests (up to --drain-timeout)
4. Flushes logs
5. Exits

Examples

# Minimal — MCP server with tunnel
mcpr run --mcp http://localhost:9000

# MCP + widgets with tunnel
mcpr run --mcp http://localhost:9000 --widgets http://localhost:4444

# Local only, no tunnel
mcpr run --mcp http://localhost:9000 --no-tunnel --port 3000

# Production — headless with JSON logs
mcpr run --mcp http://localhost:9000 --no-tunnel --port 8080 --no-tui

# Human-readable logs for debugging
mcpr run --mcp http://localhost:9000 --no-tui --log-format pretty

# Custom admin port
mcpr run --mcp http://localhost:9000 --admin-bind 0.0.0.0:9901

# Validate config
mcpr validate -c ./mcpr.toml

# Run as relay server
mcpr run --relay --relay-domain tunnel.yourdomain.com --port 443

Config file

mcpr also reads from mcpr.toml. See Configuration and Config Reference.