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 --json_args='{}'  # 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 [flags]

Flag	Description	Default
--output, -o	Output format: pretty, json	pretty
--log-level, -l	Log level	warn
--config, -c	Path to config file	auto-detect

The first section is the same needs-attention list mcpproxy attention prints; the diagnostics follow under Diagnostics: N findings. It checks for:

• Upstream server connection errors
• OAuth authentication requirements
• Missing secrets
• Runtime warnings
• Docker isolation status
• Tools pending quarantine approval (pending/changed counts per server)
• Security features status (routing mode, sensitive data detection)

attention

Print the one needs-attention list every surface shares. See Attention Command.

mcpproxy attention [-o table|json|yaml]

review

Review quarantined servers and new or changed tools through the scan gate. See Review Commands.

mcpproxy review list
mcpproxy review show <server> [--full]
mcpproxy review approve <server> [--tools a,b] [--except a,b] [--force] [--yes]
mcpproxy review reject <server> [--tools a,b] [--yes]

catalog

Search every catalog source, show an entry and add it quarantined. See Catalog Commands.

mcpproxy catalog search [query] [--source <id>] [--limit <n>]
mcpproxy catalog show <source>/<id>
mcpproxy catalog add <source>/<id> [--name <name>] [--env KEY=VALUE]

registry search and registry add are deprecated aliases of catalog search and catalog add; registry list, add-source, edit and remove manage the catalog sources.

client

List the clients MCPProxy knows about (installed, connected, seen), with their connection state and reload hint, and manage their profile bindings. The client commands are documented with the profile commands in Profile Commands.

mcpproxy client list
mcpproxy client show <client>

Upstream Management

upstream list

List all configured servers:

mcpproxy upstream list [flags]

Flag	Description	Default
--output, -o	Output format: table, json	table
--status	Filter by health status; repeatable, a comma-separated value is the same as repeating the flag	all

The STATUS column is the status label (Online, Connecting, Sign-in required, Needs review, Secret required, Needs configuration, Error, Disabled). See Management Commands.

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 inspect

Inspect tool approval status for a server (tool-level quarantine):

mcpproxy upstream inspect <server-name> [flags]

Flag	Description	Default
--tool	Inspect a specific tool by name	all tools
--output, -o	Output format: table, json	table

Examples:

# Show all tool approvals for a server
mcpproxy upstream inspect github-server

# Inspect a specific tool (shows diff if changed)
mcpproxy upstream inspect github-server --tool create_issue

# JSON output for scripting
mcpproxy upstream inspect github-server --output=json

See Tool Quarantine for details.

upstream approve

Approve quarantined tools for a server:

mcpproxy upstream approve <server-name> [tool-names...]

Without specific tool names, approves all pending/changed tools.

Examples:

# Approve all pending/changed tools
mcpproxy upstream approve github-server

# Approve specific tools
mcpproxy upstream approve github-server create_issue list_repos

upstream enable/disable

Enable or disable a server:

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

Configuration Import

upstream import

Import MCP server configurations from other AI tools:

mcpproxy upstream import <path> [flags]

Flag	Description	Default
--server, -s	Import only a specific server by name	all
--format	Force format (claude-desktop, claude-code, cursor, codex, gemini)	auto-detect
--dry-run	Preview import without making changes	false
--no-quarantine	Don't quarantine imported servers (use with caution)	false

Supported Formats:

Source	Format Flag	Auto-detected
Claude Desktop	claude-desktop	Yes
Claude Code	claude-code	Yes
Cursor IDE	cursor	Yes
Codex CLI	codex	Yes (TOML)
Gemini CLI	gemini	Yes

Examples:

# Import from Claude Desktop config
mcpproxy upstream import ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Import from Claude Code config
mcpproxy upstream import ~/.claude.json

# Preview without importing
mcpproxy upstream import --dry-run config.json

# Import with format hint (if auto-detect fails)
mcpproxy upstream import --format claude-desktop config.json

# Import only a specific server
mcpproxy upstream import --server github-server config.json

# Import without quarantine (trusted configs)
mcpproxy upstream import --no-quarantine ~/Library/Application\ Support/Claude/claude_desktop_config.json

Canonical Config Paths:

Source	macOS	Windows	Linux
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json	%APPDATA%\Claude\claude_desktop_config.json	~/.config/Claude/claude_desktop_config.json
Claude Code	~/.claude.json	~/.claude.json	~/.claude.json
Cursor IDE	~/.cursor/mcp.json	~/.cursor/mcp.json	~/.cursor/mcp.json
Codex CLI	~/.codex/config.toml	~/.codex/config.toml	~/.codex/config.toml
Gemini CLI	~/.gemini/settings.json	~/.gemini/settings.json	~/.gemini/settings.json

Imported servers are quarantined

For security, all imported servers are quarantined by default. Use --no-quarantine to skip quarantine for configs you trust.

See Configuration Import for Web UI and REST API documentation.

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	-
--tier	Filter by tier: read, write, destructive, unannotated (--risk is an alias)	-
--approval	Filter by review state: approved (Approved), pending (New, needs review), changed (Changed, needs review)	-
--timeout, -t	Connection timeout	30s
--output, -o	Output format: table, json, yaml	table
--trace-transport	Enable detailed HTTP/SSE frame-by-frame tracing	false

The TIER column is computed once by the core, so it agrees with the Web UI, macOS and the review payload.

activity list --view

mcpproxy activity list --view calls|system|all selects the same views as the Web UI and macOS Activity page: calls is tool calls only, system is system events, all is everything (the default, so scripts keep working). The CLI has no sessions view; use --session <id> for one session's history. --from and --to take RFC 3339 or relative times (-24h). See Activity Commands.

call tool

Execute a tool:

mcpproxy call tool --tool-name=<server:tool> [flags]

Flag	Description	Default
--tool-name	Tool name in format server:tool or built-in tool name	-
--json_args, -j	JSON arguments for the tool	{}
--output, -o	Output format: pretty, json	pretty

Examples:

# Call a built-in tool
mcpproxy call tool --tool-name=upstream_servers --json_args='{"operation":"list"}'

# Call an upstream server tool
mcpproxy call tool --tool-name=github:list_repos --json_args='{"owner":"myorg"}'

Intent-Based Tool Variants

For granular permission control, use intent-based tool variants:

# Read-only operations (safe, no side effects)
mcpproxy call tool-read --tool-name=github:list_repos --json_args='{}'

# Write operations (creates/modifies state)
mcpproxy call tool-write --tool-name=github:create_issue --json_args='{"title":"Bug"}'

# Destructive operations (deletes/removes state)
mcpproxy call tool-destructive --tool-name=github:delete_repo --json_args='{"repo":"test"}'

Flag	Description	Default
--tool-name	Tool name in format server:tool	-
--json_args, -j	JSON arguments for the tool	{}
--reason	Human-readable reason for the operation	-
--sensitivity	Data sensitivity: public, internal, private, unknown	-
--output, -o	Output format: pretty, json	pretty

Code Execution

code exec

Execute JavaScript or TypeScript code:

mcpproxy code exec [flags]

Flag	Description	Default
--code	JavaScript or TypeScript code to execute	-
--file	Path to JS/TS file (alternative to --code)	-
--language	Source code language: javascript, typescript	javascript
--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	-

Examples:

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

# TypeScript with type annotations
mcpproxy code exec --language typescript --code="const x: number = 42; ({ result: x })"

# TypeScript from file
mcpproxy code exec --language typescript --file=script.ts --input-file=params.json

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

Security Scanner Commands

MCPProxy integrates Docker-based security scanners that analyze quarantined upstream MCP servers for tool poisoning, prompt injection, CVEs, and other supply-chain risks. All commands live under mcpproxy security and cover three workflows:

1. Scanner lifecycle — scanners, enable, disable, configure
2. Scan operations — scan (with --all, --async, --dry-run, --scanners), rescan, status, report, cancel-all
3. Approval & integrity — approve, reject, integrity, overview

Quick examples:

mcpproxy security scanners                      # list registry + status
mcpproxy security enable mcp-scan               # pull the scanner image
mcpproxy security configure mcp-scan --env SNYK_TOKEN=xxx
mcpproxy security scan github-server            # blocking, live progress
mcpproxy security scan github-server --dry-run  # print plan, no containers
mcpproxy security report github-server          # aggregated findings
mcpproxy security approve github-server         # unquarantine + index tools

For the full reference — every flag, every status vocabulary, all output formats (table / json / yaml / sarif), workflow recipes, and troubleshooting — see Security Commands. For the underlying feature architecture see Security Scanner Plugin System.

Reviewing quarantined servers and new or changed tools has its own command group, mcpproxy review list|show|approve|reject: see Review Commands.