Skip to content

command-reference.md

Latest commit

 

History

History
590 lines (425 loc) · 16.8 KB

command-reference.md

File metadata and controls

590 lines (425 loc) · 16.8 KB
Raw
id command-reference
title Command Reference
sidebar_label Command Reference
sidebar_position 1
description Complete CLI command reference for MCPProxy
keywords
cli
commands
terminal
shell

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

:::tip 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

:::note 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

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)

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 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

:::note 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 -
--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 --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.