Management Commands

MCPProxy provides CLI commands for managing upstream servers and monitoring system health.

Quick Diagnostics

Run this first when debugging any issue:

mcpproxy doctor

This checks for:

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

Common Workflow

mcpproxy doctor                     # Check overall health
mcpproxy upstream list              # Identify issues
mcpproxy upstream logs failing-srv  # View logs
mcpproxy upstream restart failing-srv

Upstream Commands

List Servers

mcpproxy upstream list

Output shows unified health status:

• Server name and protocol type
• Tool count
• Health status with emoji indicator (✅ healthy, ⚠️ degraded, ❌ unhealthy, ⏸️ disabled, 🔒 quarantined)
• Suggested action command when applicable

Example output:

NAME                      PROTOCOL   TOOLS      STATUS                         ACTION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅    github-server           http       15         Connected (15 tools)           -
❌    oauth-server            http       0          Token expired                  auth login --server=oauth-server

View Logs

# View last 100 lines
mcpproxy upstream logs github-server --tail=100

# Follow logs in real-time (requires daemon)
mcpproxy upstream logs github-server --follow

Restart Server

# Restart single server
mcpproxy upstream restart github-server

# Restart all servers
mcpproxy upstream restart --all

Enable/Disable

mcpproxy upstream enable server-name
mcpproxy upstream disable server-name

Patch Headers / Env

mcpproxy upstream patch updates HTTP headers and stdio env on an existing server using JSON Merge Patch semantics — keys you specify are upserted, keys named in --header-remove / --env-remove are deleted, and every other key on the stored config is preserved.

This means you can rotate a single Bearer token without seeing or touching any other header. The same applies to env vars on stdio servers.

# Rotate the Authorization header on a connected server
mcpproxy upstream patch synapbus --header "Authorization: Bearer new-token"

# Add a custom header without disturbing existing ones
mcpproxy upstream patch synapbus --header "X-Trace: on"

# Remove a stale header
mcpproxy upstream patch synapbus --header-remove "X-Old"

# Set + remove in one round-trip
mcpproxy upstream patch synapbus --header "X-New: v" --header-remove "X-Old"

# Update env vars on a stdio server
mcpproxy upstream patch obsidian-pilot \
  --env "LOG_LEVEL=debug" --env-remove "OBSOLETE_VAR"

Flags (all repeatable):

Notes:

• Requires the daemon to be running (mcpproxy serve). The subcommand applies changes through the live REST endpoint so connection state and OAuth tokens stay coordinated; editing mcp_config.json by hand is only safe while the daemon is offline.
• Specifying the same key in both --header and --header-remove is a conflict and errors out with a useful message.
• For new servers, use upstream add (HTTP/stdio) or upstream add-json (full JSON shape) instead.

Socket Communication

CLI commands automatically detect and use Unix socket/named pipe communication when the daemon is running.

Benefits of socket mode:

• Reuses daemon's existing server connections (faster)
• Shows real daemon state (not config file state)
• Coordinates OAuth tokens with running daemon
• No redundant server connection overhead

Commands with socket support:

• upstream list/logs/enable/disable/restart/patch
• doctor (requires daemon)
• call tool
• code exec
• tools list
• auth login/status

Standalone commands (no socket needed):

• secrets - Direct OS keyring operations
• trust-cert - File system operations
• search-servers - Registry API operations

Log Locations

Files:

• main.log - Main application log
• server-{name}.log - Per-server logs (reserved characters in {name}, e.g. the / in registry names, are sanitized to _)