Proxyman Traffic Debugging

Proxyman Traffic Debugging And MCP Operations

Use this skill after Proxyman MCP is configured. It teaches the agent how to use Proxyman as a local MCP server for traffic debugging and full Proxyman operations.

If Proxyman MCP tools are not available, stop and use proxyman-mcp-setup. If Proxyman is not installed, use proxyman-download-setup.

Proxyman MCP is not a cloud API. MCP clients talk to the bundled mcp-server executable over stdio, and the bridge controls a running local Proxyman app.

Treat tools/list, resources/list, and prompts/list from the connected MCP server as the current source of truth when exact schemas or tool availability matter.

Mental Model

• MCP clients talk to the bundled mcp-server executable over stdio.
• The mcp-server bridge reads a local handshake file, then forwards requests to the running Proxyman app at http://127.0.0.1:<ephemeral-port>/mcp.
• The app's local HTTP server is localhost-only and authenticated with a bearer token from the handshake file.
• Do not hardcode the HTTP port or token. They are regenerated by the app and discovered from the handshake.
• Prefer the stdio MCP bridge over direct HTTP calls because the bridge adds schema validation, prompts, resources, annotations, structured content, and extra redaction safeguards.
• On Windows, the bridge is typically mcp-server.exe beside Proxyman.exe. On Linux AppImage builds, Proxyman prepares a stable bridge at ${XDG_CONFIG_HOME:-$HOME/.config}/Proxyman/bin/mcp-server after the app launches.
• Flow tools expose the app's active session/sidebar data source, including special sources such as Atlantis when selected, so results should match what the user sees in Proxyman.
• The tool list below is an orientation map. Use the live MCP schemas before sending calls, especially after Proxyman updates.

First Calls In A Session

1. List tools/resources/prompts when the MCP client exposes discovery calls. 2. Use get_version to confirm the bridge can reach the app. 3. Use get_proxy_status to check recording state, proxy port, and SSL Proxying. 4. For setup questions, call answer_setup_question before inventing advice. 5. For traffic work, call get_flows or filter_flows, then use returned flow_id values with detail/export/code tools. 6. For mutations, inspect current state first with the relevant list/status tool, then make the smallest requested change.

The stdio server uses strict schemas. Always obey tools/list; unknown parameters and invalid enum values are rejected as protocol errors.

Privacy And Consent

• Redaction is controlled in Proxyman Settings > MCP. When enabled, Proxyman redacts sensitive headers, cookies, query secrets, JWTs, bearer tokens, and common secret/password fields.
• Some outputs intentionally honor the app's privacy setting, such as flow detail, WebSocket payload previews, Compose drafts seeded from flows, and exported cURL.
• Ask before disabling redaction, exporting files, installing/uninstalling certificates, enabling system proxy, quitting Proxyman, clearing sessions, deleting rules, launching injected terminals, launching Electron apps, or running guided automations.
• export_flows requires an explicit user-approved save path. If the path is a directory, Proxyman auto-generates a filename.
• If the user asks for raw secrets, confirm that they understand redaction may need to be disabled in Proxyman Settings > MCP.

Core Tool Groups

Use this section to choose the right workflow quickly. Do not copy these names blindly; confirm current schemas and enum values from the connected MCP server.

Read-only inspection:

• get_version, get_proxy_status, get_flows, filter_flows, get_flow_detail
• list_websocket_sessions, get_websocket_messages
• list_rules, get_ssl_proxying_list, get_system_proxy_status
• get_certificate_status, get_external_proxy, list_tool_status

Capture setup and guidance:

• answer_setup_question for user-specific setup advice with diagnosis, steps, verification, citations, and next actions.
• search_docs, list_setup_workflows, list_popular_workflows
• open_proxyman_screen for app guide screens.
• run_guided_setup for safe built-in automations: Chrome current profile, Chrome new profile, Firefox, Android emulator override/revert.

Session and proxy control:

• toggle_recording, clear_session
• get_system_proxy_status, set_system_proxy
• enable_ssl_proxying, disable_ssl_proxying, toggle_ssl_proxying_domain
• install_certificate, uninstall_certificate

Rule management:

• create_breakpoint, create_map_local, create_map_local_from_flow, create_map_remote, create_blacklist
• create_scripting_rule, create_allow_list, create_network_condition, create_dns_spoofing, create_reverse_proxy
• list_rules, delete_rule, toggle_rule
• update_breakpoint, update_map_local, update_map_remote, update_blacklist, update_scripting_rule, update_allow_list, update_network_condition, update_dns_spoofing, update_reverse_proxy
• toggle_tool toggles whole features such as breakpoint, map_local, map_remote, blacklist, scripting, dns_spoofing, network_throttling, whitelist, reverse_proxy, no_caching, and external_proxy.

Flow operations:

• export_flow_curl
• export_flows with format: "har" or "proxymanlogv2"
• generate_code with targets such as curl, python, swift_urlsession, swift_alamofire, go, node_fetch, axios, kotlin_okhttp, java_httpclient, dart, php_guzzle, rust_reqwest, httpie, har, postman, and swift_moya.

Compose and WebSocket:

• create_compose_http, create_compose_http_from_flow, get_compose_http, update_compose_http, send_compose_http, delete_compose_http
• list_websocket_sessions, get_websocket_messages, close_websocket_session

Runtime/app injection:

• inject_terminal, get_terminal_manual_command
• inject_electron

App control:

• open_proxyman can launch regular or Setapp Proxyman if installed. Wait briefly, then retry get_version.
• quit_proxyman quits the local app and should be treated as destructive.

Common Workflows

When a workflow mutates Proxyman state, explain what will change before calling the tool.

Inspect Traffic

1. get_proxy_status 2. get_flows with limit, host_filter, method_filter, or status_filter, or use filter_flows for body/header/status matching. 3. get_flow_detail for a chosen flow_id. 4. Use export_flow_curl or generate_code only after confirming the flow is the one the user wants.

Verify A Feature From Traffic

1. Ask for the feature, expected endpoint behavior, and approximate time window if the user has not provided it. 2. get_proxy_status to confirm recording and proxy state. 3. Use get_flows or filter_flows to find relevant requests. 4. Group results by endpoint, method, status, timing, and request sequence. 5. Inspect representative flow_id values with get_flow_detail. 6. Report a verdict: passed, suspicious, failed, or inconclusive.

Recommended report shape:

Feature Traffic Report

Verdict: ...
Traffic window: ...
Endpoint summary: ...
Evidence: ...
Possible issues: ...
Next action: ...

Help A User Capture Missing Traffic

1. answer_setup_question with the user's exact symptom and any platform/app hints. 2. Check get_proxy_status, get_certificate_status, and get_ssl_proxying_list. 3. If localhost is involved, prefer Reverse Proxy guidance or create_reverse_proxy. 4. If iOS plus VPN is involved, prefer Atlantis guidance. 5. If a browser, Android emulator, or terminal automation is offered, ask before run_guided_setup or inject_terminal.

Create A Debugging Rule From Captured Traffic

1. get_flows or filter_flows to locate the target request. 2. get_flow_detail to confirm URL, method, body, and matched tools. 3. Use create_map_local_from_flow when the user wants to reuse the captured response exactly. 4. Use create_map_local only when the user provides or wants a literal custom response. 5. Use list_rules to verify the new rule ID and enabled state.

Manage Existing Rules

1. list_rules with rule_type when possible. 2. Use the returned id; do not infer IDs from names. 3. For delete_rule and toggle_rule, pass the exact rule_type. Common values are breakpoint, maplocal, mapremote, blacklist, scripting, whitelist, reverse_proxy, network_condition, and dns_spoofing. 4. For updates, omit fields that should stay unchanged. For GraphQL operation filters, an empty string or null clears the filter where supported.

Write A Scripting Rule

1. Read docs://scripting/snippet-code or use the write_scripting_rule prompt. 2. Generate only the script needed for the user's case. 3. onRequest() must return request; onResponse() must return response. 4. The bridge validates return statements and rejects scripts that would silently fail.

Compose And Replay An HTTP Request

1. Use create_compose_http for a blank draft or create_compose_http_from_flow to seed from a captured flow. 2. Use update_compose_http with method, url, headers: [{ "key": "...", "value": "..." }], and UTF-8 body_text. 3. Use send_compose_http to send the draft and receive the resulting captured flow summary/detail. 4. send_compose_http is HTTP-only; WebSocket URLs are rejected. 5. Delete unused drafts with delete_compose_http.

Inspect WebSockets

1. list_websocket_sessions 2. get_websocket_messages with flow_id, direction: "all" | "client" | "server", include_ping_pong, and include_payload. 3. Payload previews are truncated and honor redaction. 4. close_websocket_session only supports active Compose-created WebSocket sessions.

Built-In Resources And Prompts

Use built-in resources and prompts for Proxyman-specific setup and scripting guidance before reaching for generic web advice.

Resources:

• docs://setup/ios-device
• docs://setup/ios-simulator
• docs://setup/android-device
• docs://setup/android-emulator
• docs://setup/tvos-watchos
• docs://setup/automatic-setup
• docs://setup/manual-setup
• docs://setup/firefox
• docs://setup/atlantis
• docs://troubleshooting/vpn
• docs://troubleshooting/localhost
• docs://troubleshooting/third-party-libraries
• docs://scripting/snippet-code
• insights://popular-workflows
• Resource template: docs://search/{query}

Prompts:

• recommend_capture_path
• troubleshoot_missing_traffic
• explain_vpn_or_atlantis_choice
• write_scripting_rule

These resources/prompts are curated to match the app's own automation paths.

Troubleshooting

• "Handshake file not found": Proxyman is not running, MCP is disabled, or the app has not finished startup. Launch Proxyman and enable Settings > MCP.
• "Invalid handshake file" or HTTP 401: restart Proxyman so the bridge gets the current token.
• "Cannot connect to Proxyman": confirm the app is open and the MCP status shows "Running on port ...".
• Linux AppImage bridge missing: launch Proxyman once, enable Settings > MCP, restart the app, then use the copied bridge from ${XDG_CONFIG_HOME:-$HOME/.config}/Proxyman/bin/mcp-server.
• No flows appear: check recording, target proxy settings, certificate trust, SSL Proxying, and whether the active Proxyman sidebar/session source is the expected one.
• HTTPS bodies are opaque: check get_certificate_status and get_ssl_proxying_list, then enable SSL Proxying for the host.
• Localhost is missing: use Reverse Proxy; many localhost calls bypass the system proxy path.
• VPN blocks capture: for iOS apps, recommend Atlantis before fighting the device proxy path.
• Browser or terminal automation fails: macOS Automation permission may be missing. Ask the user to allow Proxyman in System Settings > Privacy & Security > Automation.
• Certificate install in automatic mode can trigger a macOS sudo dialog; manual mode opens Keychain Access for user trust steps.
• Flow IDs can disappear after clear_session, source changes, app restart, or import/session changes. List flows again before retrying.