---
name: proxymanapp/proxyman-traffic-debugging
source: https://app.decimal.ai/s/proxymanapp-proxyman-traffic-debugging@1/SKILL.md
source_sha256: b5201d2d6d7c
---

# 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`.
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.