MCP tools reference
A practical reference for discovery, scan control and finding retrieval.
Tools operate on the server connection used for the call. Save that connection alias with every scan and issue ID. Consult the running server's advertised schema when connecting to an older build.
server_info
None
Server version, engine_version, live/tracked counts, effective limits, insertion capability and history usage.
list_profiles
Optional tag, scanner
Catalogue metadata; tag matching is case-insensitive.
create_scan
See below
Starts work or returns pending approval.
list_scans
offset ≥ 0; limit 1–100, default 100
Live/retained scan page and pending approvals.
get_scan_status
scan_id; optional include_configuration
Compact progress, issue counts, timestamps, warnings and optional retained settings.
get_scan_issues
scan_id; optional min_severity, offset, limit
Finding summaries; default 20, maximum 100 per page.
get_scan_issue
scan_id, integer issue_id ≥ 0
One finding and bounded evidence.
pause_scan
scan_id
Pause the scan.
resume_scan
scan_id
Resume a paused live scan.
cancel_scan
scan_id
Cancel live work or its pending approval request.
cancel_all_scans
None
Cancel ongoing work and discard pending approvals on this server.
delete_scan_history
scan_id
Delete a completed scan's retained summary and evidence.
active_scans excludes terminal work. tracked_scans may include finished scans still retained in the live manager; neither is a measurement of free CPU capacity.
create_scan
requests
Required array of strings
1–100 complete raw HTTP requests, using CRLF and a blank line before the body. Each request becomes one scan.
services
Array of origin strings
One http://host:port or https://host:port per request. Required unless each request already has its service URL on a separate leading line. Conflicts are rejected.
mode
active by default
active sends probes; passive analyzes supplied exchanges.
responses
Array of strings
Passive mode only; required for passive-response checks, one nonempty HTTP response per request.
profile_names
Array of strings
Exact catalogue names.
profile_tags
Array of strings
Select profiles matching any requested tag.
profiles
String
A complete .bb JSON array serialized as a string, for supplied profiles.
rps
Integer 0–1,000,000
Omitted inherits the scan default; 0 explicitly means unlimited.
concurrency
Integer 1–1000
Omitted inherits the scan default.
payload_strategy
only_once by default
only_once or all; misspelled values are rejected.
retain_results
History-enabled state by default
true requests durable findings; false temporary results.
Choose exactly one of names, tags or inline profiles. Only enabled profiles execute. Active mode needs active profiles; passive mode accepts only passive profiles. Supplied response data is not an instruction to fetch or scan a target.
The request/response input and profile input have 8 MiB bounds. The enclosing MCP HTTP body is also limited to 8 MiB, including JSON escaping and overhead. Split large batches. There is no dry_run flag, client idempotency key, catalogue upload tool, arbitrary custom-token argument or approval tool.
Creation and errors
A running response includes created scan IDs and count. A pending response includes status: pending_approval, approval_id, scans, targets and expiry. Pending work has not been authorized to start.
Inspect the MCP tool result's isError and error content as well as transport success. A timeout/lost response may leave started work behind. Reconcile list_scans on the same server before retrying; creation is not idempotent. Partial start errors also require reconciliation.
Retrieving findings
For get_scan_issues, valid min_severity values are Information, Low, Medium, High. Follow next_offset until null. The filtered total and whole-scan counts answer different questions.
Use the numeric summary issue_id as the next call's issue_id. Detail text fields are capped at 64 KiB and exchange arrays at four items; inspect truncated_fields. A history-expiry or read error is not “no vulnerabilities”.
Last updated