Command Reference

Complete reference for all MCPProxy CLI commands.

Global Flags

These flags are available for all commands:

Flag	Description
--config	Path to configuration file
--log-level	Log level (debug, info, warn, error)
--data-dir, -d	Data directory path (default: ~/.mcpproxy)
--log-to-file	Enable logging to file in standard OS location
--log-dir	Custom log directory path (overrides standard OS location)
--help	Show help for command

Execution Modes

CLI commands like tools list, call tool, code exec, and auth login support two execution modes:

Daemon Mode (Default)

When mcpproxy serve is running, CLI commands automatically connect to it via Unix socket (macOS/Linux) or named pipe (Windows). This provides:

• Fast execution - Daemon is already loaded with connections established
• Shared state - OAuth tokens, server connections, and search indices are shared
• Real-time sync - Changes made via CLI reflect immediately in daemon

Detection: CLI checks for socket at ~/.mcpproxy/mcpproxy.sock (Unix) or \\.\pipe\mcpproxy-<username> (Windows).

# Start daemon
mcpproxy serve &

# These commands use daemon mode automatically
mcpproxy tools list --server=github-server    # Fast - uses daemon
mcpproxy auth login --server=oauth-server     # OAuth tokens shared with daemon
mcpproxy call tool --tool-name=github:search  # Uses daemon's connection pool

Standalone Mode (Direct Connection)

When no daemon is detected, CLI commands create direct connections to upstream MCP servers. This is useful for:

• Debugging - Full control over connection with verbose logging
• Isolated testing - Independent of daemon state
• Single-use operations - No need to run persistent daemon

# Stop daemon to use standalone mode
pkill -f "mcpproxy serve"

# Now commands connect directly to upstream servers
mcpproxy tools list --server=github-server --log-level=debug
mcpproxy tools list --server=github-server --trace-transport  # Full HTTP/SSE tracing

Forcing Standalone Mode

To debug a specific server connection without stopping the daemon:

# Use a different data directory (creates isolated socket path)
mcpproxy tools list --server=github-server --data-dir=/tmp/debug-session

# Or set empty endpoint to skip socket detection
MCPPROXY_TRAY_ENDPOINT="" mcpproxy tools list --server=github-server

Mode Comparison

Aspect	Daemon Mode	Standalone Mode
Startup	Fast (< 1s)	Slower (2-5s, initializes components)
OAuth Tokens	Shared globally	Isolated per command
Server State	Persistent	Ephemeral
Debugging	Limited visibility	Full component tracing
Use Case	Production / Normal use	Debugging / Testing

Environment Variables

Variable	Description
MCPPROXY_TRAY_ENDPOINT	Override socket path. Set to empty string "" to force standalone mode

Examples:

# Custom socket endpoint
MCPPROXY_TRAY_ENDPOINT="unix:///tmp/custom.sock" mcpproxy tools list --server=myserver

# Force standalone mode (skip daemon)
MCPPROXY_TRAY_ENDPOINT="" mcpproxy tools list --server=myserver --log-level=trace

auth status requires daemon

The auth status command requires a running daemon since it queries the daemon's OAuth state:

mcpproxy auth status --server=oauth-server
# Error: auth status requires running daemon. Start with: mcpproxy serve

Server Commands

serve

Start the MCPProxy server:

mcpproxy serve [flags]

Flag	Description	Default
--listen	Address to listen on	127.0.0.1:8080
--api-key	API key for authentication	auto-generated
--enable-socket	Enable Unix socket/named pipe	true
--tray-endpoint	Tray endpoint override (unix:///path/socket.sock or npipe:////./pipe/name)	-
--debug-search	Enable debug search tool	false
--tool-response-limit	Tool response limit in characters (0 = disabled)	0
--read-only	Enable read-only mode	false
--disable-management	Disable management features	false
--allow-server-add	Allow adding new servers	true
--allow-server-remove	Allow removing servers	true
--enable-prompts	Enable prompts for user input	true

doctor

Run health diagnostics:

mcpproxy doctor

Checks for:

• Upstream server connection errors
• OAuth authentication requirements
• Missing secrets
• Runtime warnings
• Docker isolation status

Upstream Management

upstream list

List all configured servers:

mcpproxy upstream list [flags]

Flag	Description	Default
--output, -o	Output format: table, json	table

upstream logs

View server logs:

mcpproxy upstream logs <server-name> [flags]

Flag	Description
--tail	Number of lines to show
--follow	Follow log output

upstream restart

Restart a server:

mcpproxy upstream restart <server-name>
mcpproxy upstream restart --all

upstream enable/disable

Enable or disable a server:

mcpproxy upstream enable <server-name>
mcpproxy upstream disable <server-name>

Server Discovery

search-servers

Search MCP registries for available servers:

mcpproxy search-servers [flags]

Flag	Description
-r, --registry	Registry ID or name to search (exact match)
-s, --search	Search term for server name/description
-t, --tag	Filter servers by tag/category
-l, --limit	Maximum results (default: 10, max: 50)
--list-registries	List all known registries

Tool Commands

tools list

List available tools:

mcpproxy tools list [flags]

Flag	Description	Default
--server	Filter by server name	-
--timeout, -t	Connection timeout	30s
--output, -o	Output format: table, json, yaml	table
--trace-transport	Enable detailed HTTP/SSE frame-by-frame tracing	false

call tool

Execute a tool:

mcpproxy call tool <server:tool> [flags]

Flag	Description	Default
--input	JSON input data for the tool	{}
--output, -o	Output format: pretty, json	pretty

Code Execution

code exec

Execute JavaScript code:

mcpproxy code exec [flags]

Flag	Description	Default
--code	JavaScript code to execute	-
--file	Path to JavaScript file (alternative to --code)	-
--input	JSON input data	{}
--input-file	Path to JSON file containing input data	-
--max-tool-calls	Maximum tool calls (0 = unlimited)	0
--allowed-servers	Comma-separated list of allowed servers	-

Example:

mcpproxy code exec --code="({ result: input.value * 2 })" --input='{"value": 21}'

See Code Execution for detailed documentation.

Authentication

auth login

Authenticate with an OAuth server:

mcpproxy auth login [flags]

Flag	Description	Default
--server	Server name to authenticate with (required)	-
--timeout	Authentication timeout	5m

auth status

Check authentication status:

mcpproxy auth status [flags]

Flag	Description
--server, -s	Server name to check status for
--all	Show status for all servers

auth logout

Clear OAuth token and disconnect from a server:

mcpproxy auth logout [flags]

Flag	Description	Default
-s, --server	Server name to logout from (required)	-
--timeout	Logout timeout	30s

Secrets Management

secrets set

Store a secret in the system keyring:

mcpproxy secrets set <key> <value> [flags]

Flag	Description
--type	Secret type (api-key, oauth-token, password)
--from-env	Read value from environment variable
--from-stdin	Read value from stdin

Examples:

mcpproxy secrets set github-token "ghp_abc123" --type=oauth-token
mcpproxy secrets set api-key --from-env=MY_API_KEY
echo "secret-value" | mcpproxy secrets set db-password --from-stdin

secrets get

Retrieve a secret:

mcpproxy secrets get <key> [flags]

Flag	Description
--type	Secret type filter
--masked	Show masked value (first/last 4 chars)

secrets del

Delete a secret:

mcpproxy secrets del <key> [flags]

Flag	Description
--type	Secret type filter

secrets list

List all stored secrets:

mcpproxy secrets list [flags]

Flag	Description
--json	Output in JSON format
--all	Show all secret metadata

secrets migrate

Migrate secrets between storage backends:

mcpproxy secrets migrate [flags]

Flag	Description	Default
--dry-run	Show what would be migrated without executing	false
--auto-approve	Skip confirmation prompts	false
--from	Source storage backend	-
--to	Target storage backend	-

Certificate Management

trust-cert

Install a trusted certificate:

mcpproxy trust-cert <certificate-path> [flags]

Flag	Description	Default
--force	Install certificate without confirmation	false
--keychain	Target keychain: 'system' or 'login'	system

Example:

mcpproxy trust-cert /path/to/cert.pem --keychain=system