Update to Proxyman

{
  "description": "Connect an AI coding agent to Proxyman MCP. Use when Proxyman is installed but the agent cannot see tools, or when configuring Codex, Claude, Cursor, VS Code, or Copilot and troubleshooting bridge, handshake, or tool-discovery errors.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 221
    }
  ],
  "name": "proxyman-mcp-setup",
  "skill_md_contents": "---\nname: \"proxyman-mcp-setup\"\ndescription: \"Connect an AI coding agent to Proxyman MCP. Use when Proxyman is installed but the agent cannot see tools, or when configuring Codex, Claude, Cursor, VS Code, or Copilot and troubleshooting bridge, handshake, or tool-discovery errors.\"\n---\n\n# Proxyman MCP Setup\n\nConfigure an agent to talk to Proxyman MCP through Proxyman's bundled stdio bridge.\n\n## Operating Rules\n\n1. This skill is shell-first. MCP tools may not be connected yet.\n2. Do not use API-key or direct HTTP MCP configuration. Proxyman MCP uses a local stdio bridge executable.\n3. Proxyman must be installed, running, and have Settings > MCP > MCP Server enabled before verification can pass.\n4. Preserve existing MCP server entries in agent config files. Add or update only the `proxyman` entry.\n5. Prefer the exact command shown in Proxyman Settings > MCP when the app exposes one.\n\n## Mental Model\n\nProxyman MCP has two local pieces:\n\n1. The AI agent launches Proxyman's bundled `mcp-server` executable over stdio.\n2. The bridge reads `mcp-handshake.json` from Proxyman's app data folder.\n3. 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.\n4. 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.\n\nDo not hardcode the HTTP port or token. The app regenerates them.\n\nCommon handshake locations:\n\n| Platform/build | Handshake folder |\n|----------------|------------------|\n| macOS native app | Proxyman Application Support bundle folder, including regular and Setapp bundle IDs |\n| Windows Electron app | `%APPDATA%\\Proxyman` |\n| Linux Electron app | `${XDG_CONFIG_HOME:-$HOME/.config}/Proxyman` |\n\nDo not edit the handshake file. If it is missing or stale, restart Proxyman and re-enable Settings > MCP.\n\n## Step 1: Verify Proxyman Is Installed\n\n### macOS\n\n```bash\nif [ -d \"/Applications/Proxyman.app\" ]; then\n  echo \"INSTALLED: /Applications/Proxyman.app\"\nelif mdfind 'kMDItemCFBundleIdentifier == \"com.proxyman.NSProxy\"' | grep -q \"Proxyman.app\"; then\n  mdfind 'kMDItemCFBundleIdentifier == \"com.proxyman.NSProxy\"'\nelse\n  echo \"NOT_INSTALLED\"\nfi\n```\n\n### Windows (PowerShell)\n\n```powershell\n$installed = Get-ItemProperty `\n  \"HKLM:\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\*\",\n  \"HKCU:\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\*\",\n  \"HKLM:\\SOFTWARE\\WOW6432Node\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\*\" `\n  -ErrorAction SilentlyContinue |\n  Where-Object { $_.DisplayName -like \"*Proxyman*\" }\nif ($installed) { \"INSTALLED\" } else { \"NOT_INSTALLED\" }\n```\n\n### Linux\n\n```bash\nif command -v proxyman >/dev/null 2>&1 || ls \"$HOME\"/Downloads/Proxyman*.AppImage \"$HOME\"/Downloads/proxyman*.AppImage >/dev/null 2>&1; then\n  echo \"INSTALLED\"\nelse\n  echo \"NOT_INSTALLED\"\nfi\n```\n\nIf Proxyman is not installed, stop and use `proxyman-download-setup`.\n\n## Step 2: Launch Proxyman And Enable MCP\n\n### macOS\n\n```bash\nopen -a \"Proxyman\"\nsleep 10\n```\n\n### Windows (PowerShell)\n\n```powershell\n$candidates = @(\n  \"$env:LOCALAPPDATA\\Programs\\Proxyman\\Proxyman.exe\",\n  \"C:\\Program Files\\Proxyman\\Proxyman.exe\",\n  \"C:\\Program Files (x86)\\Proxyman\\Proxyman.exe\"\n)\n$proxymanExe = $candidates | Where-Object { Test-Path $_ } | Select-Object -First 1\nif ($proxymanExe) { Start-Process $proxymanExe; Start-Sleep 10 }\n```\n\n### Linux\n\n```bash\nif command -v proxyman >/dev/null 2>&1; then\n  nohup proxyman >/dev/null 2>&1 &\nelse\n  nohup \"$HOME/Downloads/Proxyman.AppImage\" >/dev/null 2>&1 &\nfi\nsleep 10\n```\n\nAsk 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.\n\nIf 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.\n\nKeep \"Redact Sensitive Data Before Sending to AI\" enabled unless the user explicitly wants raw headers, cookies, query strings, or bodies sent to the agent.\n\nOn 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.\n\n## Step 3: Resolve The Bridge Executable\n\n### macOS\n\nRegular build:\n\n```bash\nBRIDGE_PATH=\"/Applications/Proxyman.app/Contents/MacOS/mcp-server\"\ntest -x \"$BRIDGE_PATH\" && echo \"$BRIDGE_PATH\"\n```\n\nIf the regular path is missing, search installed Proxyman apps:\n\n```bash\nmdfind 'kMDItemCFBundleIdentifier == \"com.proxyman.NSProxy\" || kMDItemCFBundleIdentifier == \"com.proxyman.NSProxy-setapp\"' |\nwhile read -r app; do\n  candidate=\"$app/Contents/MacOS/mcp-server\"\n  [ -x \"$candidate\" ] && echo \"$candidate\"\ndone\n```\n\n### Windows (PowerShell)\n\nThe Windows Electron app copies `mcp-server.exe` beside `Proxyman.exe`. If no bridge is found, use the exact command from Proxyman Settings > MCP.\n\n```powershell\n$exeCandidates = @(\n  \"$env:LOCALAPPDATA\\Programs\\Proxyman\\Proxyman.exe\",\n  \"C:\\Program Files\\Proxyman\\Proxyman.exe\",\n  \"C:\\Program Files (x86)\\Proxyman\\Proxyman.exe\"\n)\n$proxymanExe = $exeCandidates | Where-Object { Test-Path $_ } | Select-Object -First 1\n\n$bridgeCandidates = @()\nif ($proxymanExe) {\n  $bridgeCandidates += Join-Path (Split-Path $proxymanExe -Parent) \"mcp-server.exe\"\n}\n$bridgeCandidates += @(\n  \"$env:LOCALAPPDATA\\Programs\\Proxyman\\mcp-server.exe\",\n  \"C:\\Program Files\\Proxyman\\mcp-server.exe\",\n  \"C:\\Program Files (x86)\\Proxyman\\mcp-server.exe\"\n)\n\n$bridge = $bridgeCandidates | Where-Object { Test-Path $_ } | Select-Object -First 1\nif ($bridge) { $bridge } else { \"NOT_FOUND: copy the path from Proxyman Settings > MCP\" }\n```\n\n### Linux\n\nThe packaged Linux AppImage copies `mcp-server` into Proxyman's config folder after launch. Prefer that stable copied path.\n\n```bash\nCONFIG_HOME=\"${XDG_CONFIG_HOME:-$HOME/.config}\"\nBRIDGE_PATH=\"$CONFIG_HOME/Proxyman/bin/mcp-server\"\n\nif [ -x \"$BRIDGE_PATH\" ]; then\n  echo \"$BRIDGE_PATH\"\nelse\n  echo \"NOT_FOUND: launch Proxyman, enable Settings > MCP, restart Proxyman, or copy the path from Settings > MCP\"\nfi\n```\n\nSet `BRIDGE_PATH` to the chosen executable path. It must be the stdio bridge, not the Proxyman app binary.\n\n## Step 4: Detect The Agent Config\n\nUse environment variables first, then parent process, then filesystem markers.\n\n```bash\n[ -n \"$OPENAI_CODEX\" ] && echo \"codex\"\n[ -n \"$CLAUDE_CODE_ENTRYPOINT\" ] && echo \"claude-code\"\n[ -n \"$CURSOR_TRACE_ID\" ] || [ \"$TERM_PROGRAM\" = \"cursor\" ] && echo \"cursor\"\n[ -n \"$VSCODE_PID\" ] || [ \"$TERM_PROGRAM\" = \"vscode\" ] && echo \"vscode\"\n[ -n \"$GITHUB_COPILOT_CLI\" ] && echo \"copilot-cli\"\n```\n\nFallback markers:\n\n```bash\ntest -d \"$HOME/.codex\" && echo \"codex\"\ntest -d \"$HOME/.claude\" && echo \"claude-code\"\ntest -d \"$HOME/.cursor\" && echo \"cursor\"\ntest -d \".vscode\" && echo \"vscode\"\ntest -f \"$HOME/.copilot/mcp-config.json\" && echo \"copilot-cli\"\ntest -f \"$HOME/Library/Application Support/Claude/claude_desktop_config.json\" && echo \"claude-desktop\"\n```\n\nIf multiple agents are detected, ask the user which agent they want to configure.\n\n## Step 5: Add The MCP Server\n\n### Codex CLI\n\nPreferred command:\n\n```bash\ncodex mcp add proxyman -- \"$BRIDGE_PATH\"\n```\n\nEquivalent TOML:\n\n```toml\n[mcp_servers.proxyman]\nenabled = true\ncommand = \"BRIDGE_PATH\"\nargs = []\n```\n\nConfig file: `~/.codex/config.toml`.\n\n### Claude Code\n\n```bash\nclaude mcp add proxyman --transport stdio -- \"$BRIDGE_PATH\"\n```\n\nConfig file: `~/.claude.json`.\n\n### Claude Desktop\n\nConfig file:\n\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\nServer entry:\n\n```json\n{\n  \"mcpServers\": {\n    \"proxyman\": {\n      \"command\": \"BRIDGE_PATH\",\n      \"args\": [],\n      \"env\": {}\n    }\n  }\n}\n```\n\n### Cursor\n\nConfig file: `~/.cursor/mcp.json`.\n\n```json\n{\n  \"mcpServers\": {\n    \"proxyman\": {\n      \"command\": \"BRIDGE_PATH\",\n      \"args\": [],\n      \"env\": {}\n    }\n  }\n}\n```\n\n### VS Code / GitHub Copilot\n\nConfig file:\n\n- macOS: `~/Library/Application Support/Code/User/mcp.json` or workspace `.vscode/mcp.json`\n- Linux: `~/.config/Code/User/mcp.json` or workspace `.vscode/mcp.json`\n- Windows: `%APPDATA%\\Code\\User\\mcp.json` or workspace `.vscode\\mcp.json`\n\n```json\n{\n  \"servers\": {\n    \"proxyman\": {\n      \"command\": \"BRIDGE_PATH\",\n      \"args\": [],\n      \"env\": {}\n    }\n  }\n}\n```\n\n### GitHub Copilot CLI\n\nConfig file: `~/.copilot/mcp-config.json`.\n\n```json\n{\n  \"mcpServers\": {\n    \"proxyman\": {\n      \"command\": \"BRIDGE_PATH\",\n      \"args\": [],\n      \"env\": {},\n      \"tools\": [\"*\"]\n    }\n  }\n}\n```\n\nWhen editing JSON or TOML config manually, parse and merge with a real parser when possible. Never replace unrelated `mcpServers` or `servers` entries.\n\n## Step 6: Verify\n\nRestart or reload the agent after changing config.\n\nVerification sequence:\n\n1. Confirm Proxyman is running.\n2. Confirm Settings > MCP shows the server running.\n3. Ask the agent to list MCP tools/resources/prompts if it supports discovery.\n4. Call `get_version`.\n5. Call `get_proxy_status`.\n\nSuccessful setup means the agent can see Proxyman tools and `get_version` returns a Proxyman app/bridge response.\n\nTool 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.\n\n## Troubleshooting\n\n| Error | Meaning | Action |\n|-------|---------|--------|\n| `Proxyman is not running or MCP server not started` | Bridge cannot find `mcp-handshake.json`. | Launch Proxyman and enable Settings > MCP. |\n| `Invalid handshake file` | Token or port is stale. | Restart Proxyman, then reload the agent. |\n| `Cannot connect to Proxyman` | App is closed or MCP server stopped. | Open Proxyman and confirm MCP status. |\n| Linux bridge path is missing | The AppImage has not prepared `mcp-server` in the config folder yet. | Launch Proxyman, enable Settings > MCP, restart Proxyman, then check `${XDG_CONFIG_HOME:-$HOME/.config}/Proxyman/bin/mcp-server`. |\n| Agent has no Proxyman tools | Config path is wrong or agent was not reloaded. | Re-check `BRIDGE_PATH`, config file, and restart the agent. |\n| User sees no traffic after setup | MCP is connected but target capture is not configured. | Use `proxyman-https-capture`, then inspect with `proxyman-traffic-debugging`. |\n\n## Next Step\n\nOnce `get_version` and `get_proxy_status` work:\n\n- use `proxyman-traffic-debugging` for the complete MCP operation surface;\n- use `proxyman-https-capture` for device, emulator, browser, runtime, and framework routing/trust setup;\n- use `proxyman-debugging-tools` for current official feature documentation;\n- use `proxyman-cli` for version-matched shell automation.\n"
}