Proxyman

View saved version →

---
name: "proxyman-app-settings"
description: "Inspect, explain, audit, and safely change Proxyman macOS App Settings. Use when a user asks where a preference lives, what it does, why it is locked or ineffective, or requests a settings change or review. Do not use for individual debugging-tool rules."
---

# Proxyman App Settings

Guide the current Proxyman macOS Settings window without treating every preference as an MCP or CLI operation.

## Select The Relevant Reference

- Read [General, Appearance, and Privacy](references/general-appearance-privacy.md) for certificates, proxy port/startup behavior, layout, theme/editor display, analytics, or crash reporting.
- Read [Workspace, Tools, and Integrations](references/workspace-tools-integrations.md) for Team Workspace, Map Local/Scripting defaults, copy/export preferences, GitHub Gist, Products, or MCP.
- Read [Advanced](references/advanced.md) for the Proxy Helper Tool, time format, window/resource behavior, update notifications, proxy restoration, or app language.

Read more than one reference only when the request spans those tabs.

## Establish The Actual UI

This skill's bundled catalog is a reviewed macOS snapshot. Before giving exact current instructions:

1. Identify the installed Proxyman version, distribution, and platform when available.
2. Open the Settings window and use its visible tab/control names as the authority for that build.
3. When product behavior or documentation may have changed, fetch `https://docs.proxyman.com/llms.txt`, follow the selected `.md` link, and cite the corresponding public page. Do not invent a documentation URL.
4. Account for build differences. The reviewed Setapp build omits Workspace and changes some Products destinations.

Do not claim the Windows or Linux Settings UI matches this macOS catalog unless the installed build confirms it.

## Handle A Settings Request

1. Restate the desired outcome and identify the owning tab and control.
2. Read the current value before changing it. For audits, report current, recommended target, consequence, and any restart requirement separately.
3. Check whether the control is unavailable because of license, build, organization/CLI policy, current certificate state, or a genuinely disabled/coming-soon implementation.
4. Explain material side effects before the change. Obtain confirmation immediately before certificate/private-key export or deletion, trust-store changes, helper-tool install/removal, GitHub authorization/removal, public sharing, disabling AI redaction, or exposing script environment variables.
5. Apply only the requested setting through the interface actually exposed by the installed build.
6. Verify by reopening the tab or observing the independent effect described in the relevant reference. A click or saved checkbox alone is not sufficient when runtime behavior is testable.
7. State how to restore the previous value. Record the prior value first when a change affects routing, trust, external sharing, or privacy.

Ordinary reversible display preferences do not need extra confirmation when the user already asked for the change.

## Interface Boundary

The reviewed MCP server has no generic read/write API for App Settings. Use the GUI as the canonical interface unless a specialized overlap exists:

- MCP can inspect/install/uninstall the generated root certificate, but it does not expose every General certificate action.
- MCP can read system/proxy status and change current system-proxy or External Proxy state, but those are not substitutes for startup preferences or arbitrary proxy-port editing.
- `proxyman-cli mcp on|off` controls the MCP organization/CLI lock and persisted server state; discover installed help before use.
- `proxyman-cli export` and `import` operate only on the configuration scope documented by the installed command. Do not assume they serialize every tab.
- Most Appearance, Privacy, Workspace, Tools, GitHub, Products, and Advanced preferences are GUI-only in the reviewed interfaces.

Route generated/custom certificate lifecycle, Debug Mode, Reset Network Proxy, and Factory Reset to `proxyman-certificates-recovery`; live traffic/rule operations to `proxyman-traffic-debugging`; exact shell automation to `proxyman-cli`; MCP client connection work to `proxyman-mcp-setup`; and per-rule feature guidance to `proxyman-debugging-tools`.

## Response Shape

For guidance or an audit, report:

```text
Tab > control
Current state (if observed)
What it changes
How to change it
How to verify
Restart / license / build limitation
Risk and rollback (when material)
Official docs (when available)
```

Say when no dedicated public documentation exists; use the installed UI and reviewed source behavior instead of stretching an unrelated page into evidence.

Referenced files: 4

View saved version →

---
name: "proxyman-certificates-recovery"
description: "Safely manage Proxyman certificates and destructive recovery workflows on macOS. Use for generated or custom root certificates, custom server or client certificates, Copy Debug Info, Debug Mode, Reset Network Proxy, or Factory Reset. Do not use for ordinary display preferences or device-specific CA setup."
---

# Proxyman Certificates And Recovery

Keep certificate roles, trust, diagnostics, and reset scope separate. These operations can change the macOS trust store, disclose private-key material, interrupt live TLS connections, or delete Proxyman data.

## Select The Relevant Reference

- Read [Root certificates](references/root-certificates.md) for the generated Proxyman CA, automatic/manual trust, custom root import, replacement, removal, MCP, or CLI boundaries.
- Read [Custom server and client certificates](references/custom-server-client-certificates.md) for TLS-to-client certificates, mTLS client identity, PEM/DER/P12 imports, host/port matching, replacement, or CLI automation.
- Read [Diagnostics and recovery](references/diagnostics-and-recovery.md) for Copy Debug Info, Debug Mode, Reset Network Proxy, data/backup folders, or Factory Reset.

Read more than one reference only when the task crosses those boundaries.

## Establish Current Behavior

1. Identify the installed Proxyman version, distribution, and whether the task is GUI, MCP, or CLI driven.
2. Fetch `https://docs.proxyman.com/llms.txt` when current behavior matters, then fetch the selected official `.md` page and cite its public URL.
3. Use the installed UI, live MCP schema, or installed `proxyman-cli --help` as the exact interface authority. The bundled references are a reviewed macOS snapshot.
4. If no dedicated public page exists for Debug Mode or Factory Reset, say so and use the installed Help menu plus the source-grounded behavior in this skill.

Do not generalize this macOS trust/Keychain workflow to Windows, Linux, mobile devices, simulators, Java, Firefox, or containers. Route target-specific trust setup to `proxyman-https-capture`.

## Classify Before Acting

- **Generated Proxyman root CA:** Proxyman generates the signing identity used for ordinary HTTPS interception; install and trust it on the current Mac.
- **Custom root CA:** replaces the generated signing identity inside Proxyman and must include its private key.
- **Custom server certificate:** Proxyman presents it to matching clients based on certificate names; it is not an upstream mTLS identity.
- **Custom client certificate:** Proxyman presents it to one configured upstream host and port for mutual TLS.
- **Debug Mode:** increases production console diagnostics; it is not a reset and does not export a support bundle.
- **Factory Reset:** removes certificates and preferences, with an optional broader deletion of app-managed data including rules and backups.

If the user says only “add a certificate,” ask which TLS direction and goal. Choosing the wrong role can break handshakes or widen trust unnecessarily.

## Safe Operating Workflow

1. Inspect current certificate/status/rule state and record the exact item being changed.
2. Pause or finish important captures before any custom-certificate mutation; the reviewed app closes live connections when custom certificate state changes.
3. Preserve recoverable inputs outside Proxyman-managed folders: original certificate/key files, passwords in the user's approved secret store, relevant debugging-rule exports, and any required logs/backups.
4. Explain the exact trust, routing, secret, interruption, or deletion effect.
5. Obtain confirmation immediately before a privileged trust-store change, certificate/private-key import or deletion, Reset Network Proxy, or Factory Reset. For Debug Mode, an explicit request to enable it is sufficient; agree on the reproduction and log-sharing scope before launching the app from Terminal or sharing output.
6. Make one scoped change. Do not retry a password/sudo/Keychain failure repeatedly; inspect the resulting partial state first.
7. Verify through an independent status and a fresh controlled TLS connection or post-relaunch state.
8. Restore the prior certificate/configuration or disable diagnostics after the requested result is captured.

## Interface Boundary

- GUI is the complete reviewed interface for generated and custom certificates, Debug Mode, and Factory Reset.
- MCP can inspect current root status, generate/install the default Proxyman CA, and remove the current managed root. It cannot import or CRUD custom root/server/client certificates or invoke Debug Mode/Factory Reset.
- `proxyman-cli install-root-cert` imports a custom P12 root; `custom-cert` manages P12 server/client certificates. Discover version-matched help before constructing commands.
- Reviewed GUI supports PEM/DER certificate plus matching private key or P12 for server/client certificates. Reviewed CLI supports P12 only.
- Factory Reset and Debug Mode are GUI-only. Never emulate Factory Reset by recursively deleting Application Support or Keychain content.
- `proxyman-cli export` backs up debugging-tool rules only. It is not a backup of App Settings, certificates/private keys, captured sessions, license state, or Proxyman's backup folder.

Route ordinary Settings-tab questions to `proxyman-app-settings`, capture/trust on another target to `proxyman-https-capture`, and exact CLI execution to `proxyman-cli`.

## Sensitive Data Rules

- Never read, paste, or retain a private key, P12 payload, passphrase, sudo password, Keychain token, captured TLS secret, or full console log unless the user explicitly approves the exact exposure.
- Prefer GUI password prompts. The reviewed CLI accepts certificate passwords as arguments, which can expose them through shell history or process inspection; provide placeholders for user-run commands rather than receiving the real secret.
- Import only certificates the user owns or is authorized to use. A custom server certificate does not authorize bypassing pinning in a third-party production app.
- Preview debug information and console logs before copying or sharing them with support.

Referenced files: 4

View saved version →

---
name: "proxyman-cli"
description: "Discover and safely use the installed proxyman-cli for proxy control, MCP state, licenses, configuration, logs, certificates, rules, and debugging-tool automation. Use for Proxyman shell commands, scripts, CLI help, or operations that MCP does not execute."
---

# Proxyman CLI

Use the CLI installed with the user's Proxyman build. Never assume a command hierarchy or flags from static documentation.

## Discover Version-Matched Syntax

If Proxyman MCP is connected:

1. Call `get_proxyman_cli_help` with an empty command path for top-level help.
2. Call it again with command names only, for example `export-log` or `rules map-local create`.
3. Never include flags, values, pipes, redirects, or shell syntax in `command_path`.
4. Use the returned syntax, then execute an authorized operational command through the agent host's shell. The MCP helper never performs the command. If the command's only supported secret input is an argument, as with the reviewed `activate` command, provide a placeholder command for the user to run instead.

If MCP is unavailable:

1. Resolve the actual executable without changing shell profiles.
2. Run that executable with `--help`.
3. Run nested `--help` until every required argument and option is known.
4. If the CLI is missing, route to app installation/update or the GUI; do not substitute guessed syntax.

The official command-line page is useful background, but installed help wins for exact syntax. Read [command catalog](references/command-catalog.md) to choose a hierarchy, then discover it live.

## Plan Before Execution

1. Translate the user's intent to one command hierarchy.
2. Inspect current state through MCP, CLI list/get, or the GUI when possible.
3. Classify the command:
   - read-only: help, list, get, status;
   - filesystem write: export and export-log; use an explicit destination and confirm before overwriting an existing file;
   - reversible mutation: on/off, enable/disable, create/update;
   - destructive/sensitive: unlink, delete/remove, clear, override import, root/custom certificate changes, credential-bearing operations.
4. Show the command shape with secrets replaced by placeholders.
5. Obtain confirmation for destructive actions or newly requested system/trust/proxy changes.
6. Execute once, capture exit status, stdout, and stderr, and redact secrets.
7. Verify state with a separate status/list/get operation.

## Safety Rules

- Never invent flags or rely on a command example without checking the installed help.
- Never expose a license key, certificate password, proxy credential, cookie, token, or captured secret in output.
- Prefer GUI license entry. The reviewed `activate` command accepts the key only as an argument, which can expose it in shell history, process listings, and an agent tool call.
- Never execute the positional-argument `activate` form with a real key through the agent host. Provide a version-matched command shape with `<LICENSE_KEY>` for the user to substitute and run directly in their own terminal.
- Avoid embedding certificate passwords in committed scripts or reusable shell history. Use the safest input mechanism supported by current help.
- Treat `activate`, `unlink`, `clear-session`, rule delete/remove, configuration import with override, custom/root certificate changes, and proxy routing changes according to their real effect.
- Do not run a generated shell command merely because MCP returned help. The user request and confirmation still control execution.
- Use explicit file paths. Verify output paths before exports and input paths before imports/certificate operations.
- Do not modify shell profiles to make the executable discoverable unless the user specifically asks.

## Major Command Families

The installed build may expose:

- license: `activate`, `unlink`;
- application state: `proxy`, `proxy-host`, `mcp`, `clear-session`;
- configuration: `export`, `import`;
- logs: `export-log`;
- certificates: `custom-cert`, `install-root-cert`;
- debugging tools: Breakpoint, Map Local, Map Remote, Scripting, Block List, Allow List, Reverse Proxy, Network Condition, No Caching, DNS Spoofing, External Proxy;
- unified rule operations under `rules`.

Treat this as routing, not syntax. Read [rule automation](references/rule-automation.md) for the rule workflow.

## Important Workflows

### MCP Server State

Use the version-matched `mcp on`/`mcp off` hierarchy when the user wants to persistently enable or disable Proxyman's MCP server, including when the app is closed. Reload the MCP client after enabling and launch Proxyman before expecting operational tools.

### License Activation

Discover `activate --help`, but do not ask the user for the key and do not execute the reviewed positional-argument form through the agent host. Provide a command shape with `<LICENSE_KEY>` for the user to run directly. After a successful activation, have the user restart Proxyman before verifying the licensed state; do not quit the app without explicit authorization.

### Export Logs Or Configuration

1. Discover output formats, filters, flow-boundary options, and path rules.
2. Resolve the destination explicitly and avoid overwriting unless the user requested it.
3. Warn that captured logs may contain unredacted secrets.
4. Verify the resulting file exists and report its path and size, not its secret contents.

### Import Configuration

1. Validate the source path and discover merge/override semantics.
2. Explain whether existing configuration will be preserved or replaced.
3. Require confirmation for override/replacement.
4. Verify resulting rule inventories.

### Certificates

Differentiate the default Proxyman CA from importing a custom root or server/client certificate. Discover the relevant subcommand, certificate type, password handling, and trust option. Obtain confirmation before changing any trust store.

## Result Format

Report:

```text
Executable/version:
Command hierarchy:
Action:
Exit status:
Sanitized output:
Verification:
Rollback or next step:
```

If execution was not authorized or possible, provide the verified command shape with placeholders and state exactly what remains for the user.

Referenced files: 3

View saved version →

---
name: "proxyman-debugging-tools"
description: "Find and explain current Proxyman debugging tools using official documentation, with GUI, MCP, and CLI workflows where supported. Use for Breakpoint, Map Local or Remote, Scripting, Compose, Repeat, Protobuf, TLS Key Logging, Reverse Proxy, Network Conditions, WebSocket, filters, exports, certificates, and other Proxyman feature guides."
---

# Proxyman Debugging Tools And Documentation

Use official Proxyman documentation to teach or plan a debugging workflow. This skill is documentation-first: it does not assume that a similarly named MCP or CLI action exists.

Use `proxyman-traffic-debugging` when the main task is to operate MCP now. Use `proxyman-app-settings` for a Settings-tab audit or preference change, `proxyman-certificates-recovery` for local root/custom certificate lifecycle or Help-menu Debug Mode/Factory Reset, `proxyman-https-capture` for device/runtime capture configuration, `proxyman-cli` for shell automation, and `proxyman-license-management` for licensing.

## Get The Current Documentation

For every task where current behavior matters:

1. Fetch `https://docs.proxyman.com/llms.txt`.
2. Match the user's feature or symptom to one or more official `.md` entries.
3. Fetch the selected `.md` page directly. Do not reconstruct a page path from memory when the index provides it.
4. Cite the public HTML URL by removing only the final `.md` from the fetched URL.
5. If the page links a prerequisite or troubleshooting page that materially changes the steps, fetch that page too.

Use official Proxyman-owned domains `docs.proxyman.com`, `docs.proxyman.io`, `proxyman.com`, `proxyman.io`, and the live Proxyman MCP server as authorities. A freshly fetched official page may link to an external destination, but treat that destination as authoritative only for its own product or service unless the user asks for third-party guidance.

If internet access is unavailable, say that the latest page could not be verified. You may use the bundled [debugging tool index](references/debugging-tool-index.md) as a navigation fallback, but label it as a snapshot.

## Understand Built-In MCP Documentation

`search_docs`, `answer_setup_question`, `docs://search/{query}`, and the static MCP resources search Proxyman's bundled **setup and troubleshooting** knowledge base. They are version-matched and ideal for capture diagnosis, but they do not represent the full `docs.proxyman.com` catalog.

For a product-wide feature question, fetch the public index even if `search_docs` returns a result. For exact MCP inputs, trust `tools/list`, not the public MCP page or this skill.

## Build The Answer Or Guide

1. Identify the user's goal, target traffic, platform, and whether they want explanation, GUI steps, MCP execution, or CLI automation.
2. Read the current official page and extract prerequisites, supported platforms, limits, and verification behavior.
3. Inspect [debugging tool index](references/debugging-tool-index.md) to map the feature to interfaces.
   - For Breakpoint, Map Local, Map Remote, Scripting, or interaction among those rules, read [request and response modification](references/request-response-modification.md).
   - For Compose or Repeat, Network Conditions, or Reverse Proxy, read [replay and routing workflows](references/replay-and-routing.md).
   - For Protobuf or TLS Key Logging, read [protocol decoding and key logging](references/protocol-decoding-and-key-logging.md).
4. Present only supported routes:
   - **GUI:** menu/screen and ordered user steps from the current page.
   - **MCP:** current tool names, discovery requirement, state read, mutation, and verification.
   - **CLI:** route to `proxyman-cli`; discover installed help before giving exact flags.
5. Include a concrete verification: expected flow, rule inventory, status field, response change, or exported artifact.
6. Include rollback for persistent rules, proxy changes, certificate trust, or capture automation.

If the docs describe a GUI-only feature, say so. Do not invent MCP/CLI parity.

## Guide Shape

Use this compact structure:

```text
Goal
Prerequisites
GUI steps
MCP steps (if exposed)
CLI steps (if exposed)
How to verify
How to undo
Limits / platform notes
Official docs
```

Skip empty interface sections rather than padding the answer.

## Safety

- Start with read-only discovery and traffic inspection.
- Obtain confirmation before changing proxy routing, trust stores, global tool state, external proxy credentials, or other applications.
- Obtain confirmation immediately before deletes, session clearing, certificate uninstall, destructive imports, or irreversible portal actions.
- Keep MCP redaction enabled. Warn that exported original traffic is not sanitized by MCP preview redaction.
- Never paste license keys, TLS session-key logs, tokens, passwords, cookies, or captured secrets into a guide or tool input unless the user explicitly requires it and understands the exposure.
- Do not claim a page is current unless it was fetched during this task.

## Coverage

The reference maps capture/view/filter tools, Repeat/Compose, Breakpoint, Map Local/Remote, Block/Allow List, Scripting, No Caching, External/Reverse/SOCKS proxy, SSL Proxying, certificates, WebSocket, Protobuf/GraphQL, Network Conditions, DNS Spoofing, exports, code generation, diff, OpenAPI, TLS Key Logging, and adjacent GUI tools.

When a current index adds a new debugging page, use it even if it is absent from the snapshot, then state which interfaces the live product exposes.

Referenced files: 5

View saved version →

---
name: "proxyman-download-setup"
description: "Download, install, launch, and prepare Proxyman on macOS, Windows, or Linux. Use when Proxyman is absent or the user asks to install, download, start, or prepare Proxyman before MCP configuration."
---

# Proxyman Download & Setup

Guide the user through installing and launching Proxyman. This skill is shell-first because Proxyman and its MCP tools may not be available yet.

## Operating Rules

1. Do not use Proxyman MCP tools until Proxyman is installed, launched, and MCP is configured.
2. Do not hardcode app versions. Use Proxyman's latest release redirects.
3. On Windows, prefer PowerShell. If the active shell is not PowerShell, wrap PowerShell snippets with `powershell.exe -Command '...'`.
4. Only install the macOS Helper Tool when system proxy automation is needed or the user asks for it.
5. Only install a root certificate when the user needs HTTPS decryption. Basic HTTP capture and app installation do not require certificate installation.
6. On Windows and Linux, launch Proxyman at least once before MCP setup so the app can expose or prepare the bundled MCP bridge.

## Phase 1: Check Existing Installation

### macOS

```bash
if [ -d "/Applications/Proxyman.app" ]; then
  VERSION=$(/usr/libexec/PlistBuddy -c "Print CFBundleShortVersionString" "/Applications/Proxyman.app/Contents/Info.plist" 2>/dev/null)
  echo "INSTALLED: ${VERSION:-unknown}"
elif mdfind 'kMDItemCFBundleIdentifier == "com.proxyman.NSProxy"' | grep -q "Proxyman.app"; then
  echo "INSTALLED: found via Spotlight"
else
  echo "NOT_INSTALLED"
fi
```

### Windows (PowerShell)

```powershell
$installed = Get-ItemProperty `
  "HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\*",
  "HKCU:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\*",
  "HKLM:\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall\*" `
  -ErrorAction SilentlyContinue |
  Where-Object { $_.DisplayName -like "*Proxyman*" }

if ($installed) {
  Write-Host "INSTALLED: $($installed.DisplayVersion)"
} else {
  Write-Host "NOT_INSTALLED"
}
```

### Linux

```bash
if command -v proxyman >/dev/null 2>&1; then
  echo "INSTALLED: $(command -v proxyman)"
elif ls "$HOME"/Downloads/Proxyman*.AppImage "$HOME"/Downloads/proxyman*.AppImage >/dev/null 2>&1; then
  echo "INSTALLED: AppImage in Downloads"
else
  echo "NOT_INSTALLED"
fi
```

If Proxyman is already installed, launch it and continue to preparation. If the user needs the latest build, download using the platform redirect below.

## Phase 2: Download And Install

### macOS: Homebrew Preferred

If Homebrew is installed, use the cask:

```bash
brew install --cask proxyman
```

If Homebrew is unavailable or the user prefers a direct download, use the latest DMG redirect:

```bash
curl -L "https://proxyman.com/release/osx/Proxyman_latest.dmg" -o "$HOME/Downloads/Proxyman.dmg"
hdiutil attach "$HOME/Downloads/Proxyman.dmg" -nobrowse
cp -R "/Volumes/Proxyman/Proxyman.app" /Applications/
hdiutil detach "/Volumes/Proxyman"
```

If the volume name differs, list attached volumes and copy from the mounted Proxyman volume:

```bash
ls /Volumes
```

### Windows

The Windows endpoint name ends in `.dmg` for legacy reasons, but it redirects to the latest Windows installer.
The installer is an NSIS one-click installer and normally launches Proxyman after completion.

```powershell
$installer = "$env:USERPROFILE\Downloads\ProxymanSetup.exe"
Invoke-WebRequest "https://proxyman.com/release/windows/Proxyman_latest.dmg" -OutFile $installer -MaximumRedirection 5
Start-Process $installer -ArgumentList "/S" -Wait
```

If silent installation fails, run the installer interactively:

```powershell
Start-Process $installer -Wait
```

### Linux

Download the latest AppImage redirect, make it executable, and launch it:

```bash
curl -L "https://proxyman.com/release/linux/proxyman_latest" -o "$HOME/Downloads/Proxyman.AppImage"
chmod +x "$HOME/Downloads/Proxyman.AppImage"
nohup "$HOME/Downloads/Proxyman.AppImage" >/dev/null 2>&1 &
```

The packaged Linux app prepares its MCP bridge on first launch. After Proxyman has opened, the stable bridge path should be:

```bash
BRIDGE_PATH="${XDG_CONFIG_HOME:-$HOME/.config}/Proxyman/bin/mcp-server"
test -x "$BRIDGE_PATH" && echo "MCP_BRIDGE: $BRIDGE_PATH"
```

## Phase 3: Launch Proxyman

### macOS

```bash
open -a "Proxyman"
sleep 10
```

### Windows (PowerShell)

```powershell
$candidates = @(
  "$env:LOCALAPPDATA\Programs\Proxyman\Proxyman.exe",
  "C:\Program Files\Proxyman\Proxyman.exe",
  "C:\Program Files (x86)\Proxyman\Proxyman.exe"
)
$proxymanExe = $candidates | Where-Object { Test-Path $_ } | Select-Object -First 1
if ($proxymanExe) {
  Start-Process $proxymanExe
  Start-Sleep 10
} else {
  Write-Host "Proxyman executable not found. Launch Proxyman from the Start menu, then continue."
}
```

After launch, the bundled MCP bridge should live next to the app executable. For the default per-user install:

```powershell
$bridge = "$env:LOCALAPPDATA\Programs\Proxyman\mcp-server.exe"
if (Test-Path $bridge) { Write-Host "MCP_BRIDGE: $bridge" }
```

### Linux

```bash
if command -v proxyman >/dev/null 2>&1; then
  nohup proxyman >/dev/null 2>&1 &
else
  nohup "$HOME/Downloads/Proxyman.AppImage" >/dev/null 2>&1 &
fi
sleep 10
```

If the Linux MCP bridge path is missing after launch, ask the user to open Settings > MCP and enable MCP Server, then relaunch Proxyman so the AppImage can copy and `chmod` the bridge into the config folder.

## Windows And Linux MCP Bridge Notes

Windows and Linux Proxyman builds use the same MCP model as macOS: an AI agent launches a bundled `mcp-server` process over stdio, and that bridge talks to the running local Proxyman app through an authenticated localhost handshake.

Use these bridge paths when moving on to `proxyman-mcp-setup`:

| Platform | Bridge path |
|----------|-------------|
| Windows default install | `%LOCALAPPDATA%\Programs\Proxyman\mcp-server.exe` |
| Windows custom install | `mcp-server.exe` in the same folder as `Proxyman.exe` |
| Linux AppImage | `${XDG_CONFIG_HOME:-$HOME/.config}/Proxyman/bin/mcp-server` |

Do not configure agents to use `Proxyman.exe` or the `.AppImage` as the MCP command. The command must be the stdio bridge executable.

## Phase 4: Prepare Proxy Capture

Proxyman can capture different targets in different ways. Ask what the user wants to capture before changing system state.

- Desktop apps and browsers often use the system proxy.
- CLI runtimes such as Node.js, Python, Ruby, and Go may need Proxyman Automatic Setup or Manual Setup.
- Localhost traffic may need Reverse Proxy because many clients bypass the system proxy for localhost.
- iOS apps behind VPNs may need Atlantis instead of classic proxy capture.

Use `proxyman-https-capture` for the target-specific routing, certificate, SSL Proxying, verification, and rollback workflow. Installation alone does not configure every target.

## macOS Helper Tool

The Helper Tool is macOS-only. Install it when the user wants Proxyman to override system proxy settings reliably across network interfaces, or when system proxy automation fails because privileged network settings are required.

Tell the user that macOS may show a visible password or approval dialog, then run:

```bash
open -a "Proxyman" --args --install-privileged-components
```

If macOS shows an approval prompt in System Settings, ask the user to approve Proxyman's Helper Tool and retry the system proxy action.

## Root Certificate

Root certificate setup is required for HTTPS decryption, not for merely installing Proxyman.

Preferred sequence:

1. Finish app installation.
2. Configure MCP with `proxyman-mcp-setup` if the user wants agent automation.
3. Use `get_certificate_status`.
4. If HTTPS decryption is needed and the certificate is missing or untrusted, use `install_certificate` through MCP or Proxyman's Certificate menu.

Without MCP, guide the user to Proxyman's in-app Certificate menu and choose the setup path for the target platform. Use `proxyman-https-capture` rather than applying a desktop root certificate to every target indiscriminately.

On Windows, automatic certificate installation may show a UAC prompt and can use an elevated `certutil` flow. On Linux, automatic trust-store installation is designed for Ubuntu/Debian, Fedora/RHEL, openSUSE/SUSE, and Arch-family systems; unsupported distros may require manual trust-store commands from the Proxyman UI.

Some Proxyman builds expose `proxyman-cli`. Use it only after confirming it exists with `command -v proxyman-cli` or `Get-Command proxyman-cli`. For custom root certificates only, a CLI build that supports root import can use:

```bash
proxyman-cli install-root-cert /path/to/custom-root.p12 --password "password" --trust
```

Do not use the custom root certificate CLI command for the default Proxyman-generated root CA.

## Phase 5: Suggest MCP Setup

After Proxyman is installed and running, offer to configure MCP:

```text
Proxyman is installed and running. The next step is to connect your AI agent to Proxyman MCP so it can inspect traffic, manage rules, install certificates when needed, and use Proxyman setup guidance. Use the proxyman-mcp-setup skill next.
```

If the user's next goal is activation, use `proxyman-license-management`. Do not ask them to paste a license key into chat.

## Troubleshooting

| Issue | Action |
|-------|--------|
| macOS DMG volume name is different | Run `ls /Volumes`, find the Proxyman volume, and copy `Proxyman.app` from it. |
| macOS app will not open | Run `xattr -cr "/Applications/Proxyman.app"` and launch again. |
| Windows SmartScreen blocks installer | Ask the user to approve the installer from the visible Windows prompt. |
| Linux AppImage does not run | Ensure it is executable and that required AppImage/FUSE dependencies are installed. |
| System proxy cannot be enabled on macOS | Install or approve the Helper Tool, then retry. |
| HTTPS traffic is still opaque | Install and trust the root certificate, then enable SSL Proxying for the target host. |

Referenced files: 1

View saved version →

---
name: "proxyman-https-capture"
description: "Configure and troubleshoot Proxyman HTTPS capture across desktop systems, Apple and Android devices or simulators, browsers, runtimes, containers, frameworks, and HTTP clients, including Atlantis instrumentation for controlled apps."
---

# Proxyman HTTPS Capture

Choose the least invasive working capture path for the user's exact device, runtime, network, and Proxyman platform. Normal proxy capture has three independent requirements: route traffic through Proxyman, trust the Proxyman CA, and enable SSL Proxying for the target host. Atlantis is an instrumentation alternative that forwards inspected traffic to Proxyman without that proxy/CA/SSL-Proxying path; apply its separate limits and verification.

Use `proxyman-mcp-setup` if tools are absent, `proxyman-traffic-debugging` to inspect captured flows, `proxyman-certificates-recovery` for the host Mac's generated/custom root lifecycle or custom server/client identities, and `proxyman-debugging-tools` when current official documentation is needed beyond the setup flow.

## Gather The Minimum Context

Establish:

- host OS running Proxyman and app version;
- target type, OS/runtime version, physical vs simulator/emulator, and debug vs production build;
- how the target connects to the host and whether a VPN, MDM, firewall, proxy, or certificate pinning is present;
- target hostname and whether HTTP is visible but HTTPS is opaque, or no traffic appears at all;
- whether the user wants GUI steps, MCP-guided automation, or manual commands.

Do not install certificates, root an emulator, alter system proxy, inject a shell/app, or restart a target until the user approves that action.

## Universal Capture Model

Diagnose in this order:

1. **Reachability:** target can reach the host running Proxyman.
2. **Routing:** target sends HTTP/HTTPS to Proxyman's current proxy host and port.
3. **Recording:** Proxyman is recording and the source/client is visible.
4. **Trust:** target trusts the correct Proxyman root CA in the relevant store.
5. **SSL Proxying:** target host is included and not excluded.
6. **Application behavior:** library proxy bypass, localhost special case, VPN, pinning, QUIC/HTTP3, or a custom trust store.

Do not treat certificate installation as proof that routing works, or SSL Proxying as proof that the target trusts the CA.

## Choose A Path

Read [capture paths](references/capture-paths.md) for the decision matrix and official page links. Read [Atlantis capture](references/atlantis.md) when the user asks what Atlantis is, needs capture while a VPN blocks the normal proxy, or wants to integrate Atlantis into an app.

- Desktop browser/app honoring system proxy: use system proxy plus host certificate trust.
- iOS/iPadOS/Vision Pro device: use Wi-Fi manual proxy and device certificate trust; for a supported app that can include an instrumentation library, consider Atlantis when proxy/certificate setup is undesirable or a VPN blocks the normal route.
- Apple simulator: install the CA into the booted simulator and use the simulator proxy path.
- tvOS/watchOS: follow the physical/simulator-specific official path.
- Android physical device: manual Wi-Fi proxy plus user/system CA strategy appropriate to OS and app policy.
- Android emulator: prefer Proxyman's guided automation for an active compatible AVD; read [Android emulator safety](references/android-emulator.md).
- Terminal runtime or browser: prefer Automatic Setup/injection when supported; otherwise use explicit proxy variables/options and the runtime CA bundle/store from [runtime capture](references/runtime-capture.md).
- Localhost: use explicit proxy configuration or Reverse Proxy; many clients intentionally bypass the system proxy.
- Docker/VM/subsystem: use the host address reachable from that network namespace, not blindly `127.0.0.1`.

## MCP-Guided Workflow

1. `get_version` and `get_proxy_status`.
2. `answer_setup_question` with the exact target, platform, runtime, VPN, and symptom.
3. Read the returned citations and use `list_setup_workflows` when the target is ambiguous.
4. For a normal proxy path, check `get_certificate_status` and `get_ssl_proxying_list`. For Atlantis, read `docs://setup/atlantis` and do not force certificate or SSL Proxying setup.
5. Use a relevant built-in resource or prompt. Setup resources are listed in the capture-path reference.
6. Explain the automation's state changes and request consent.
7. Use `run_guided_setup`, `inject_terminal`, `inject_electron`, `set_system_proxy`, `install_certificate`, or SSL tools only when the live server exposes the needed action and the user approved it.
8. Generate one known HTTPS request from the target.
9. Find it with `filter_flows` using host and, when relevant, `client`; inspect it with `get_flow_detail`.
10. Verify HTTPS body visibility, TLS/certificate summary, and target identity.

If the MCP setup index has no exact match, fetch the current official page through `proxyman-debugging-tools` rather than forcing a generic fallback result.

## GUI Workflow

1. Open Proxyman's Setup or Certificate guide for a normal proxy target. For Atlantis, follow the dedicated integration reference instead.
2. Use the proxy host/port shown by the running app; do not hardcode a common port.
3. Follow the target-specific routing and certificate steps from the current official page.
4. Enable SSL Proxying only for the required host or wildcard.
5. Generate a deterministic request and verify it in Proxyman.
6. Document how to restore proxy, trust, emulator boot image, or injected environment.

## Failure Triage

- **Nothing appears:** recording/routing/reachability/client-source problem.
- **HTTP appears, HTTPS does not:** routing works; inspect target trust, SSL Proxying, pinning, HTTP3/QUIC, or custom CA stores.
- **TLS error:** verify the correct CA, full trust, host include/exclude, app pinning, and date/time. Do not disable TLS verification as the default fix.
- **Only some libraries missing:** the library likely bypasses environment/system proxy or uses a separate trust store.
- **Device cannot connect:** verify same network or routable host address, firewall/access control, current port, and VPN/Private Relay behavior.
- **Localhost missing:** use Reverse Proxy or explicit proxy settings with a non-loopback target address.
- **VPN conflict on iOS:** read the Atlantis decision path for a build the user controls instead of repeatedly changing the device proxy.
- **Android app rejects user CA:** use a debug network security configuration or a controlled compatible emulator system-CA path. Do not advise bypassing pinning in a production app.

## Verification Checklist

A setup is complete only when:

- the expected target/client is identifiable;
- the test request and response appear;
- HTTPS headers/body are readable through the intended path: decrypted for normal proxy capture or forwarded by the expected Atlantis source;
- no unrelated hosts were unnecessarily enabled for SSL Proxying when the normal proxy path was used;
- the user knows the rollback path;
- limitations such as pinning, production builds, VPN, root/Magisk, or unsupported automation are stated.

Referenced files: 5

View saved version →

---
name: "proxyman-license-management"
description: "Safely activate, unlink, revoke, transfer, and manage Proxyman licenses and device seats. Use for license keys, activation failures, deactivation, License Manager, old devices, purchase emails, seat assignment, renewal, corporate proxy activation, or moving a license."
---

# Proxyman License Management

Handle license tasks with minimal secret exposure and an explicit distinction between the current app, `proxyman-cli`, and the web License Manager.

## Verify Current Official Guidance

Before giving entitlement, seat-count, renewal, supported-platform, or portal instructions:

1. Fetch `https://docs.proxyman.com/llms.txt`.
2. Fetch the current License and License Manager `.md` pages listed there.
3. Follow the License Manager access-link URL from the freshly fetched official page. Do not hardcode or guess the portal domain because official Proxyman domains and redirects can change.
4. Avoid hardcoding prices, device allowances, subscription terms, or trial terms; these can change.

Read [license workflows](references/license-workflows.md) for operation-specific checks.

## Protect The License Key

Treat a Proxyman license key, purchase email, activation response, and License Manager access link as secrets.

- Never repeat the full key in chat, logs, screenshots, issue text, or final output.
- Never ask the user to paste the key into chat or an agent tool call.
- Ask the user to enter a key directly in Proxyman when GUI activation is possible.
- Prefer GUI activation for ordinary use because a CLI argument may remain in shell history or appear in process inspection.
- The reviewed CLI accepts the key only as a positional argument. Never execute that form with a real key through the agent host. Discover the installed help, provide a command shape containing `<LICENSE_KEY>`, and have the user substitute the key and run it directly in their own terminal.
- Only reconsider agent-side CLI activation if version-matched help explicitly exposes a non-argument secret input such as stdin, a file descriptor, or an interactive prompt, and the user authorizes that method.
- Do not save the key in a script, repository, skill, environment file, or shell profile.
- Do not access the user's mailbox unless an available email connector is explicitly authorized for that task.

## Route The Request

### Activate This Device

Preferred GUI path:

1. Open Proxyman's License/Activate screen.
2. Have the user paste the key directly into the app.
3. Activate and verify the app shows the expected licensed state and account email.

CLI path is currently supported on macOS builds that include `proxyman-cli`. Use the `proxyman-cli` skill and discover `activate --help`, but do not execute the reviewed positional-argument form through the agent host. Give the user a verified command shape with `<LICENSE_KEY>` so they can substitute the key and run it directly in their terminal. After the command succeeds, have the user restart Proxyman before verifying the licensed state. Do not quit the app on their behalf unless they explicitly authorize it.

If activation fails, collect the exact sanitized error, app version/platform, current license state, network reachability, and external/corporate proxy state. Do not repeatedly retry a key or guess its validity.

### Activate Proxyman For iOS

Fetch the current iOS activation section from the official License page because navigation and device entitlements can change. Have the user enter the key directly in the standalone iOS app's protected license/unlock screen, then verify the app shows the licensed state. The reviewed desktop MCP and `proxyman-cli` do not activate the standalone iOS app; do not claim parity.

### Unlink This Device

Unlink affects the active device and may contact the license server before local license data is removed. Treat it as destructive.

1. Confirm the user means the current device.
2. Verify current licensed state.
3. Explain that access on this device will be removed.
4. Use the GUI unlink action or version-matched `proxyman-cli unlink` only after immediate confirmation.
5. Verify the app is no longer activated.

Do not use unlink when the user needs to recover a lost, replaced, or unavailable device; use License Manager.

### Revoke Or Remove Another Device

Use License Manager, not the local unlink command.

1. Open the official access-link page.
2. The user enters the purchase email or license key on the official site.
3. Proxyman sends an access link to the purchase email; the user opens it themselves unless they explicitly authorize mailbox access.
4. Identify the exact device/seat using the portal's metadata.
5. Confirm immediately before remove/revoke/transfer.
6. Verify the device is gone or the seat is available, then activate the replacement device separately.

Never guess which device to revoke based only on a generic name.

### Manage Seats, Emails, Transfer, Or Renewal

Use the current License Manager page and portal UI. First establish the user's license type and the desired device/email/seat. Describe any billing or entitlement consequence shown by the portal and require confirmation before the final action.

There is no general Proxyman MCP action for license management and no documented public License Manager automation API in this package. Do not improvise HTTP calls or scrape authenticated portal state.

## Corporate Proxy Or Network Failure

- Confirm general connectivity and capture the sanitized activation error.
- If the environment requires an upstream proxy, configure Proxyman's External Proxy using the current official guide. Ask before sending credentials.
- Recheck system date/time and TLS interception policy if the error indicates certificate or connection failure.
- Do not disable security controls or advise sharing the key with support logs.

## Finish With

- operation requested and surface used (GUI, CLI, or License Manager);
- device/account target without secret values;
- verified result or exact sanitized blocker;
- next safe action, including replacement-device activation when relevant.

Referenced files: 2

View saved version →

---
name: "proxyman-mcp-setup"
description: "Connect an AI coding agent to Proxyman MCP. Use when Proxyman is installed but the agent cannot see tools, or when configuring Codex, Claude, Cursor, VS Code, or Copilot and troubleshooting bridge, handshake, or tool-discovery errors."
---

# Proxyman MCP Setup

Configure an agent to talk to Proxyman MCP through Proxyman's bundled stdio bridge.

## Operating Rules

1. This skill is shell-first. MCP tools may not be connected yet.
2. Do not use API-key or direct HTTP MCP configuration. Proxyman MCP uses a local stdio bridge executable.
3. Proxyman must be installed, running, and have Settings > MCP > MCP Server enabled before verification can pass.
4. Preserve existing MCP server entries in agent config files. Add or update only the `proxyman` entry.
5. Prefer the exact command shown in Proxyman Settings > MCP when the app exposes one.

## Mental Model

Proxyman MCP has two local pieces:

1. The AI agent launches Proxyman's bundled `mcp-server` executable over stdio.
2. The bridge reads `mcp-handshake.json` from Proxyman's app data folder.
3. The bridge forwards tool calls to the running app at `http://127.0.0.1:<ephemeral-port>/mcp` with a bearer token from the handshake file.
4. The bridge belongs to one client session and exits when the client's stdin reaches EOF. The MCP client should launch it again for the next session.

Do not hardcode the HTTP port or token. The app regenerates them.

Common handshake locations:

| Platform/build | Handshake folder |
|----------------|------------------|
| macOS native app | Proxyman Application Support bundle folder, including regular and Setapp bundle IDs |
| Windows Electron app | `%APPDATA%\Proxyman` |
| Linux Electron app | `${XDG_CONFIG_HOME:-$HOME/.config}/Proxyman` |

Do not edit the handshake file. If it is missing or stale, restart Proxyman and re-enable Settings > MCP.

## Step 1: Verify Proxyman Is Installed

### macOS

```bash
if [ -d "/Applications/Proxyman.app" ]; then
  echo "INSTALLED: /Applications/Proxyman.app"
elif mdfind 'kMDItemCFBundleIdentifier == "com.proxyman.NSProxy"' | grep -q "Proxyman.app"; then
  mdfind 'kMDItemCFBundleIdentifier == "com.proxyman.NSProxy"'
else
  echo "NOT_INSTALLED"
fi
```

### Windows (PowerShell)

```powershell
$installed = Get-ItemProperty `
  "HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\*",
  "HKCU:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\*",
  "HKLM:\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall\*" `
  -ErrorAction SilentlyContinue |
  Where-Object { $_.DisplayName -like "*Proxyman*" }
if ($installed) { "INSTALLED" } else { "NOT_INSTALLED" }
```

### Linux

```bash
if command -v proxyman >/dev/null 2>&1 || ls "$HOME"/Downloads/Proxyman*.AppImage "$HOME"/Downloads/proxyman*.AppImage >/dev/null 2>&1; then
  echo "INSTALLED"
else
  echo "NOT_INSTALLED"
fi
```

If Proxyman is not installed, stop and use `proxyman-download-setup`.

## Step 2: Launch Proxyman And Enable MCP

### macOS

```bash
open -a "Proxyman"
sleep 10
```

### Windows (PowerShell)

```powershell
$candidates = @(
  "$env:LOCALAPPDATA\Programs\Proxyman\Proxyman.exe",
  "C:\Program Files\Proxyman\Proxyman.exe",
  "C:\Program Files (x86)\Proxyman\Proxyman.exe"
)
$proxymanExe = $candidates | Where-Object { Test-Path $_ } | Select-Object -First 1
if ($proxymanExe) { Start-Process $proxymanExe; Start-Sleep 10 }
```

### Linux

```bash
if command -v proxyman >/dev/null 2>&1; then
  nohup proxyman >/dev/null 2>&1 &
else
  nohup "$HOME/Downloads/Proxyman.AppImage" >/dev/null 2>&1 &
fi
sleep 10
```

Ask the user to open Proxyman Settings > MCP and enable "MCP Server". If the MCP toggle is locked, the user must authorize the plan/license required by their Proxyman build.

If a bundled `proxyman-cli` is already available, it can persist the same state even while Proxyman is closed. Read `proxyman-cli mcp --help` from that installed build, then use its `mcp on` action only when the user asked to enable MCP. Launch Proxyman afterward before expecting operational MCP calls. Use `proxyman-cli` skill for executable discovery and exact syntax; do not guess flags from this setup guide.

Keep "Redact Sensitive Data Before Sending to AI" enabled unless the user explicitly wants raw headers, cookies, query strings, or bodies sent to the agent.

On Linux AppImage builds, launching Proxyman lets the app copy the packaged MCP bridge into a stable config path and mark it executable. If the bridge path below is missing, enable MCP in Settings, restart Proxyman, and check again.

## Step 3: Resolve The Bridge Executable

### macOS

Regular build:

```bash
BRIDGE_PATH="/Applications/Proxyman.app/Contents/MacOS/mcp-server"
test -x "$BRIDGE_PATH" && echo "$BRIDGE_PATH"
```

If the regular path is missing, search installed Proxyman apps:

```bash
mdfind 'kMDItemCFBundleIdentifier == "com.proxyman.NSProxy" || kMDItemCFBundleIdentifier == "com.proxyman.NSProxy-setapp"' |
while read -r app; do
  candidate="$app/Contents/MacOS/mcp-server"
  [ -x "$candidate" ] && echo "$candidate"
done
```

### Windows (PowerShell)

The Windows Electron app copies `mcp-server.exe` beside `Proxyman.exe`. If no bridge is found, use the exact command from Proxyman Settings > MCP.

```powershell
$exeCandidates = @(
  "$env:LOCALAPPDATA\Programs\Proxyman\Proxyman.exe",
  "C:\Program Files\Proxyman\Proxyman.exe",
  "C:\Program Files (x86)\Proxyman\Proxyman.exe"
)
$proxymanExe = $exeCandidates | Where-Object { Test-Path $_ } | Select-Object -First 1

$bridgeCandidates = @()
if ($proxymanExe) {
  $bridgeCandidates += Join-Path (Split-Path $proxymanExe -Parent) "mcp-server.exe"
}
$bridgeCandidates += @(
  "$env:LOCALAPPDATA\Programs\Proxyman\mcp-server.exe",
  "C:\Program Files\Proxyman\mcp-server.exe",
  "C:\Program Files (x86)\Proxyman\mcp-server.exe"
)

$bridge = $bridgeCandidates | Where-Object { Test-Path $_ } | Select-Object -First 1
if ($bridge) { $bridge } else { "NOT_FOUND: copy the path from Proxyman Settings > MCP" }
```

### Linux

The packaged Linux AppImage copies `mcp-server` into Proxyman's config folder after launch. Prefer that stable copied path.

```bash
CONFIG_HOME="${XDG_CONFIG_HOME:-$HOME/.config}"
BRIDGE_PATH="$CONFIG_HOME/Proxyman/bin/mcp-server"

if [ -x "$BRIDGE_PATH" ]; then
  echo "$BRIDGE_PATH"
else
  echo "NOT_FOUND: launch Proxyman, enable Settings > MCP, restart Proxyman, or copy the path from Settings > MCP"
fi
```

Set `BRIDGE_PATH` to the chosen executable path. It must be the stdio bridge, not the Proxyman app binary.

## Step 4: Detect The Agent Config

Use environment variables first, then parent process, then filesystem markers.

```bash
[ -n "$OPENAI_CODEX" ] && echo "codex"
[ -n "$CLAUDE_CODE_ENTRYPOINT" ] && echo "claude-code"
[ -n "$CURSOR_TRACE_ID" ] || [ "$TERM_PROGRAM" = "cursor" ] && echo "cursor"
[ -n "$VSCODE_PID" ] || [ "$TERM_PROGRAM" = "vscode" ] && echo "vscode"
[ -n "$GITHUB_COPILOT_CLI" ] && echo "copilot-cli"
```

Fallback markers:

```bash
test -d "$HOME/.codex" && echo "codex"
test -d "$HOME/.claude" && echo "claude-code"
test -d "$HOME/.cursor" && echo "cursor"
test -d ".vscode" && echo "vscode"
test -f "$HOME/.copilot/mcp-config.json" && echo "copilot-cli"
test -f "$HOME/Library/Application Support/Claude/claude_desktop_config.json" && echo "claude-desktop"
```

If multiple agents are detected, ask the user which agent they want to configure.

## Step 5: Add The MCP Server

### Codex CLI

Preferred command:

```bash
codex mcp add proxyman -- "$BRIDGE_PATH"
```

Equivalent TOML:

```toml
[mcp_servers.proxyman]
enabled = true
command = "BRIDGE_PATH"
args = []
```

Config file: `~/.codex/config.toml`.

### Claude Code

```bash
claude mcp add proxyman --transport stdio -- "$BRIDGE_PATH"
```

Config file: `~/.claude.json`.

### Claude Desktop

Config file:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

Server entry:

```json
{
  "mcpServers": {
    "proxyman": {
      "command": "BRIDGE_PATH",
      "args": [],
      "env": {}
    }
  }
}
```

### Cursor

Config file: `~/.cursor/mcp.json`.

```json
{
  "mcpServers": {
    "proxyman": {
      "command": "BRIDGE_PATH",
      "args": [],
      "env": {}
    }
  }
}
```

### VS Code / GitHub Copilot

Config file:

- macOS: `~/Library/Application Support/Code/User/mcp.json` or workspace `.vscode/mcp.json`
- Linux: `~/.config/Code/User/mcp.json` or workspace `.vscode/mcp.json`
- Windows: `%APPDATA%\Code\User\mcp.json` or workspace `.vscode\mcp.json`

```json
{
  "servers": {
    "proxyman": {
      "command": "BRIDGE_PATH",
      "args": [],
      "env": {}
    }
  }
}
```

### GitHub Copilot CLI

Config file: `~/.copilot/mcp-config.json`.

```json
{
  "mcpServers": {
    "proxyman": {
      "command": "BRIDGE_PATH",
      "args": [],
      "env": {},
      "tools": ["*"]
    }
  }
}
```

When editing JSON or TOML config manually, parse and merge with a real parser when possible. Never replace unrelated `mcpServers` or `servers` entries.

## Step 6: Verify

Restart or reload the agent after changing config.

Verification sequence:

1. Confirm Proxyman is running.
2. Confirm Settings > MCP shows the server running.
3. Ask the agent to list MCP tools/resources/prompts if it supports discovery.
4. Call `get_version`.
5. Call `get_proxy_status`.

Successful setup means the agent can see Proxyman tools and `get_version` returns a Proxyman app/bridge response.

Tool availability can vary by platform and build. Treat the live tool list as authoritative. In particular, macOS system proxy control, Apple Terminal/iTerm/Ghostty injection, `.app` Electron injection, and bridge app-control tools are macOS-oriented; do not offer them on Windows or Linux unless that server exposes an applicable schema.

## Troubleshooting

| Error | Meaning | Action |
|-------|---------|--------|
| `Proxyman is not running or MCP server not started` | Bridge cannot find `mcp-handshake.json`. | Launch Proxyman and enable Settings > MCP. |
| `Invalid handshake file` | Token or port is stale. | Restart Proxyman, then reload the agent. |
| `Cannot connect to Proxyman` | App is closed or MCP server stopped. | Open Proxyman and confirm MCP status. |
| Linux bridge path is missing | The AppImage has not prepared `mcp-server` in the config folder yet. | Launch Proxyman, enable Settings > MCP, restart Proxyman, then check `${XDG_CONFIG_HOME:-$HOME/.config}/Proxyman/bin/mcp-server`. |
| Agent has no Proxyman tools | Config path is wrong or agent was not reloaded. | Re-check `BRIDGE_PATH`, config file, and restart the agent. |
| User sees no traffic after setup | MCP is connected but target capture is not configured. | Use `proxyman-https-capture`, then inspect with `proxyman-traffic-debugging`. |

## Next Step

Once `get_version` and `get_proxy_status` work:

- use `proxyman-traffic-debugging` for the complete MCP operation surface;
- use `proxyman-https-capture` for device, emulator, browser, runtime, and framework routing/trust setup;
- use `proxyman-debugging-tools` for current official feature documentation;
- use `proxyman-cli` for version-matched shell automation.

Referenced files: 1

View saved version →

---
name: "proxyman-traffic-debugging"
description: "Use Proxyman MCP to inspect and debug HTTP, HTTPS, and WebSocket traffic and operate the complete Proxyman MCP surface. Use for flows, API diagnosis, filtering, export, replay, Compose, debugging rules, WebSockets, recording, proxy and certificate control, code generation, or guided setup."
---

# Proxyman Traffic Debugging And MCP Operations

Use Proxyman MCP as a local control plane for the running Proxyman app. Start read-only, identify the relevant captured flow or current state, then make only the change the user requested.

If Proxyman tools are unavailable, use `proxyman-mcp-setup`. If Proxyman is absent, use `proxyman-download-setup`. For target-specific HTTPS configuration, use `proxyman-https-capture`. For current product documentation, use `proxyman-debugging-tools`. For shell automation, use `proxyman-cli`.

## Sources Of Truth

Use this order whenever sources disagree:

1. The connected server's `tools/list`, `resources/list`, and `prompts/list` for available MCP capabilities and exact schemas.
2. Current state returned by Proxyman status/list tools.
3. Built-in MCP resources for version-matched setup, CLI, and scripting guidance.
4. Official live documentation through `proxyman-debugging-tools` for GUI behavior and features beyond the built-in setup index.
5. The bundled references in this skill as an orientation map.

Never invent a tool, enum, parameter, rule ID, flow ID, file path, or command flag. The stdio bridge uses strict schemas.

## Mental Model

- The MCP client launches Proxyman's bundled `mcp-server` over stdio. The bridge reads a local handshake and forwards calls to an authenticated localhost server in the running app.
- Never hardcode the HTTP port or token. Each client bridge lasts only while its stdin remains open.
- Flow tools use the active workspace's sidebar-backed traffic universe. That includes flows from regular folders and, when present, saved, pinned, imported, Atlantis, and remote-device sources; results are deduplicated across folders rather than limited to the selected folder.
- List/filter results are snapshots. A flow ID can disappear after a clear, import, source change, or restart.
- Some actions are platform-specific. System proxy, Terminal injection, Electron `.app` injection, and app control are primarily macOS operations. Trust live discovery on Windows and Linux.

## Start Every MCP Session

1. Discover tools, resources, and prompts if the client exposes discovery.
2. Call `get_version` to verify the bridge reaches Proxyman.
3. Call `get_proxy_status` to learn recording state, proxy port, and SSL Proxying state.
4. Use the smallest read operation that establishes the target: `get_flows`, `filter_flows`, a status call, or the relevant list call.
5. Read detail using returned identifiers. Do not infer IDs from names or visible order.
6. Explain any mutation and its effect, obtain consent where required, call it, then verify with a read operation.

For tool selection, read [MCP tool catalog](references/mcp-tool-catalog.md). For multi-step tasks, read [MCP workflows](references/mcp-workflows.md). For Breakpoint, Map Local, Map Remote, Scripting, or overlapping modification rules, read [request and response rules](references/request-response-rules.md). For built-in knowledge, read [MCP resources and prompts](references/mcp-resources-prompts.md).

## Privacy And Consent

Keep **Settings > MCP > Redact Sensitive Data Before Sending to AI** enabled by default. It covers common secret headers, cookies, query values, JWTs, credentials, and secret-like body fields in MCP output.

Redaction does not sanitize the original HAR or Proxyman log written by `export_flows`. Treat exported files as sensitive.

Require explicit user approval immediately before:

- clearing the session, deleting a rule or Compose draft, closing a WebSocket, quitting Proxyman, or uninstalling a certificate;
- changing system proxy, certificate trust, recording, SSL Proxying, external proxy, or global debugging-tool state when the user did not already request that exact change;
- running guided automation, Terminal injection, Electron injection, or any action that launches or modifies another app;
- exporting original traffic or sending proxy credentials;
- disabling MCP redaction or revealing raw secrets.

Use an explicit approved destination for exports. Do not claim an export is redacted merely because MCP previews are redacted.

## Operating Pattern

### Inspect And Diagnose Traffic

1. Confirm capture state with `get_proxy_status`.
2. Narrow candidates with `get_flows` or `filter_flows`. Use client/device identity when the user names a source.
3. Inspect representative IDs with `get_flow_detail`; use its Summary metadata, timing, sizes, connection/TLS details, headers, query, cookies, and body preview.
4. Correlate method, URL, status, timing, request sequence, client, and matched debugging tools.
5. Return a verdict: passed, suspicious, failed, or inconclusive, with the flow IDs and observations supporting it.
6. Export or generate code only when the user needs a reproducible artifact.

### Mutate Proxyman Safely

1. Read the current state and capture the relevant IDs.
2. State the smallest proposed change and whether it affects capture, trust, traffic, disk, or another app.
3. Use the exact live schema. Omit optional fields only when the tool documents patch semantics.
4. Verify the returned object and call the matching list/status/detail tool.
5. Report changed IDs and an exact rollback action when one exists.

### Handle A Tool Error

1. Read the full MCP error; schema and validation errors are designed to be actionable.
2. Refresh live discovery after an app update or a `tool not found` result.
3. Re-list flows or rules when an ID is stale.
4. Correct the smallest invalid field; do not weaken the user's requested scope.
5. If the capability is not exposed, route to the GUI or `proxyman-cli` and say that MCP cannot perform it in this build.

## Critical Semantics

- `get_flows`/`filter_flows` return at most 500 results and body previews can be truncated. Use a user-approved export for complete archival data.
- `filter_flows` can filter on `client`; prefer it when distinguishing device, simulator, Atlantis, or app sources.
- Use `list_rules` for Breakpoint, Map Local, Map Remote, Block List, Scripting, Allow List, Network Condition, and DNS Spoofing. Reverse Proxy has its own list tool.
- Create/update operations use returned IDs. Updates preserve IDs.
- Successful rule CRUD, rule toggles, and global feature toggles refresh the corresponding open Proxyman lists/editors. Deleting the rule currently being edited closes that editor.
- Rule methods support uppercase `QUERY`; use `ANY` only for all methods. Set `include_paths` deliberately because defaults differ by rule type.
- Creating Scripting, Allow List, Network Condition, DNS Spoofing, or Reverse Proxy enables the associated feature. Verify other feature state with `list_tool_status`.
- Only one Network Condition can be active at a time.
- Network Condition profile names and supported scope come from the live schema. Do not invent custom bandwidth values when it exposes presets only.
- A Map Local literal-response update should send `response_body`, `status_code`, and `content_type` together.
- The reviewed MCP can manage Breakpoint rules but cannot edit or execute/cancel/abort an actively paused breakpoint; that interaction remains in the Proxyman GUI.
- The reviewed MCP Map Local surface creates literal or captured-flow responses, not arbitrary file/directory rules. Map Remote's reviewed MCP schema does not expose the CLI's separate preserve-original-URL option.
- For overlapping Map Local, Map Remote, Scripting, and Breakpoint rules, verify the ordered Debugging Tools summary instead of assuming every matching rule runs.
- External proxy changes should send a complete setting for the selected kind; omitted values are not reliably patch-preserved. Ask before passing credentials.
- Compose IDs are in-memory. `send_compose_http` is HTTP-only; WebSocket URLs are rejected.
- The reviewed MCP has no separate one-click Repeat action. Seeding Compose from a flow is an Edit & Repeat analogue, not exact GUI Repeat/history parity.
- MCP can show Protobuf content after Proxyman decodes it but does not configure Protobuf schemas/rules. TLS Key Logging is also GUI-only in the reviewed MCP.
- WebSocket payload previews are limited and redacted. `close_websocket_session` applies only to an active Compose-created WebSocket session.
- Scripting handlers must use Proxyman's positional signatures. Read `docs://scripting/snippet-code` before non-trivial script generation.
- `get_proxyman_cli_help` only returns safe, version-matched help. It never executes an operational CLI command.

## Expected Result

Finish with:

- what was inspected or changed;
- the relevant flow/rule/draft IDs;
- evidence from the verification read;
- privacy, export, or platform limitations;
- a rollback or next diagnostic step when appropriate.

Do not claim traffic is complete when capture state, time window, client source, or preview truncation makes the result inconclusive.

## Troubleshooting

- Handshake missing: launch Proxyman and enable Settings > MCP, or use `proxyman-mcp-setup`.
- Invalid handshake/401: restart Proxyman and reload the MCP client.
- No flows: check recording, target proxy routing, root trust, SSL Proxying, client source, and target-specific setup with `proxyman-https-capture`.
- HTTPS remains opaque: inspect certificate status and SSL Proxying includes/excludes before changing either.
- Localhost is absent: many clients bypass system proxy; use the Reverse Proxy workflow or the target's explicit proxy configuration.
- VPN blocks device capture: use the Atlantis decision path for supported iOS apps.
- Automation fails: check visible OS permission prompts, target availability, certificate state, and required user consent before retrying.

Referenced files: 5