MCP Tool Reference

probe-mcp exposes 61 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 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

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, …).

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.