MCP Tool Reference

probe-mcp exposes 84 tools, all prefixed probe_…. They’re grouped here by feature. For each tool: a one-line description, the input schema, and what comes back. Every result is wrapped in MCP’s content: [{type: "text", text: "..."}] envelope; for tools that return structured data, the text is pretty-printed JSON from the underlying REST API.

Need wiring? See MCP Setup.

Conventions

• Required parameters are marked. Everything else is optional.
• Type is the JSON Schema type accepted by the MCP inputSchema.
• Returns describes what the AI sees in content[0].text after the call resolves.
• IDs returned by probe_list_traffic are integers; collection / session / script-rule / flow / remote-fs connection IDs are strings.

Traffic inspection

probe_list_traffic

List recent HTTP/HTTPS traffic. Use filters to narrow the result.

Parameter	Type	Description
limit	integer	Max entries (default 20, capped at 500).
offset	integer	Pagination offset.
host	string	Substring match against host.
method	string	HTTP method filter (e.g. GET).
status_min	integer	Minimum status code.
status_max	integer	Maximum status code.
has_error	boolean	Only entries with status ≥ 400.
since_id	integer	Only entries with id > since_id (poll for new traffic).
since	integer	Only entries with timestamp >= since (ms since epoch).

Returns: {items, total, offset, limit} where items[] are summaries — id, method, url, host, status_code, content_type, duration_ms, timestamp, client_addr, has_response.

probe_get_request

Full detail of a single entry, including headers and bodies.

Parameter	Type	Required	Description
id	integer	yes	Traffic entry id from probe_list_traffic.

Returns: the full entry — request and response headers as [[key, value], …], request and response bodies as strings (or null), timing, content type, client address.

probe_search_traffic

Search by URL path or body content.

Parameter	Type	Required	Description
query	string	yes	Substring matched against URL and body.
limit	integer		Default 20.

Returns: the same shape as probe_list_traffic.

probe_get_session_summary

Quick health snapshot — uptime, entry count, capture status, API port, version. No parameters.

Returns: {status, version, capturing, entry_count, uptime_secs, api_port}.

probe_clear_traffic

Drop every captured entry from memory. No parameters. Returns: "All traffic cleared.".

probe_delete_traffic

Delete one entry by id.

Parameter	Type	Required
id	integer	yes

Returns: "Traffic entry <id> deleted.".

probe_get_capture_status

Whether traffic is being recorded right now and the current entry count. No parameters.

Returns: {capturing, entry_count}.

Capture control

probe_toggle_capture

Start or stop recording. Traffic still flows through the proxy when capture is off — it just isn’t logged.

Parameter	Type	Required
enabled	boolean	yes

Returns: "Traffic capture enabled." or "Traffic capture disabled.".

Replay

probe_replay_request

Re-send a captured request and return the new response.

Parameter	Type	Required
id	integer	yes

Returns: a JSON object containing the new response (status, headers, body, timing). The replay also lands as a fresh entry in the traffic list.

Diff

probe_diff_traffic

Compare two captured entries — method, URL, status, headers, body. Useful for “did the replay match the original?” or “what changed between two similar calls?”.

Parameter	Type	Required	Description
left_id	integer	yes	The “before” entry id.
right_id	integer	yes	The “after” entry id.

Returns: a JSON diff — added/removed/changed fields per section.

Export

probe_export_curl

Export an entry as a runnable cURL command.

Parameter	Type	Required
id	integer	yes

Returns: the cURL string.

probe_export_raw

Export an entry as raw HTTP text — request line + headers + body, then the response if there is one.

Parameter	Type	Required
id	integer	yes

Returns: the raw HTTP text.

Breakpoints

Breakpoint rules pause matching traffic so the AI (or you) can edit it before it continues. Use probe_list_intercepts to see what’s currently paused, then probe_resume_intercept to release it.

probe_create_breakpoint

Parameter	Type	Required	Default	Description
pattern	string	yes		Host or URL pattern to match.
intercept_request	boolean		true	Pause matching requests.
intercept_response	boolean		true	Pause matching responses.

Returns: "Breakpoint created for '<pattern>'.".

probe_delete_rule

Remove a breakpoint by its pattern.

Parameter	Type	Required
pattern	string	yes

probe_list_rules

List every active breakpoint. No parameters. Returns: array of breakpoint definitions.

probe_clear_breakpoints

Remove all breakpoints in one call. No parameters.

probe_list_intercepts

List requests currently paused, waiting for a decision. No parameters. Returns: array of {id} for each paused request.

probe_resume_intercept

Release a paused request, optionally rewriting it.

Parameter	Type	Required	Description
id	integer	yes	Intercepted request id.
abort	boolean		If true, abort with 502.
status_code	integer		Override response status.
headers	array of [key, value]		Override response headers.
body	string		Override response body.
url	string		Override request URL (request-phase intercepts only).

Returns: "Intercept <id> resumed." (or aborted).

Intercept hosts

A request to an intercept host is paused for inspection. Different from a breakpoint pattern: this matches strict hostnames.

probe_add_intercept_host

Parameter	Type	Required
host	string	yes

probe_remove_intercept_host

Parameter	Type	Required
host	string	yes

probe_list_intercept_hosts

List every intercepted host. No parameters.

Blocked hosts

Traffic to a blocked host is forwarded silently — no log entry, no breakpoint, no rule application. Use this to silence noise from analytics or telemetry hosts.

probe_block_host

Parameter	Type	Required
host	string	yes

probe_unblock_host

Parameter	Type	Required
host	string	yes

probe_list_blocked_hosts

No parameters. Returns: array of host strings.

Blocked clients

Block by client label — a process name (loopback) or IP address (remote phone). Same silent-forward behaviour as blocked hosts.

probe_block_client

Parameter	Type	Required	Description
label	string	yes	Process name or IP.

probe_unblock_client

Parameter	Type	Required
label	string	yes

probe_list_blocked_clients

No parameters. Returns: array of label strings.

Throttle

Probe has two throttle layers. The global throttle applies to every request; the scoped throttle rules apply per host/url-glob/app and run on top of it. The MCP can read both, and write the global one. Scoped rules are read-only here — Probe’s UI owns persistence and pushes the list on every mutation.

probe_set_throttle

Set the global bandwidth cap.

Parameter	Type	Required	Description
bytes_per_second	integer	yes	Bandwidth in bytes/sec.

probe_disable_throttle

Turn off the global throttle. No parameters.

probe_get_throttle

Current global throttle status and limit. No parameters.

probe_list_throttle_rules

List the scoped throttle rules. Each rule has its own profile (down/up bps, DNS delay, loss percentage) and matches by host, url glob, or app. No parameters.

Scripting

Run JS through Probe’s embedded QuickJS engine — either ad-hoc against a request you describe, or as a registered rule that auto-applies to matching traffic.

probe_execute_script

Run a script once in test mode and return its result. Doesn’t touch live traffic.

Parameter	Type	Required	Description
script	string	yes	JS source.
variables	object		Variables exposed via pro.variables.
request	object		Optional request context (method, url, headers, body).
response	object		Optional response context (status, headers, body).

Returns: the engine’s full output — console messages, assertion pass/fail, mutated request/response, and any thrown error.

probe_list_script_rules

List every script rule and the global scripting on/off flag. No parameters.

probe_add_script_rule

Add a rule that auto-applies JS to matching traffic.

Parameter	Type	Required	Default	Description
name	string	yes		Human-readable name.
url_pattern	string	yes		URL glob (supports *).
method	string		*	HTTP method, or * for all.
request_script	string		""	Runs on requests.
response_script	string		""	Runs on responses.
apply_to_request	boolean		true
apply_to_response	boolean		true

The new rule’s id is generated server-side as mcp_<ms>.

probe_update_script_rule

Patch an existing rule — only fields you pass are changed.

Parameter	Type	Required	Description
id	string	yes	Rule id.
name	string
method	string
url_pattern	string
request_script	string
response_script	string
apply_to_request	boolean
apply_to_response	boolean
enabled	boolean

probe_delete_script_rule

Parameter	Type	Required
id	string	yes

probe_toggle_scripting

Master switch. When off, no script rules fire.

Parameter	Type	Required
enabled	boolean	yes

Sessions

Probe organises captured traffic into session tabs in the UI. The active recording tab fills with new traffic; other tabs are read-only snapshots. Saved sessions live on disk under ~/.probe/sessions/.

probe_list_session_tabs

List every active tab — name, entry count, which one is the recording tab. No parameters.

probe_get_session_tab

Fetch the entries inside a specific tab.

Parameter	Type	Required
id	string	yes

probe_list_saved_sessions

List sessions persisted to disk. No parameters.

probe_get_saved_session

Fetch the entries inside a saved session.

Parameter	Type	Required
id	string	yes

Compose

The Composer is Probe’s request builder — Postman-like collections, environments, and inline auth. The compose tools are how the AI builds and fires off requests against your saved targets.

probe_list_collections

List every collection — name, request/folder/environment counts. No parameters.

probe_get_collection

Full collection content.

Parameter	Type	Required
id	string	yes

probe_create_collection

Create a collection. Saves to disk and shows up immediately in Probe.

Parameter	Type	Required	Description
name	string	yes	Collection name.
requests	array		Inline requests (each {name, method, url, headers, queryParams, body, contentType}).
folders	array		Folders with nested requests ({name, requests, folders}).
environments	array		Environments with {name, variables: [{key, defaultValue}]}.
default_headers	array		Headers applied to every request.
default_auth	object		Default auth (e.g. {type: 'bearer', token: '...'}).

Returns: the new collection’s id.

probe_add_compose_request

Add a single request to an existing collection.

Parameter	Type	Required	Default	Description
collection_id	string	yes
name	string	yes
method	string		GET
url	string			Supports {{variable}} syntax.
headers	array			[{key, value, enabled}].
query_params	array			[{key, value, enabled}].
body	string
content_type	string
folder_id	string			Subfolder placement.
auth	object			Per-request auth override.

probe_add_compose_environment

Add an environment with variables.

Parameter	Type	Required	Description
collection_id	string	yes
name	string	yes	e.g. Development.
variables	array	yes	[{key, defaultValue, currentValue?, enabled?, isSecret?}].

probe_send_compose_request

Resolve variables and send the request. The resulting traffic also lands in the log.

Parameter	Type	Required	Description
collection_id	string	yes
request_id	string	yes
environment	string		Env name or id.
variables	object		Per-call overrides (highest precedence).

Returns: {status, headers, body, duration_ms, …}.

Map Local

Map Local rules serve a canned response from disk or an inline string instead of contacting the origin. See Map Local for the full feature doc.

Caution

Rules created by MCP live in the proxy’s in-memory store and are ephemeral. Probe’s UI owns Map Local persistence — any UI edit (or app restart) clobbers MCP-added rules. Ask the user to re-save in the UI if the rule needs to survive.

probe_list_map_local_rules

List every rule and the master enable flag. No parameters.

probe_check_map_local_match

Preview which rule (if any) would intercept a given request — no side effects.

Parameter	Type	Required
method	string	yes
url	string	yes

Returns: {matched: true, rule: {…}} or {matched: false}.

probe_create_map_local_rule

Create a new rule. id is optional — generated as mcp_<ms> if you don’t supply one.

Parameter	Type	Required	Description
url_pattern	string	yes	Wildcard *, e.g. api.example.com/users/*.
source	string	yes	local_file or inline_body.
id	string
method	string		Default GET.
match_all_methods	boolean
enabled	boolean
file_path	string		Absolute path. Required when source is local_file.
inline_body	string		Required when source is inline_body.
inline_format	string		json, xml, html, or text.
status_code	integer		Default 200.
response_headers	object		String → string map.
delay_ms	integer		Artificial latency.

probe_update_map_local_rule

Full replace by id (not patch). Required fields match create, plus id.

probe_delete_map_local_rule

Parameter	Type	Required
id	string	yes

404 if id doesn’t exist.

probe_toggle_map_local_rule

Flip a single rule’s enabled flag.

Parameter	Type	Required
id	string	yes

probe_set_map_local_enabled

Master switch. When off, no rule matches.

Parameter	Type	Required
enabled	boolean	yes

Map Remote

Map Remote rules redirect matching requests to a different upstream — same shape as Map Local rules but the destination is another origin instead of a canned body. See Map Remote.

The MCP-vs-UI persistence caveat above applies here too.

probe_list_map_remote_rules

List every rule and the master enable flag. No parameters.

probe_check_map_remote_match

Preview which rule would redirect a given request, plus the rewritten URL.

Parameter	Type	Required
method	string	yes
url	string	yes

Returns: the matching rule and the resolved destination URL, or {matched: false}.

probe_create_map_remote_rule

Parameter	Type	Required	Description
source_scheme	string	yes	http or https.
source_host	string	yes
source_path	string	yes	Wildcards * are captured in order.
dest_scheme	string	yes	http or https.
dest_host	string	yes
dest_path	string	yes	Each * is filled with captures from source_path.
id	string		Generated as mcp_mr_<ms> if omitted.
source_port	integer		Defaults to 443/80 by scheme.
dest_port	integer
method	string		Default GET.
match_all_methods	boolean
enabled	boolean
preserve_original_host_header	boolean		When true, forward client’s Host header instead of rewriting to dest_host.

probe_update_map_remote_rule

Full replace by id. Required: id plus the same set as create.

probe_delete_map_remote_rule

Parameter	Type	Required
id	string	yes

probe_toggle_map_remote_rule

Parameter	Type	Required
id	string	yes

probe_set_map_remote_enabled

Parameter	Type	Required
enabled	boolean	yes

Mock Server

The Mock server is a standalone HTTP listener (default port 9100) that serves canned responses to clients that hit it directly — unlike Map Local, there’s no proxying involved. See Mock Server for the full feature doc.

Caution

Rules created by MCP live in the proxy’s in-memory store and are ephemeral. Probe’s UI owns Mock Server persistence — any UI edit (or app restart) clobbers MCP-added rules.

probe_list_mock_rules

List every Mock rule and the master enable flag. No parameters.

probe_get_mock_status

Get the Mock server listener status: whether it is running and on which port. No parameters.

probe_check_mock_match

Check whether a given method+path would be served by any active Mock rule — no side effects.

Parameter	Type	Required
method	string	yes
path	string	yes

Returns: {matched: true, rule: {…}} or {matched: false}.

probe_create_mock_rule

Create a new rule. id is optional — generated as mcp_<ms> if you don’t supply one.

Parameter	Type	Required	Description
url_pattern	string	yes	Path with * wildcards, e.g. /api/users/*.
id	string
name	string
method	string		Empty matches any method.
enabled	boolean
status_code	integer		Default 200.
status_text	string		Optional custom reason phrase.
headers	array of [name, value]
body	string
body_is_base64	boolean		Decode body from base64 for binary responses.
latency_ms	integer		Artificial delay before responding.

probe_update_mock_rule

Full replace by id (not patch). Required: id plus url_pattern.

probe_delete_mock_rule

Parameter	Type	Required
id	string	yes

404 if id doesn’t exist.

probe_toggle_mock_rule

Flip a single rule’s enabled flag.

Parameter	Type	Required
id	string	yes

probe_set_mock_enabled

Master switch. When off, no rule matches and the server answers 404 for everything.

Parameter	Type	Required
enabled	boolean	yes

probe_start_mock_server

Start the standalone listener.

Parameter	Type	Required	Default	Description
port	integer		9100	Port to listen on.

Errors if the port is already in use or the server is already running.

probe_stop_mock_server

Stop the standalone listener. No parameters.

Flows

API Flows are Probe’s node-based request chains — build once in the app (like Postman Flows), then drive them from the AI. Flows are Dart-owned: the two list/get tools read what the app has persisted, probe_run_flow asks the running app to actually execute the chain. See Flows in CI for the headless-automation angle these tools plug into.

probe_list_flows

List every saved flow — id, name, node count, edge count, created/updated timestamps. No parameters.

Returns: each flow’s id, name, nodeCount, edgeCount, createdAt, updatedAt. Use the id with probe_get_flow / probe_run_flow.

probe_get_flow

Full flow definition: nodes (request/condition/start/subflow, with extractions and assertions), edges, and canvas viewport.

Parameter	Type	Required	Description
flow_id	string	yes	Id from probe_list_flows.

Returns: the stored flow JSON, plus a derived subflowIds array — the deduped target ids of every subflow node, so a client can discover a flow’s sub-flow dependencies without walking node payloads itself.

probe_run_flow

Execute a flow end-to-end and return its run report.

Parameter	Type	Required	Description
flow_id	string	yes	Id from probe_list_flows.
environment	object		Variable overrides for this run (name → value), forwarded to the executor.

Returns: per-node results (status, extracted values, assertion outcomes, resolved URL), overall passed/failed/skipped counts, and total duration.

The Probe app must be running — this bridges to the UI to fire the flow’s real HTTP requests. Fails with 503 if the app isn’t running, 504 if it doesn’t answer in time (runs can take up to two minutes).

Files (remote-fs)

Thin wrappers over the Files feature’s remote-fs REST routes — the same SFTP/FTP/FTPS/S3/WebDAV engine backing the app’s Files browser. There is no connect tool: credentials stay entirely in the Probe UI path. Open a connection in the app first, then drive it from here by connection_id (see probe_list_remote_fs_connections).

probe_list_remote_fs_connections

List every open Files connection. No parameters.

Returns: each connection’s id, protocol, host, server label, home path, and whether the transport is encrypted.

probe_remote_fs_list_dir

List a directory’s entries on an open connection.

Parameter	Type	Required	Description
connection_id	string	yes	Id from probe_list_remote_fs_connections.
path	string	yes	Absolute remote directory path, e.g. /var/www.

Returns: each entry’s name, path, isDir, size, and (when the backend reports them) modifiedMs, permissions, owner, symlinkTarget.

probe_remote_fs_mkdir

Create a directory.

Parameter	Type	Required	Description
connection_id	string	yes
path	string	yes	Absolute path of the directory to create.

probe_remote_fs_rename

Rename or move an entry.

Parameter	Type	Required	Description
connection_id	string	yes
from	string	yes	Current absolute path.
to	string	yes	New absolute path.

probe_remote_fs_delete

Delete one or more entries in a single call.

Parameter	Type	Required	Description
connection_id	string	yes
paths	array of {path, is_dir}	yes	Entries to delete. is_dir defaults to false — needed by backends like S3 that distinguish an object from a prefix.

probe_remote_fs_download

Enqueue a download from the connection to a local file.

Parameter	Type	Required	Description
connection_id	string	yes
remote_path	string	yes	Absolute remote source path.
local_path	string	yes	Absolute local destination path.

Returns: {transferId} immediately — poll probe_remote_fs_transfers to watch progress and completion.

probe_remote_fs_upload

Enqueue an upload of a local file to the connection.

Parameter	Type	Required	Description
connection_id	string	yes
local_path	string	yes	Absolute local source path.
remote_path	string	yes	Absolute remote destination path.

Returns: {transferId}, same as probe_remote_fs_download.

probe_remote_fs_transfers

List the Files transfer queue. No parameters.

Returns: every download/upload the engine is tracking — transferId, connectionId, kind, state (queued/running/paused/done/cancelled/error), remote/local paths, and byte offset.

WebSocket

Inspect WebSocket frames Probe captured through the proxy. These are read-only snapshots of a bounded in-memory store — the proxy observes frames MITM’d through it; it does not open sockets. See WebSocket for the UI side.

probe_ws_list_connections

List captured WebSocket connections. No parameters.

Returns: each connection’s connId, logId (the traffic entry of the upgrade handshake, or null if uncorrelated), url, openedTs, closedTs, closed, and frameCount. Use connId with probe_ws_get_frames.

probe_ws_get_frames

Get the captured frames for one connection.

Parameter	Type	Required	Description
conn_id	integer	yes	connId from probe_ws_list_connections.

Returns: each frame’s dir (in = server → client, out = client → server), opcode (text/binary/ping/pong/close), text (text payload, or base64 for binary — capped at 64 KB), sizeBytes (true payload size), and truncated.

Errors

Every tool returns the same MCP envelope on failure:

{
  "content": [{"type": "text", "text": "Error: <reason>"}],
  "isError": true
}

Common reasons:

• Missing required parameter: <name> — schema violation.
• Probe app (PID <n>) is no longer running. — Probe was quit since probe-mcp started.
• Cannot reach Probe API: … — port in handshake is unreachable.
• HTTP-status messages from the underlying REST API (404, 401, 500, 503, 504, …). probe_run_flow is the one tool that can 503/504 under normal use — see its entry above.

Next steps

• MCP Setup — wire probe-mcp into your client.
• Internal REST API — what each tool calls under the hood.
• Scripting — what pro.* exposes inside probe_execute_script.
• Flows in CI — running probe_run_flow unattended, outside an interactive AI session.