> 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/mcp-server/external-servers.md).

# External MCP Servers

Beyond Burp's built-in MCP tools, Custom AI Agent can connect to **external or custom MCP servers** over **SSE** (HTTP) or **stdio** (local process) transports. Their tools appear alongside the built-in Burp tools in the agent's tool preamble, namespaced `ext:<server>:<tool>`. Introduced in v0.9.0 (closes #41).

{% hint style="info" %}
**Full build only.** External MCP servers, the **Settings > MCP Server > External MCP Servers** section and the `ext:<server>:<tool>` tools are part of the GitHub full build (`Custom-AI-Agent-full-<version>.jar`, built with `./gradlew fullJar`). The BApp Store build (`./gradlew bappJar`) does not include them. See [Which Build?](https://burp-ai-agent.six2dez.com/getting-started/which-build.md).
{% endhint %}

## Setup

1. Open **Settings > MCP Server** and expand **External MCP Servers**.
2. Click **Add Server** and choose a transport:
   * **SSE** — enter the server's SSE URL (e.g. `http://127.0.0.1:3000/sse`) and, if required, a bearer token.
   * **stdio** — enter the executable command (e.g. `/usr/local/bin/my-mcp-server`). stdio is **off by default** (it launches a local process) — enable it explicitly and confirm the local-process warning first.
3. Click **Save Server**, then **Save settings**. The Status column shows `Connected (N tools)`, and the server's tools become callable as `ext:<server>:<tool>` and listed in the agent's tool preamble.

## Transport Types

| Transport | Use when                                | Example                        |
| --------- | --------------------------------------- | ------------------------------ |
| **SSE**   | Remote or local HTTP-based MCP server   | `http://127.0.0.1:3000/sse`    |
| **stdio** | Local process launched by the extension | `/usr/local/bin/my-mcp-server` |

## Security Model

{% hint style="warning" %}
External MCP servers are **untrusted by default**. Their output is wrapped in an explicit trust-boundary marker before it enters the AI prompt. This makes the trust boundary explicit and escapes forged closing markers, but it is prompt-injection mitigation rather than proof that a model will ignore malicious instructions.
{% endhint %}

* **Encrypted auth tokens.** SSE bearer tokens are stored encrypted at rest (AES-256-GCM, `ENC1:`-prefixed) — the same path as every other API key — masked in the UI behind a show/hide toggle, and never logged. The AES master key is itself stored in Burp Preferences beside the ciphertext (`secret.master.key.v1`), so this protects against casual inspection of a preferences file, not against a local attacker. See [Secrets at Rest](https://burp-ai-agent.six2dez.com/privacy-and-logging/limitations.md#secrets-at-rest--what-the-encryption-does-not-do).
* **Trust-boundary wrapping.** Every external tool result is wrapped as `[EXTERNAL-TOOL-RESULT:<server>]…[/EXTERNAL-TOOL-RESULT]` (with close-marker escaping), marking it as untrusted data rather than agent instructions. Treat it as defense in depth, not a semantic sandbox.
* **SSRF guard.** Configuring an external URL that resolves to a non-loopback private/link-local address triggers the same soft SSRF warning used for backend URLs — non-blocking, so deliberate internal use is still possible.
* **Audit logging.** Every external tool invocation is recorded in the [audit log](https://burp-ai-agent.six2dez.com/privacy-and-logging/audit-logging.md) (when enabled) with the server name, tool name, and a result summary.
* **Always confirmed.** When the extension's own AI emits a call to an `ext:`-namespaced tool, it asks you every single time — no "approve for session" option. External tools never inherit a built-in tool's silent tier. See [Tool-Call Confirmation](https://burp-ai-agent.six2dez.com/mcp-server/security-model.md#7-tool-call-confirmation-sec-06).

## Related Pages

* [MCP Overview](https://burp-ai-agent.six2dez.com/mcp-server/overview.md)
* [Security Model](https://burp-ai-agent.six2dez.com/mcp-server/security-model.md)
* [Tools Reference](https://burp-ai-agent.six2dez.com/mcp-server/tools-reference.md)
* [Audit Logging](https://burp-ai-agent.six2dez.com/privacy-and-logging/audit-logging.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/mcp-server/external-servers.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.
