Start or adopt a live capture session for incremental polling. PREFER THIS TOOL when the user wants to inspect ongoing / just-now traffic. This is the default entry point for live-plane analysis; do NOT default to list_recordings or query_recorded_traffic unless the user explicitly names a saved recording (.chlsj).

DEFAULT BEHAVIOR (safe): adopts the user's ongoing Charles session WITHOUT clearing the traffic that is already there, and ensures Charles is recording (start_recording is idempotent). The capture always includes the traffic recorded before this call, so query and read tools see the whole session: the first read_live_capture returns the existing entries, later reads return only new ones.

Pass reset_session=true ONLY when the user explicitly asks to clear / wipe the current Charles session before starting a fresh capture (e.g. debugging a single isolated flow). Reset is destructive and cannot be undone by this server.

Returns a capture_id required by all other live tools. Preserve and reuse capture_id across follow-up live calls.

Read incremental traffic and advance the cursor. Returns compact entry summaries (host/method/path/status only). This read call consumes the current increment. Use query_live_capture_entries for structured filtering instead of this tool. This tool advances the internal cursor — repeated calls only return new items.

Preview incremental traffic without advancing the cursor. Returns compact entry summaries (host/method/path/status only). This peek call does not consume the current increment. Safe to call repeatedly — does not consume items. Use query_live_capture_entries for structured filtering and analysis.

Stop an active live capture and optionally persist the filtered snapshot. Only status='stopped' means the capture is fully closed.

Analyze the active live capture with structured summary-first filtering. This is the RECOMMENDED tool for inspecting live / ongoing traffic. Prefer this over query_recorded_traffic / analyze_recorded_traffic unless the user explicitly names a saved recording (.chlsj). Use this summary path before calling get_traffic_entry_detail. Does NOT advance the cursor — safe to call repeatedly with different filters. Default cursor=0 scans all captured data from the beginning. Use get_traffic_entry_detail to drill down into a specific entry_id.

Pass since_seconds=N to look only at traffic captured in the last N seconds (relative to "now" at query time). This is the preferred shortcut when the user asks for "just now / recent" traffic and removes the need to thread the cursor through follow-up calls.

Analyze a saved recording snapshot with compact summaries. HISTORY-PLANE TOOL — only use when the user explicitly references a saved recording (.chlsj file). For ongoing / live traffic, prefer start_live_capture + query_live_capture_entries instead. Preserve recording_path for follow-up detail calls. Returns structured TrafficSummary items with matched_fields and match_reasons. Use get_traffic_entry_detail to drill down into a specific entry_id afterwards.

Load one traffic entry detail view for drill-down inspection. Requires entry_id from a prior summary/query call. Use detail for one confirmed target, not bulk browsing. For history entries, pass recording_path from the summary. For live entries, pass capture_id from the summary. Keep include_full_body=false unless you specifically need the raw body text.

Return coarse traffic class counts for a live capture or saved recording.

Group analyzed traffic so the agent can inspect hot spots with lower token cost.

Query the latest saved recording. This tool never reads the live Charles session. HISTORY-PLANE TOOL — only use when the user explicitly references a saved recording (.chlsj file). For ongoing / live traffic, prefer start_live_capture + query_live_capture_entries instead.

List saved recording files using an explicit history-oriented tool name. HISTORY-PLANE TOOL — only use when the user explicitly references saved recordings (.chlsj files). For ongoing / live traffic, prefer start_live_capture instead. Start history analysis here, then preserve recording_path for summary/detail calls.

Load a saved recording snapshot. This tool never reads the live Charles session. HISTORY-PLANE TOOL — only use when the user explicitly references a saved recording (.chlsj file).

Set a network throttling preset in Charles.

Reset the Charles environment and restore the saved configuration.

Check Charles connectivity and active live-capture state. Returns recommended_next_action to nudge agents toward the live plane: when no active capture exists, agents should start_live_capture before falling back to history-plane tools.

Import an official Charles XML/native session into the canonical reverse-analysis store.

List imported captures from the local SQLite store.

Query imported entries using route-level filters. Use this as the summary-first narrowing step for a reverse capture_id.

Get the canonical detail view for one imported entry. Use after candidate selection; this is not a bulk-browsing endpoint.

Decode a stored request/response body, including protobuf when a descriptor is provided.

Replay one imported entry with optional mutations and store the experiment result.

Compare multiple requests and rank fields that look signature-related.

List persisted findings from replay or signature-candidate analysis.

Inspect Charles recording state and optional reverse live-session state.

Start a near-real-time live analysis session without using undocumented JSON export. Preserve and reuse live_session_id for follow-up reverse live tools.

Snapshot the current Charles session and inspect only new entries without advancing the live cursor.

Snapshot the current Charles session and advance the live cursor to consume new entries.

Stop a reverse live-analysis session and optionally restore Charles recording.

Run a task-oriented live login/auth reverse-analysis workflow on new traffic. Read summary/report first and expand evidence only as needed.

Run a task-oriented live API reverse-analysis workflow on new traffic. Read summary/report first and expand evidence only as needed.

Run a task-oriented live signature reverse-analysis workflow on new traffic. Read summary/report first and expand evidence only as needed.

One-time setup per host: create the mock directory and the Charles rules (Map Local https:///* -> directory, Rewrite text/plain -> JSON type). After that, mocks are plain files: present = served by Charles, absent = real server. apply=false returns manual steps (UI, no restart); apply=true writes the rules into the Charles config and only works while Charles is closed (Charles overwrites its config on quit). This tool never quits or starts Charles: ask the user to save the session, quit Charles, and start it after the write. A config backup is made first.

Turn a captured response into a Map Local mock, optionally editing it. Take entry_id from query_live_capture_entries (pass capture_id) or a history summary (pass recording_path). The mock is written for the entry's host and path; a previous mock at that path is archived, never deleted. Read warnings: Map Local always answers 200 and ignores method and query.

Write a mock response from scratch. Pass body as a JSON value (written pretty-printed) or body_text as raw text, not both. Prefer mock_create_from_entry when a real response exists, so the shape stays valid.

List active mock files, optionally for one host. Archived versions are not listed.

Show the content of one active mock.

Stop mocking one path: the file moves to the archive and requests pass through to the real server again.

Turn the whole Charles Map Local tool on or off. Off means every request goes to real servers; mock files stay on disk.

Send a host (or domain glob) through the dispatcher; once per host/domain. One Charles Map Remote mapping (https:// -> local dispatcher, empty destination path, preserve host header) covers every path and action under it; after that, mocks are only data. Unmocked requests pass through unchanged. apply=true writes the mapping into the Charles config; only while Charles is closed, because Charles overwrites its config from memory on quit. This tool never quits or starts Charles: ask the user to save the session and quit Charles, not to reopen it until the write is done, then to start it. apply=false returns manual steps that work in the UI without a restart.

Overview of the whole captured session: API requests grouped by method, host, path and the value of a request-body field (default /action; "null" for GETs and bodies without it), with counts, sample entry_ids and response statuses. Use it right after reading a session so the user can name what to change. Filter with host_contains / path_contains / methods. live needs capture_id.

Create or extend the rule for one request variant (method + path + body/query values) from a captured entry. match_body_fields picks the variant, e.g. ["/action"] for POSTs; leave it empty for GETs. host_scope="any" (default) applies the rule on every routed host, since the same API runs on several hosts; "exact" limits it to the entry's host, and host accepts a glob such as .example.com. match_path replaces the entry's exact path with a pattern where * stands for one segment or part of one, for segments that differ by platform or app version: /api//payoneer covers /api/p24-aos2/payoneer and its iOS twin. It must cover the entry's path. mode="patch": the real server answers; request_patches edit the request body, request_headers set (or remove with null) request headers before it is forwarded, response_patches edit only the named response fields. mode="fixture": answer from the captured response with any status (e.g. 500), never contacting the server (request edits are ignored). status overrides the response code in either mode; delay_ms waits that many milliseconds before answering, to test loaders and client timeouts. merge=true adds to the variant's existing rule; a patch on the same pointer replaces the old one. Patches are checked against the captured entry.

Write a rule document directly (advanced; prefer mock_rule_create_from_entry). Shape: {"id", "host", "match": {"method", "path", "query", "headers", "body": {"/action": "init"}}, "request": {"patches"}, "response": {"mode": "fixture"|"patch", "status", "headers", "patches"}, "priority", "enabled"}. Fixture rules need fixture_json or fixture_text unless a fixture exists.

List dispatcher routes and rules, optionally for one host. Invalid rule files are reported in errors and ignored by the dispatcher.

Show one rule document and, for fixture rules, the stored fixture.

Enable or disable one rule without deleting it.

Archive one rule (and its fixture); matching requests pass through again.

Start, stop or check the local dispatcher that Map Remote routes point to. A dispatcher started here lives inside the MCP server and stops with it; for a long-running one use the charles-mcp-dispatcher command. By default start also enables Charles Map Remote and stop disables it (toggle_map_remote), so routed requests never point at a stopped dispatcher; mock files and rules stay.