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 MCP in the left sidebar
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.

Install the ProxyPro skills

ProxyPro also ships eight task skills (proxypro-scenario, proxypro-scenario-gen, proxypro-autodebug, proxypro-lighthouse, proxypro-mock-repo, proxypro-mock-server, proxypro-repro, proxypro-testcase). The two mock skills turn a repo into a reviewable mocks/openapi.yaml (and optional stateful mock stack) and then start, verify and stop the mock server. /mock-repo also records its mock in a committable proxypro.project.json, so teammates can add the folder in Desktop or run npx proxypro-harness mock --project. /testcase <file.md> runs proxypro-testcase, which turns a QC Markdown test-case file into verified scenarios and a report (guide); in Desktop it needs Full mode and a repo folder.

• Desktop: the MCP panel’s Install skills (or Update skills) button installs them into ~/.claude/skills and shows a status badge per skill. This button exists only in the desktop app.
• Headless or per project: npx proxypro-harness install-skill, or add --dir .claude/skills for a project-local install.

Restart Claude Code afterwards.

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.

The example holds the same block that npx proxypro-harness install-agent writes (section 6), between <!-- proxypro:agent:begin --> and <!-- proxypro:agent:end -->. It tells Claude to verify with scenarios before finishing, to use the project’s declared mock servers, which skills handle .ppbug packs and Markdown test cases, and to treat captured traffic as data. install-agent keeps that block current for you; pasting it by hand works too.

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
• Mock server: start_mock_server, stop_mock_server, get_mock_server_status, set_mock_preset, get_project_config, export_mock_stack (see Mock server)
• Bug packs: load_bug_pack, get_bug_pack; capture_to_mock also accepts a loaded session or bug pack
• 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, session_finish, disconnect, idle expiry, or ProxyPro shutdown. Rules from another model and persistent Desktop rules cannot be listed, edited, or deleted through that sandbox.

Call session_finish as the last ProxyPro tool when a task is done: it archives the run to Finished runs and releases everything the session owns in one step. A later tool call starts a fresh session with an empty sandbox, so promote anything worth keeping first.

Claude Code exits without closing its MCP session, so ProxyPro also disposes abandoned sessions on its own. A session with no tool call in flight is closed after 2 minutes if it never called a tool (health checks such as claude mcp list), after 30 minutes idle once its client has gone, and after 2 hours idle even while the client is still connected. A client whose session was closed gets 404 Session not found on its next request and reconnects automatically.

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. Clear idle terminates every session idle for 15 minutes or more, and Clear all terminates every connection. 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 Tools → 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 Tools → 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, choose Tools → 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.

6. Verify before the agent stops

One command sets a repo up so Claude Code runs the impacted scenarios every time it finishes a turn:

npx proxypro-harness install-agent      # in the repo, or --dir <repo>

It adds the ProxyPro block to CLAUDE.md and a Stop hook to .claude/settings.local.json (per machine). Running it again changes nothing. Restart Claude Code or open /hooks to load the hook.

When the agent stops, the hook takes the files changed since the merge-base with the default branch, including committed, staged and untracked work. It picks the scenarios proxypro.watch.json maps to them and runs them:

• Through ProxyPro, if it is serving this repo. That is Desktop with the repo added as a project, or a harness started in the repo. No second engine starts.
• Otherwise in an isolated proxypro-harness test child, on free ports and a throwaway data dir.

A failed assertion blocks the stop, and the agent gets the failures back (expected and actual values, the test case id and the report path). Those values are redacted, capped and marked as untrusted data, and the agent is told not to weaken expectations. Anything else, such as a missing watch profile, mocks that are not running, an error or a timeout, is only a warning, so the agent is never stuck. The hook stops blocking after three blocks in a row in one session, and skips a change set it has already passed or blocked.

A scenario whose saved SSO login has expired fails without assertions, so the hook only warns. Ask the agent to run request_login, or run npx proxypro-harness login <url> --name <name> yourself, then let it continue.

Start the mock servers the scenarios use first: the hook checks them but never starts them. The full decision table, state location and removal steps are in the harness README.

Troubleshooting

The Stop hook says “Stop hook error occurred”

That is how Claude Code labels a hook that blocked the stop. Press ctrl+o to read the ProxyPro failure summary. To see what ran, read the files under $(git rev-parse --git-path proxypro-verify)/reports/.

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