> For the complete documentation index, see [llms.txt](https://burp-ai-agent.six2dez.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://burp-ai-agent.six2dez.com/user-guide/burp-integration.md).

# Burp Integration

The extension integrates directly with Burp tools and workflows so AI analysis stays close to real testing data.

## Supported Burp Tools

| Burp Tool              | Integration                                                                                         |
| ---------------------- | --------------------------------------------------------------------------------------------------- |
| **Proxy History**      | Request context menus and passive scan coverage (via a registered Montoya passive scan check, Pro). |
| **Repeater**           | Context actions on requests/responses and MCP Repeater tools.                                       |
| **Intruder**           | MCP tools can create and run Intruder setups.                                                       |
| **Scanner** (Pro)      | Issue context menus, active checks, and ScanCheck integration.                                      |
| **Site Map**           | Context menus and MCP site map search/query tools.                                                  |
| **Target Scope**       | Scope-aware scanner and MCP scope tools.                                                            |
| **Comparer** (Pro)     | MCP `comparer_send` workflow support.                                                               |
| **Collaborator** (Pro) | Active scanner OAST payload generation and polling.                                                 |

## Burp Pro vs Community Edition

| Feature                         | Community                                                                                                                                                                                 | Professional                                                                                                                                                                              |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Context menu actions (requests) | Yes                                                                                                                                                                                       | Yes                                                                                                                                                                                       |
| Context menu actions (issues)   | No                                                                                                                                                                                        | Yes                                                                                                                                                                                       |
| Chat & sessions                 | Yes                                                                                                                                                                                       | Yes                                                                                                                                                                                       |
| AI backends                     | BApp Store build: AI requests need "Use AI" enabled for the extension; with it off they are refused. GitHub full build: the HTTP and CLI backends work regardless; Burp AI needs "Use AI" | BApp Store build: AI requests need "Use AI" enabled for the extension; with it off they are refused. GitHub full build: the HTTP and CLI backends work regardless; Burp AI needs "Use AI" |
| MCP server                      | Yes (non-Pro tools)                                                                                                                                                                       | Yes (all tools)                                                                                                                                                                           |
| Passive AI Scanner              | Manual queue path                                                                                                                                                                         | Automatic passive scan check + manual queue                                                                                                                                               |
| Active AI Scanner               | Manual queue path                                                                                                                                                                         | Native scanner integration + queue                                                                                                                                                        |
| Scanner MCP tools               | No                                                                                                                                                                                        | Yes (GitHub full build only)                                                                                                                                                              |
| Collaborator OAST               | No                                                                                                                                                                                        | Yes                                                                                                                                                                                       |
| Scan reports via MCP            | No                                                                                                                                                                                        | Yes (GitHub full build only)                                                                                                                                                              |

The extension detects Burp edition at startup and disables unsupported capabilities automatically.

Which Burp editions can turn "Use AI" on is decided by Burp, not by this extension. PortSwigger documents "Use AI" as a per-extension checkbox, off by default: **Extensions > Installed > Custom AI Agent > Use AI**. See [Which Build?](https://burp-ai-agent.six2dez.com/getting-started/which-build.md#burp-edition-requirements).

MCP `ai_analyze` and `ai_passive_scan` return a tool error while "Use AI" is off, in both builds, even if another backend is selected. See the [MCP Tools Reference](https://burp-ai-agent.six2dez.com/mcp-server/tools-reference.md#ai-extension-native).

## MCP Tool Toggles

You control MCP exposure from **Burp Integration** and **MCP Server** tabs. The **Burp Integration** tab embeds the redesigned MCP Tools panel: tools are grouped under **AI Tools (extension-native)**, subtitled "Extension-native tools — available in both the BApp Store and the full build.", and **Montoya Tools (generic)**, subtitled "Generic Montoya API wrappers — available in the full build only.", with a search/filter box and per-group bulk toggles.

### Build matters

There are two builds, and which tools are even registered depends on the build. [Which Build?](https://burp-ai-agent.six2dez.com/getting-started/which-build.md) compares them.

* **GitHub full build** (`./gradlew fullJar` → `build/libs/Custom-AI-Agent-full-<version>.jar`; release asset `Custom-AI-Agent-full-<version>.jar`): registers all **59** MCP tools, including the generic Montoya-API tools (proxy history, Repeater, scanner, scope, site map, Intruder, Collaborator, utilities, etc.).
* **BApp Store build** (`./gradlew bappJar` → `build/libs/custom-ai-agent-bapp.jar`; release asset `Custom-AI-Agent-bapp-<version>.jar`): registers only the **8** extension-native AI tools (`status`, `issue_create`, `ai_analyze`, `ai_passive_scan`, `ai_findings_recent`, `redact_preview`, `ai_audit_query`, `ai_backends_list`). The generic Montoya-API tools are not exposed over MCP in this build — PortSwigger's official Burp MCP Server provides those.

The group subtitles in the panel show which build offers each group, so you can see at a glance what is available in your build.

### Safe vs Unsafe

* **Safe**: read-only operations, enabled by default.
* **Unsafe**: state-changing or traffic-generating operations, disabled by default.

### Managing Tool Access

1. Open the **Burp Integration** tab in Settings.
2. Enable/disable tools by group, using search/filter and per-group bulk toggles as needed.
3. Enable **Unsafe Tools** in the **MCP Server** tab if unsafe tool toggles must be active.

![Screenshot: MCP tool toggles](https://741304880-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FaQ3pR328GUzNEoYZ2fgc%2Fuploads%2Fgit-blob-efaa58f98c2ced94d763b1623657081c1a214fe9%2Fmcp-tool-toggles.png?alt=media)

{% hint style="warning" %}
Enable unsafe tools only for trusted MCP clients and only while actively using those workflows.
{% endhint %}

## Collaborator Workflow (Pro)

When **Use Collaborator (OAST)** is enabled in Active Scanner settings, the workflow is:

1. Active scanner builds a targeted OAST payload using a Burp Collaborator interaction domain.
2. Payload is inserted into selected injection points (based on risk level and scan mode).
3. Requests are sent to the target and polling runs at configured intervals.
4. DNS/HTTP callbacks are correlated to the originating scan item.
5. Confirmed OAST behavior contributes to scanner evidence and issue creation.

Typical use cases:

* blind SSRF confirmation,
* blind command injection confirmation,
* out-of-band deserialization indicators.

## Native Scanner Integration (Pro)

On Burp Pro, an `AiScanCheck` is registered into Burp's scanner pipeline.

* AI checks run alongside native checks.
* Findings appear as Burp issues (`[AI Active]` naming convention).
* Burp scope/configuration rules still apply.

On Community edition, this path is skipped and the extension uses manual queue execution.

## Related Pages

* [Active AI Scanner](https://burp-ai-agent.six2dez.com/scanners/active.md)
* [Context Menus](https://burp-ai-agent.six2dez.com/user-guide/context-menus.md)
* [MCP Security Model](https://burp-ai-agent.six2dez.com/mcp-server/security-model.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://burp-ai-agent.six2dez.com/user-guide/burp-integration.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
