Status Command

The mcpproxy status command displays the current state of your MCPProxy instance including running status, API key, Web UI URL, and server statistics.

Overview

mcpproxy status [flags]

The command operates in two modes:

• Daemon mode: When MCPProxy is running, queries live data via Unix socket
• Config mode: When MCPProxy is not running, reads from the config file

Flags

Flag	Short	Default	Description
--show-key		false	Display the full unmasked API key
--web-url		false	Print only the Web UI URL (for piping)
--reset-key		false	Regenerate API key and save to config
--output	-o	table	Output format: table, json, yaml
--json		false	Shorthand for -o json

Examples

Basic Status Check

mcpproxy status

When daemon is running:

MCPProxy Status
Needs attention: 3 (run 'mcpproxy attention')
  State:       Running
  Version:     v1.2.0 (update available: v1.3.0 — https://github.com/smart-mcp-proxy/mcpproxy-go/releases/tag/v1.3.0)
  Listen:      127.0.0.1:8080
  Uptime:      2h 15m
  API Key:     a1b2****gh78
  Web UI:      http://127.0.0.1:8080/ui/?apikey=a1b2...gh78
  Routing:     retrieve_tools
  Servers:     12 connected, 2 quarantined
  Socket:      /Users/you/.mcpproxy/mcpproxy.sock
  Config:      /Users/you/.mcpproxy/mcp_config.json

Endpoint & mode
  Routing mode:    retrieve_tools
  /mcp             http://127.0.0.1:8080/mcp  (default, retrieve_tools mode)
  /mcp/call        http://127.0.0.1:8080/mcp/call  (retrieve + call tools)

The first line after the header is the needs-attention count, the same number the Web UI header pill and Home badge and the macOS tray show; it reads Needs attention: none when nothing needs you. An older daemon without the endpoint omits the line. See Attention Command.

The Endpoint & mode section (it was named "MCP Endpoints" before) lists the routing mode and the MCP endpoints to point a client at, the same facts the Clients page shows on its Endpoint & mode tab. JSON output is unchanged.

When daemon is not running:

MCPProxy Status
  State:       Not running
  Listen:      127.0.0.1:8080 (configured)
  API Key:     a1b2****gh78
  Web UI:      http://127.0.0.1:8080/ui/?apikey=a1b2...gh78
  Config:      /Users/you/.mcpproxy/mcp_config.json

Show Full API Key

# Display full key for copying
mcpproxy status --show-key

# Copy to clipboard (macOS)
mcpproxy status --show-key -o json | jq -r .api_key | pbcopy

Open Web UI in Browser

# macOS
open $(mcpproxy status --web-url)

# Linux
xdg-open $(mcpproxy status --web-url)

Reset API Key

mcpproxy status --reset-key

Output:

Warning: Resetting the API key will disconnect any HTTP clients using the current key.
         Socket connections (tray app) are NOT affected.

New API key: e7f8a9b0c1d2e3f4...
Saved to: /Users/you/.mcpproxy/mcp_config.json

MCPProxy Status
  State:       Running
  ...
  API Key:     e7f8a9b0c1d2e3f4...

note

If the MCPPROXY_API_KEY environment variable is set, resetting the key in the config file will not take effect until the environment variable is removed or updated.

JSON Output

mcpproxy status -o json

{
  "state": "Running",
  "listen_addr": "127.0.0.1:8080",
  "uptime": "2h 15m",
  "uptime_seconds": 8100,
  "api_key": "a1b2****gh78",
  "web_ui_url": "http://127.0.0.1:8080/ui/?apikey=...",
  "routing_mode": "retrieve_tools",
  "servers": {
    "connected": 12,
    "quarantined": 2,
    "total": 14
  },
  "socket_path": "/Users/you/.mcpproxy/mcpproxy.sock",
  "config_path": "/Users/you/.mcpproxy/mcp_config.json",
  "version": "v1.2.0",
  "update": {
    "available": true,
    "latest_version": "v1.3.0",
    "release_url": "https://github.com/smart-mcp-proxy/mcpproxy-go/releases/tag/v1.3.0",
    "checked_at": "2026-07-02T10:00:00Z"
  }
}

Update Availability

When the daemon is running, status surfaces the result of the background update check (the same update object as GET /api/v1/info and mcpproxy doctor):

• Update available: Version: v1.2.0 (update available: v1.3.0, 8 releases / ~14 weeks behind — <release URL>)
  • The N releases / M weeks behind clause (Spec 079 FR-002) appears only when the daemon resolved a delta. Resolving it needs a second GitHub request for the release list and publish dates, so it is absent when that request fails or is rate-limited, when the running build has no release record, and against a daemon older than the feature — the line then reads exactly as it did before, without the clause. A build too old for the scanned window reports a lower bound (59+ releases).
• Up to date: Version: v1.3.0 (latest)
• Check failed or not yet completed (offline, rate-limited): the version is shown without any annotation. In JSON output the update.check_error field retains the failure reason for diagnostics.
• Update checking disabled (update_check.enabled: false in the config, or MCPPROXY_DISABLE_AUTO_UPDATE=true): the daemon performs no check and omits the update object entirely, so the version is shown without any annotation.

In machine-readable output (-o json/-o yaml) the update object also carries checked_at (when the last successful check ran, so consumers can judge staleness) and is_prerelease (whether the offered version is a prerelease), matching the /api/v1/info contract.

API Key Masking

By default, the API key is masked showing only the first 4 and last 4 characters:

a1b2c3d4e5f6...7890abcd  →  a1b2****abcd

Use --show-key to reveal the full key. The --reset-key flag implicitly shows the full new key.

Transport and Authentication

Transport	Auth Required	Affected by Key Reset
Unix socket (tray app, CLI)	No (OS-level auth)	No
HTTP/TCP (remote clients)	Yes (API key)	Yes - clients need new key
MCP endpoints (/mcp)	No	No

Exit Codes

Code	Meaning
0	Success
1	General error (config load failure, etc.)
4	Config error