proxyman-traffic-debugging

name

proxyman-traffic-debugging

description

Use Proxyman MCP to inspect and debug captured HTTP/HTTPS/WebSocket traffic and operate Proxyman through all MCP actions. Use this skill when an agent needs to analyze traffic, diagnose missing capture, manage rules, use Compose, inspect WebSockets, install certificates, control proxy settings, use setup guidance, export flows, generate code, run Proxyman automations, or troubleshoot Proxyman MCP.

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 Atlantis, saved requests, pinned flows, imported sessions, and remote folders when selected, so results should match what the user sees in Proxyman.
• set_system_proxy, Terminal injection, .app Electron injection, and bridge app-control tools are macOS-oriented. On another platform, rely on the live tool list and schemas before offering them.
• 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.
• Flow summaries/details, WebSocket payload previews, Compose drafts/results, exported cURL, and generated code honor the app's privacy setting.
• export_flows writes original captured data to HAR or ProxymanLogv2 on disk. The file contents are not redacted by the MCP preview setting.
• Ask before disabling redaction, exporting files, installing/uninstalling certificates, enabling system proxy, quitting Proxyman, clearing sessions, deleting rules, launching injected terminals, launching Electron apps, running guided automations, or sending upstream-proxy credentials.
• 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, list_reverse_proxies, list_network_conditions, list_dns_spoofing
• 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
• SSL Proxying domain parameters accept exact hosts and wildcard patterns such as *.example.com. Use the exact same pattern when disabling or toggling a wildcard rule, then verify the result with get_ssl_proxying_list.
• install_certificate, uninstall_certificate
• get_external_proxy, set_external_proxy
• toggle_no_caching changes the No Caching feature directly; toggle_tool can also set its global state.

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
• Use list_reverse_proxies, list_network_conditions, and list_dns_spoofing for those feature-specific IDs and details. list_rules does not return Reverse Proxy entries.
• 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.
• Successful MCP rule CRUD, rule toggles, and feature toggles refresh open Proxyman tool lists and rule editors automatically. Deleting a rule that is currently being edited closes that editor.
• Update commands preserve the rule ID. Continue using the original ID for later toggle, update, or delete calls.
• Rule method fields accept QUERY alongside the established HTTP methods. Use uppercase "QUERY" for an exact RFC 10008 rule; use "ANY" only when the rule should also affect other methods.
• Set include_paths explicitly when matching scope matters. Defaults mirror each GUI and differ across rule types.
• Creating Scripting, Allow List, Network Condition, DNS Spoofing, or Reverse Proxy entries auto-enables that feature. Other rule creation may leave the global feature disabled; verify with list_tool_status.

Flow operations:

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

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.
5. Treat flow results as recent snapshots: list/filter results cap at 500 and body previews are truncated. Request an approved file export only when the user needs complete archival data.

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 the appropriate inventory tool to verify the new rule and use list_tool_status to confirm its feature is enabled.

Manage Existing Rules

1. Use list_rules for matching rules, list_reverse_proxies for Reverse Proxy, list_network_conditions for Network Condition, and list_dns_spoofing for DNS Spoofing.
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.
5. Exception: when changing a Map Local literal response, pass response_body, status_code, and content_type together because the response file is rebuilt with defaults for omitted response fields.
6. Only one Network Condition can be active at a time.

Configure An External Proxy

1. Use get_external_proxy and identify the http, https, socks, or pac setting to change.
2. Ask before sending credentials.
3. Use set_external_proxy with a complete setting for that kind. Omitted host, port, enabled, or authentication values are not patch-preserved reliably.
4. Call get_external_proxy again to verify the global feature and protocol setting.

Write A Scripting Rule

1. Read docs://scripting/snippet-code before generating non-trivial script_content, or use the write_scripting_rule prompt when the client exposes MCP prompts. Do not rely on generic proxy scripting syntax.
2. Use the canonical positional signatures exactly: async function onRequest(context, url, request) and async function onResponse(context, url, request, response).
3. Generate only the handlers needed for the user's case. onRequest must end with return request;; onResponse must end with return response;.
4. Request and response headers are mutable key-value objects. Use response.statusCode for an HTTP status code and consult the resource for body types and less common fields.
5. Never generate one-argument handlers such as onRequest(request) or onResponse(response). Proxyman passes context first, so those handlers target the wrong object.
6. The app validates JavaScript syntax, handler arity/order, and final return values before creating or updating a Scripting rule. Fix the actionable tool error and retry rather than weakening the script.

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. method: "QUERY" is supported and can be sent with 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. Compose IDs are in-memory and ephemeral. 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 to 4,096 characters 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.
• Android emulator automation also needs an available root certificate path and local IPv4 address. Check certificate status before retrying it.
• Do not offer macOS-only system proxy, Terminal, Electron .app, or app-control operations on another platform unless the live MCP server exposes an applicable schema.
• 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.