Claude Code integration

ProxyPro ships with a built-in Model Context Protocol server so AI agents (Claude Code, Cursor, any MCP-HTTP client) can read your live HTTP / gRPC / WebSocket traffic and create / toggle / delete mock rules on your behalf. The tool surface covers inspecting captures, creating Map Local / Map Remote / Throttle rules, replaying requests, and toggling the macOS system proxy.

This page walks through wiring it up, then describes the optional skill bundle that adds workflow recipes on top of the raw tools.

Want the agent to drive a browser too?

This page covers the MCP server inside the desktop app. To run ProxyPro headless and let an agent drive a real Playwright browser through the proxy — with action↔capture correlation — see the Headless AI harness guide.

Localhost-only, no auth

The MCP server listens on 127.0.0.1:9091 with no authentication. Any local process on your machine can call its tools. Rules/mock states are isolated to each MCP transport. clear_captures, SSL settings, and the system proxy remain global, but per-resource leases prevent concurrent agents from racing changes. Leases are coordination only, not authentication. Don’t run ProxyPro on a shared / untrusted machine.

1. Connect Claude Code to the MCP server

Make sure ProxyPro is running, then in your terminal:

claude mcp add --transport http proxypro http://localhost:9091/mcp

Verify the handshake:

claude mcp list
# proxypro: http://localhost:9091/mcp (HTTP) - ✓ Connected

Open a Claude Code session in any project and try:

“Use ProxyPro to list the last 5 HTTP captures.”

Claude should call list_captures and show you the results. If it doesn’t, ensure the session was started AFTER you ran mcp add — Claude only picks up MCP servers at session start.

2. (Optional) Install the skill bundle

The MCP tools alone are usable, but Claude routes them better when paired with a small skill that documents when to invoke which tool, common multi-step workflows, and anti-patterns to avoid.

Get the bundle

Two ways:

From the ProxyPro app

1. Open ProxyPro
2. Click the MCP tab in the top nav
3. Click Export skill bundle…
4. Save proxypro-claude-skill.zip anywhere convenient

From GitHub

Download the latest skill bundle from GitHub Releases (look for proxypro-claude-skill.zip in the release assets).

Install into your project

# From your project root
mkdir -p .claude/skills/
unzip ~/Downloads/proxypro-claude-skill.zip -d .claude/skills/

You should now have:

.claude/skills/proxypro/
├── SKILL.md
├── CLAUDE.md.example
└── references/
    ├── recipe-01-mock-single-endpoint.md
    ├── recipe-02-simulate-api-failure.md
    ├── recipe-03-replay-modified-headers.md
    ├── recipe-04-ab-compare-upstreams.md
    ├── recipe-05-throttle-slow-network.md
    ├── recipe-06-capture-and-mock.md
    └── recipe-07-system-proxy-session.md

Restart your Claude Code session — it picks up new skills at session start.

Lightweight alternative: CLAUDE.md only

If you want the integration mentioned to Claude on every session but don’t need the full recipe library, just paste CLAUDE.md.example into your project’s CLAUDE.md:

cat .claude/skills/proxypro/CLAUDE.md.example >> CLAUDE.md

You can delete the skill folder after if you only want the minimal hint.

3. What you can do now

Workflows the recipes cover

The seven recipes in the skill bundle each show a concrete multi-step pattern with example prompts, exact tool calls, and cleanup steps:

#	Recipe	Use case
1	Mock a single endpoint	”Fake the response from /api/users”
2	Simulate an API failure	”Make /api/checkout return 500”
3	Replay with modified headers	”Re-send that with an admin token”
4	A/B compare prod vs staging	”Diff what v1 vs v2 returns”
5	Throttle for slow-network testing	”Try this on slow 3G”
6	Capture-and-mock pattern	”Freeze that real response as a fixture”
7	System proxy session toggle	”Capture everything for the next 10 minutes”

Tools available

Core MCP tools include:

• Read: list_captures, get_capture, get_capture_body, list_rules, get_rule_detail, list_mock_states, get_mock_state
• Rules: create_map_local_rule, create_map_remote_rule, create_throttle_rule, create_breakpoint_rule, create_mock_state_write_rule, update_rule, set_rule_enabled, delete_rule
• Mock state: create_mock_state, update_mock_state, delete_mock_state
• Runtime: replay_request, clear_captures, set_system_proxy
• SSL proxying: get_ssl_proxying, set_ssl_proxying_mode, add_ssl_proxying_host, remove_ssl_proxying_host

Each has a schema-validated input + a description Claude reads at session start. The skill bundle adds higher-level “when to invoke” hints + recipes that compose multiple tools.

4. Cleanup hygiene

Every connected MCP client receives an internal sandbox automatically; there is no session argument for the model to manage. Its rules and mock states are removed on browser_close, disconnect, idle expiry, or ProxyPro shutdown. Rules from another model and persistent Desktop rules cannot be listed, edited, or deleted through that sandbox.

Open the Rules tab to see live Agent owner badges. Use Promote to persistent when a useful agent rule should outlive its transport. Manual delete_rule(ruleId) is still useful for cleaning up before the session ends, but is no longer required for crash/disconnect safety.

Open the MCP tab when several agents are connected. Its Session Control Center shows each transport’s last tool, browser, rule and mock-state ownership. You can close only its browser, clean only its sandbox, terminate that one connection, or select several rules and promote them atomically. Existing persistent mock state is never overwritten during promotion.

Client name/version comes from the normal MCP initialize handshake. You may set a temporary alias for the live connection, inspect its request/error/byte totals, expand the tool-to-traffic timeline, or choose View traffic. The Captures tab applies an exact agent:<session-id> filter but does not hide or permission other local traffic. Export evidence saves that session’s current identity, resource, rule, traffic, and activity summary as local JSON.

Global mutations are coordinated in the same MCP tab. The first session to change SSL proxying, the system proxy, or clear captures owns that resource for up to 30 minutes; a competing model receives a busy response that names the owner and next actions. SSL and system-proxy snapshots restore automatically on disconnect/expiry. Capture clearing is serialized but cannot be rolled back. The Control Center shows the countdown and last mutation, and lets you Release while keeping current state, Restore now, or Force takeover to another active session.

Finished transports move into Finished runs instead of disappearing. The Desktop stores the newest 50 runs within a 25 MB private local budget, including the end reason, cleanup/global-restore outcome, traffic summary, recent tool-to-traffic activity, sandbox rules, and bounded mock-state snapshots. From there you can reopen archived traffic, compare two runs, export a local handoff JSON file, build an editable Repro Scenario, or delete the record.

For a durable regression, expand a finished run and select up to 20 archived requests plus any useful Map Local rules/state. Safe GET, HEAD, and OPTIONS requests are selected by default; methods that may create side effects stay disabled until you explicitly allow them. Preview repro scenario generates valid Scenario v1.6 YAML with archived status and bounded exact-JSON assertions. Inline fixtures are copied, while selected state can be flattened to a static response with a warning that transitions are not reproduced. Review or edit the YAML, then open it in Scenario Studio to save, run, optionally record, or execute later through the local CLI/CI runner.

Before keeping the regression, choose Verify stability ×3. ProxyPro runs the Scenario exactly three times, reads the response bodies attached to its network assertions, and compares each result with the archived exact JSON. The review labels baselines stable, volatile, or flaky; flags likely IDs, UUIDs, timestamps, tokens, and array-order changes; and proposes existence plus stable-field assertions where exact equality is brittle. The original and proposed YAML stay side by side until you explicitly apply or save the proposal, after which Verify proposal once confirms it with the native runner. Repeating POST/PUT/PATCH/DELETE and other side-effect methods requires a visible opt-in. All runs and response analysis remain local.

Repro generation is read-only. It does not reconnect the model, mutate a live sandbox, restore authentication, or reacquire SSL, system-proxy, capture-clear, or other global state.

To continue work in another model, select eligible rules/state, choose a live target transport, and click Restore selected. ProxyPro allocates fresh IDs, keeps the target’s current sandbox intact, and does not touch peer or persistent rules. Truncated state is not restorable, and handoff never restores SSL, system-proxy, capture history, or any global lease.

For the system proxy specifically: if set_system_proxy(true) was called and the session ended without cleanup, you may need to toggle it off manually in ProxyPro → header → system proxy toggle.

5. Assign a failed Scenario to an agent

Open a failed or unstable result in Scenario Studio, choose an active MCP agent, and click Assign debug task. ProxyPro keeps the YAML, focused retry and assertion evidence, capture/recording references, source path, and CLI command in a bounded private local task. Only the selected MCP transport can see it.

The assigned model uses these tools:

• list_debug_tasks — list only tasks assigned to this transport
• get_debug_task — read the YAML and focused local evidence
• claim_debug_task — begin a tracked attempt
• submit_debug_task_result — report passed/failed/blocked, optionally attach valid Scenario YAML and up to ten owned sandbox-rule IDs

Submission does not accept a fix automatically. The Desktop MCP tab shows the result as requiring developer verification. Expand Review submitted YAML and rules to compare the failing source with the exact proposal and inspect the submitted sandbox-rule IDs. Verify once runs a quick native check; Verify ×3 proves repeatability and reuses volatile-baseline analysis when the proposal contains exact JSON assertions. Side-effect methods need the same explicit opt-in as Scenario Studio.

The verification record compares status, failed assertions, duration, flow count, and failed OpenAPI contract assertions with the original evidence. It keeps run IDs, capture references, replay paths, and bounded failure details in the local task. Next, Analyze impact ranks neighboring suite Scenarios by shared mocks, fixtures, method/path operations, hosts, fault targets, and URL scopes. Review its checkboxes, then run the candidate plus selected neighbors with Run impact gate. The source-set hash forces re-analysis when local YAML changes, and unsafe methods require a separate opt-in. Accept & resolve is enabled only when the exact current submission and affected suite both pass. A developer can still choose Override & resolve, but must record a reason. A new agent submission invalidates earlier verification and impact evidence.

Saving a copy, replacing the original suite YAML, and promoting submitted rules are separate explicit actions. Source replacement requires confirmation, rule promotion requires the owning MCP transport to remain active, and neither action resolves the task implicitly. You may also open the proposal—or a stabilized follow-up—in Scenario Studio. A disconnect makes unfinished work unassigned; another model never inherits it implicitly.

Debug tasks are stored only on this Mac (newest 50, 10 MB total, private file permissions). Claiming or submitting a task does not change persistent rules, global settings, authentication, or cloud state.

For feedback while the model edits files, open the suite in Scenario Studio and choose Start watch. Local YAML, referenced fixture/mock-body files, and the attached OpenAPI spec are debounced and mapped to impacted Scenarios. Only the latest revision runs; a newer file event cancels stale work. Results reuse the same local history, performance, assertion, and OpenAPI evidence. Unsafe native methods require the separate watch consent checkbox, and watch mode never accepts an agent result or edits source automatically.

When the suite contains a validated proxypro.watch.json, application source globs can select Scenario paths or normalized METHOD /path operations. Call get_project_watch_status to read the current revision, mapping reasons, affected paths, aggregate failures, and any Debug Tasks assigned to this MCP transport. The status tool is read-only: a developer must still assign a failed Scenario from Desktop, and tasks assigned to another model are never returned.

For explicit pre-commit verification, use Verify changed files after opening the suite. It compares the worktree with HEAD or the entered Git base, includes untracked files, and runs only mapped candidates plus impact-index neighbors. Enable Fail unmapped when every relevant source change must have a Scenario owner. The read-only get_git_verification_status MCP tool exposes the latest aggregate selection and result; it never starts a run, and it still returns only Debug Tasks assigned to the calling transport.

Before an agent edits code, click Audit mappings to check the complete source ownership model rather than only the current Git diff. The audit finds unmapped included files, dead source/Scenario selectors, and invalid Scenario YAML without starting the engine or running tests. Agents may read the bounded aggregate result through get_scenario_mapping_audit_status; the tool cannot start an audit or expose any Debug Task.

For an audit with unmapped sources, Plan fixes creates a deterministic local remediation review. Desktop shows confidence, rationale, selected Scenarios, the exact profile diff, and a mapping/exclude/skip choice for every path. If no valid Scenario mapping exists, the recommendation includes an editable Scenario skeleton preview. Applying requires a second visible confirmation and fails closed when proxypro.watch.json, the source universe, or Scenario content changed since preview. Agents can read the bounded plan or developer-confirmed result through get_scenario_mapping_remediation_status; this MCP tool cannot edit the profile or create the skeleton itself.

Troubleshooting

Claude doesn’t call ProxyPro tools when I ask

• Make sure claude mcp list shows ✓ Connected
• Restart the Claude Code session — MCP server list is picked up at start
• Check the MCP tab in ProxyPro for the recent-calls log; if it stays empty, the calls aren’t reaching ProxyPro at all

claude mcp add says “Failed to connect”

• Is ProxyPro actually running? Check Activity Monitor for ProxyPro and proxypro-engine
• Is port 9091 reachable? curl http://127.0.0.1:9091/mcp should respond
• If you see a different port in ProxyPro’s MCP tab (e.g. 9092), 9091 was in use at startup and ProxyPro hopped — claude mcp add needs the actual port

The skill bundle didn’t end up under .claude/skills/

Re-check the unzip command — unzip -d .claude/skills/ extracts the contents as .claude/skills/proxypro/.... If you see a doubled path like .claude/skills/proxypro/proxypro/..., move the inner proxypro/ folder up one level.

Where to next

Quickstart Get ProxyPro running + your first capture

Rules reference Manual rule authoring + import/export