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:

text
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.

1. Use send_compose_http to send the draft and receive the resulting captured flow summary/detail.
2. send_compose_http is HTTP-only; WebSocket URLs are rejected.
3. 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.