> For the complete documentation index, see [llms.txt](https://docs.bountysecurity.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bountysecurity.ai/burp-bounty-server/mcp-tools.md).

# 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.

| Tool                  | Arguments                                             | Result / use                                                                                                                                                     |
| --------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `server_info`         | None                                                  | Server `version`, `engine_version`, live/tracked counts, effective limits, insertion capability, history usage and `scan_access` (`allowed`, optional `reason`). |
| `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.                                                                                                         |

`scan_access.allowed: false` means license revalidation has blocked scanning. Creation, approval execution and resume return an error; discovery and retained-result retrieval remain available. Do not retry a cancelled scan until access is restored.

`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

| Argument           | Type / default                   | Contract                                                                                                                                                                |
| ------------------ | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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”.