proxyman-mcp-setup

Proxyman MCP Setup

Configure an agent to talk to Proxyman MCP through Proxyman's bundled stdio bridge.

Operating Rules

1. This skill is shell-first. MCP tools may not be connected yet.
2. Do not use API-key or direct HTTP MCP configuration. Proxyman MCP uses a local stdio bridge executable.
3. Proxyman must be installed, running, and have Settings > MCP > MCP Server enabled before verification can pass.
4. Preserve existing MCP server entries in agent config files. Add or update only the proxyman entry.
5. Prefer the exact command shown in Proxyman Settings > MCP when the app exposes one.

Mental Model

Proxyman MCP has two local pieces:

1. The AI agent launches Proxyman's bundled mcp-server executable over stdio.
2. The bridge reads mcp-handshake.json from Proxyman's app data folder.
3. The bridge forwards tool calls to the running app at http://127.0.0.1:<ephemeral-port>/mcp with a bearer token from the handshake file.
4. The bridge belongs to one client session and exits when the client's stdin reaches EOF. The MCP client should launch it again for the next session.

Do not hardcode the HTTP port or token. The app regenerates them.

Common handshake locations:

Do not edit the handshake file. If it is missing or stale, restart Proxyman and re-enable Settings > MCP.

Step 1: Verify Proxyman Is Installed

macOS

if [ -d "/Applications/Proxyman.app" ]; then
  echo "INSTALLED: /Applications/Proxyman.app"
elif mdfind 'kMDItemCFBundleIdentifier == "com.proxyman.NSProxy"' | grep -q "Proxyman.app"; then
  mdfind 'kMDItemCFBundleIdentifier == "com.proxyman.NSProxy"'
else
  echo "NOT_INSTALLED"
fi

Windows (PowerShell)

$installed = Get-ItemProperty `
  "HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\*",
  "HKCU:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\*",
  "HKLM:\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall\*" `
  -ErrorAction SilentlyContinue |
  Where-Object { $_.DisplayName -like "*Proxyman*" }
if ($installed) { "INSTALLED" } else { "NOT_INSTALLED" }

Linux

if command -v proxyman >/dev/null 2>&1 || ls "$HOME"/Downloads/Proxyman*.AppImage "$HOME"/Downloads/proxyman*.AppImage >/dev/null 2>&1; then
  echo "INSTALLED"
else
  echo "NOT_INSTALLED"
fi

If Proxyman is not installed, stop and use proxyman-download-setup.

Step 2: Launch Proxyman And Enable MCP

macOS

open -a "Proxyman"
sleep 10

Windows (PowerShell)

$candidates = @(
  "$env:LOCALAPPDATA\Programs\Proxyman\Proxyman.exe",
  "C:\Program Files\Proxyman\Proxyman.exe",
  "C:\Program Files (x86)\Proxyman\Proxyman.exe"
)
$proxymanExe = $candidates | Where-Object { Test-Path $_ } | Select-Object -First 1
if ($proxymanExe) { Start-Process $proxymanExe; Start-Sleep 10 }

Linux

if command -v proxyman >/dev/null 2>&1; then
  nohup proxyman >/dev/null 2>&1 &
else
  nohup "$HOME/Downloads/Proxyman.AppImage" >/dev/null 2>&1 &
fi
sleep 10

Ask the user to open Proxyman Settings > MCP and enable "MCP Server". If the MCP toggle is locked, the user must authorize the plan/license required by their Proxyman build.

If a bundled proxyman-cli is already available, it can persist the same state even while Proxyman is closed. Read proxyman-cli mcp --help from that installed build, then use its mcp on action only when the user asked to enable MCP. Launch Proxyman afterward before expecting operational MCP calls. Use proxyman-cli skill for executable discovery and exact syntax; do not guess flags from this setup guide.

Keep "Redact Sensitive Data Before Sending to AI" enabled unless the user explicitly wants raw headers, cookies, query strings, or bodies sent to the agent.

On Linux AppImage builds, launching Proxyman lets the app copy the packaged MCP bridge into a stable config path and mark it executable. If the bridge path below is missing, enable MCP in Settings, restart Proxyman, and check again.

Step 3: Resolve The Bridge Executable

macOS

Regular build:

BRIDGE_PATH="/Applications/Proxyman.app/Contents/MacOS/mcp-server"
test -x "$BRIDGE_PATH" && echo "$BRIDGE_PATH"

If the regular path is missing, search installed Proxyman apps:

mdfind 'kMDItemCFBundleIdentifier == "com.proxyman.NSProxy" || kMDItemCFBundleIdentifier == "com.proxyman.NSProxy-setapp"' |
while read -r app; do
  candidate="$app/Contents/MacOS/mcp-server"
  [ -x "$candidate" ] && echo "$candidate"
done

Windows (PowerShell)

The Windows Electron app copies mcp-server.exe beside Proxyman.exe. If no bridge is found, use the exact command from Proxyman Settings > MCP.

$exeCandidates = @(
  "$env:LOCALAPPDATA\Programs\Proxyman\Proxyman.exe",
  "C:\Program Files\Proxyman\Proxyman.exe",
  "C:\Program Files (x86)\Proxyman\Proxyman.exe"
)
$proxymanExe = $exeCandidates | Where-Object { Test-Path $_ } | Select-Object -First 1

$bridgeCandidates = @()
if ($proxymanExe) {
  $bridgeCandidates += Join-Path (Split-Path $proxymanExe -Parent) "mcp-server.exe"
}
$bridgeCandidates += @(
  "$env:LOCALAPPDATA\Programs\Proxyman\mcp-server.exe",
  "C:\Program Files\Proxyman\mcp-server.exe",
  "C:\Program Files (x86)\Proxyman\mcp-server.exe"
)

$bridge = $bridgeCandidates | Where-Object { Test-Path $_ } | Select-Object -First 1
if ($bridge) { $bridge } else { "NOT_FOUND: copy the path from Proxyman Settings > MCP" }

Linux

The packaged Linux AppImage copies mcp-server into Proxyman's config folder after launch. Prefer that stable copied path.

CONFIG_HOME="${XDG_CONFIG_HOME:-$HOME/.config}"
BRIDGE_PATH="$CONFIG_HOME/Proxyman/bin/mcp-server"

if [ -x "$BRIDGE_PATH" ]; then
  echo "$BRIDGE_PATH"
else
  echo "NOT_FOUND: launch Proxyman, enable Settings > MCP, restart Proxyman, or copy the path from Settings > MCP"
fi

Set BRIDGE_PATH to the chosen executable path. It must be the stdio bridge, not the Proxyman app binary.

Step 4: Detect The Agent Config

Use environment variables first, then parent process, then filesystem markers.

[ -n "$OPENAI_CODEX" ] && echo "codex"
[ -n "$CLAUDE_CODE_ENTRYPOINT" ] && echo "claude-code"
[ -n "$CURSOR_TRACE_ID" ] || [ "$TERM_PROGRAM" = "cursor" ] && echo "cursor"
[ -n "$VSCODE_PID" ] || [ "$TERM_PROGRAM" = "vscode" ] && echo "vscode"
[ -n "$GITHUB_COPILOT_CLI" ] && echo "copilot-cli"

Fallback markers:

test -d "$HOME/.codex" && echo "codex"
test -d "$HOME/.claude" && echo "claude-code"
test -d "$HOME/.cursor" && echo "cursor"
test -d ".vscode" && echo "vscode"
test -f "$HOME/.copilot/mcp-config.json" && echo "copilot-cli"
test -f "$HOME/Library/Application Support/Claude/claude_desktop_config.json" && echo "claude-desktop"

If multiple agents are detected, ask the user which agent they want to configure.

Step 5: Add The MCP Server

Codex CLI

Preferred command:

codex mcp add proxyman -- "$BRIDGE_PATH"

Equivalent TOML:

[mcp_servers.proxyman]
enabled = true
command = "BRIDGE_PATH"
args = []

Config file: ~/.codex/config.toml.

Claude Code

claude mcp add proxyman --transport stdio -- "$BRIDGE_PATH"

Config file: ~/.claude.json.

Claude Desktop

Config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Server entry:

{
  "mcpServers": {
    "proxyman": {
      "command": "BRIDGE_PATH",
      "args": [],
      "env": {}
    }
  }
}

Cursor

Config file: ~/.cursor/mcp.json.

{
  "mcpServers": {
    "proxyman": {
      "command": "BRIDGE_PATH",
      "args": [],
      "env": {}
    }
  }
}

VS Code / GitHub Copilot

Config file:

• macOS: ~/Library/Application Support/Code/User/mcp.json or workspace .vscode/mcp.json
• Linux: ~/.config/Code/User/mcp.json or workspace .vscode/mcp.json
• Windows: %APPDATA%\Code\User\mcp.json or workspace .vscode\mcp.json

{
  "servers": {
    "proxyman": {
      "command": "BRIDGE_PATH",
      "args": [],
      "env": {}
    }
  }
}

GitHub Copilot CLI

Config file: ~/.copilot/mcp-config.json.

{
  "mcpServers": {
    "proxyman": {
      "command": "BRIDGE_PATH",
      "args": [],
      "env": {},
      "tools": ["*"]
    }
  }
}

When editing JSON or TOML config manually, parse and merge with a real parser when possible. Never replace unrelated mcpServers or servers entries.

Step 6: Verify

Restart or reload the agent after changing config.

Verification sequence:

1. Confirm Proxyman is running.
2. Confirm Settings > MCP shows the server running.
3. Ask the agent to list MCP tools/resources/prompts if it supports discovery.
4. Call get_version.
5. Call get_proxy_status.

Successful setup means the agent can see Proxyman tools and get_version returns a Proxyman app/bridge response.

Tool availability can vary by platform and build. Treat the live tool list as authoritative. In particular, macOS system proxy control, Apple Terminal/iTerm/Ghostty injection, .app Electron injection, and bridge app-control tools are macOS-oriented; do not offer them on Windows or Linux unless that server exposes an applicable schema.

Troubleshooting

Next Step

Once get_version and get_proxy_status work:

• use proxyman-traffic-debugging for the complete MCP operation surface;
• use proxyman-https-capture for device, emulator, browser, runtime, and framework routing/trust setup;
• use proxyman-debugging-tools for current official feature documentation;
• use proxyman-cli for version-matched shell automation.