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

List tools/resources/prompts when the MCP client exposes discovery calls.
Use
```
get_version
```
to confirm the bridge can reach the app.
Use
```
get_proxy_status
```
to check recording state, proxy port, and SSL Proxying.
For setup questions, call
```
answer_setup_question
```
before inventing advice.
For traffic work, call
```
get_flows
```
or
```
filter_flows
```
, then use returned
```
flow_id
```
values with detail/export/code tools.
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"

"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

```
get_proxy_status
```

get_flows

with

limit

host_filter

method_filter

, or

status_filter

, or use

filter_flows

for body/header/status matching.

```
get_flow_detail
```
for a chosen
```
flow_id
```
.
Use
```
export_flow_curl
```
or
```
generate_code
```
only after confirming the flow is the one the user wants.
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

Ask for the feature, expected endpoint behavior, and approximate time window if the user has not provided it.
```
get_proxy_status
```
to confirm recording and proxy state.
Use
```
get_flows
```
or
```
filter_flows
```
to find relevant requests.
Group results by endpoint, method, status, timing, and request sequence.
Inspect representative
```
flow_id
```
values with
```
get_flow_detail
```
.
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

```
answer_setup_question
```
with the user's exact symptom and any platform/app hints.

Check

get_proxy_status

get_certificate_status

, and

get_ssl_proxying_list

If localhost is involved, prefer Reverse Proxy guidance or
```
create_reverse_proxy
```
.
If iOS plus VPN is involved, prefer Atlantis guidance.
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

```
get_flows
```
or
```
filter_flows
```
to locate the target request.
```
get_flow_detail
```
to confirm URL, method, body, and matched tools.
Use
```
create_map_local_from_flow
```
when the user wants to reuse the captured response exactly.
Use
```
create_map_local
```
only when the user provides or wants a literal custom response.
Use the appropriate inventory tool to verify the new rule and use
```
list_tool_status
```
to confirm its feature is enabled.

Manage Existing Rules

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.
Use the returned
```
id
```
; do not infer IDs from names.

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

For updates, omit fields that should stay unchanged. For GraphQL operation filters, an empty string or
```
null
```
clears the filter where supported.
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.
Only one Network Condition can be active at a time.

Configure An External Proxy

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

Write A Scripting Rule

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.

Use the canonical positional signatures exactly:

async function onRequest(context, url, request)

and

async function onResponse(context, url, request, response)

Generate only the handlers needed for the user's case.
```
onRequest
```
must end with
```
return request;
```
;
```
onResponse
```
must end with
```
return response;
```
.
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.
Never generate one-argument handlers such as
```
onRequest(request)
```
or
```
onResponse(response)
```
. Proxyman passes
```
context
```
first, so those handlers target the wrong object.
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

Use
```
create_compose_http
```
for a blank draft or
```
create_compose_http_from_flow
```
to seed from a captured flow.

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

Use
```
send_compose_http
```
to send the draft and receive the resulting captured flow summary/detail.
```
send_compose_http
```
is HTTP-only; WebSocket URLs are rejected.
Compose IDs are in-memory and ephemeral. Delete unused drafts with
```
delete_compose_http
```
.

Inspect WebSockets

```
list_websocket_sessions
```

get_websocket_messages

with

flow_id

direction: "all" | "client" | "server"

include_ping_pong

, and

include_payload

Payload previews are truncated to 4,096 characters and honor redaction.
```
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.

proxyman-traffic-debugging

NPX Install

Tags

SKILL.md Content

Proxyman Traffic Debugging And MCP Operations

Mental Model

First Calls In A Session

Privacy And Consent

Core Tool Groups

Common Workflows

Inspect Traffic

Verify A Feature From Traffic

Help A User Capture Missing Traffic

Create A Debugging Rule From Captured Traffic

Manage Existing Rules

Configure An External Proxy

Write A Scripting Rule

Compose And Replay An HTTP Request

Inspect WebSockets

Built-In Resources And Prompts

Troubleshooting