Burp Suite Meets Claude: Inside PortSwigger's MCP Server Architecture

Hook

PortSwigger just made it possible to ask Claude to scan your web application for vulnerabilities and explain SQL injection findings in plain English—all through a protocol most developers haven't heard of yet.

Context

Security testing has traditionally been a command-line and GUI affair. You fire up Burp Suite, configure your browser proxy, intercept requests, manually modify parameters, analyze responses, and document findings. This workflow works, but it's intensely manual and requires deep security expertise at every step.

Anthropic's Model Context Protocol (MCP) emerged in late 2023 as a standard for connecting AI assistants to external tools and data sources. Think of it as a way for Claude or other LLMs to call functions in your local tools the same way they might search a database or fetch web content. PortSwigger saw an opportunity: what if security professionals could have conversational interactions with Burp Suite through Claude? Instead of manually clicking through tabs to find CSRF tokens or manually documenting SQL injection vectors, you could ask "Show me all requests with potential SQL injection points" and get structured responses. The mcp-server extension makes this real by implementing the MCP specification as a Burp Suite extension written in Kotlin.

Technical Insight

The architecture is cleverly layered to solve a fundamental compatibility problem. MCP supports two transport mechanisms: stdio (standard input/output) and Server-Sent Events (SSE). Claude Desktop only supports stdio, but running a stdio server inside Burp's JVM would be architecturally messy—you'd need to handle process lifecycle management and stdin/stdout redirection in a GUI application. PortSwigger's solution is to run an SSE server directly in the Burp extension, then provide a separate stdio-to-SSE proxy (mcp-proxy) that bridges the gap.

The Burp extension starts an HTTP server on localhost:9876 that speaks SSE for MCP communication. When Claude Desktop wants to interact with Burp, it spawns the mcp-proxy process (a separate JVM application), which connects to the SSE server and translates between stdio and SSE protocols. This architecture means the Burp extension doesn't need to manage child processes, and the proxy can be restarted without affecting Burp itself.

What's particularly elegant is how tools are defined using Kotlin's type system. Here's a simplified example of how you'd expose a tool to search Burp's proxy history:

data class SearchProxyHistoryInput(
    val urlPattern: String,
    val method: String? = null,
    val statusCode: Int? = null
) : PaginatedInput

data class ProxyHistoryResult(
    val url: String,
    val method: String,
    val status: Int,
    val timestamp: Long
)

val searchProxyHistory = tool(
    name = "search_proxy_history",
    description = "Search Burp's proxy history for matching requests"
) { input: SearchProxyHistoryInput ->
    val requests = burpApi.proxy().history()
        .filter { it.url().contains(input.urlPattern) }
        .filter { input.method == null || it.method() == input.method }
        .filter { input.statusCode == null || it.statusCode() == input.statusCode }
        
    requests.paginate(input.page, input.pageSize).map { request ->
        ProxyHistoryResult(
            url = request.url(),
            method = request.method(),
            status = request.statusCode(),
            timestamp = request.time().toEpochMilli()
        )
    }
}

The Kotlin DSL automatically derives the MCP tool schema from the data classes. The PaginatedInput interface adds page and pageSize fields, and the paginate() extension function handles chunking results. This means you get pagination support across all tools without writing boilerplate. The type safety ensures that if you change the input parameters, the schema exposed to Claude changes accordingly—no JSON schema files to maintain manually.

Under the hood, when Claude calls this tool, the mcp-proxy receives a JSON-RPC request via stdio, converts it to an SSE message, and sends it to Burp's SSE endpoint. The extension deserializes the input into the SearchProxyHistoryInput data class, executes the lambda, serializes the results, and streams them back as SSE events. The proxy converts these back to stdio for Claude to consume.

The extension includes an auto-installation feature that modifies Claude Desktop's configuration file directly. When you run the installation command, it locates the config file at ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the Windows equivalent, and injects an entry like:

{
  "mcpServers": {
    "burp": {
      "command": "/path/to/mcp-proxy/bin/mcp-proxy",
      "args": ["http://127.0.0.1:9876"]
    }
  }
}

This level of polish—detecting the Claude config location, safely modifying JSON without clobbering other entries, handling errors gracefully—makes adoption far easier than manual configuration. It's the kind of developer experience detail that separates a proof-of-concept from production-ready tooling.

Gotcha

The most obvious limitation is that Burp Suite must be running locally and the extension must be loaded for any of this to work. This isn't a cloud API you can hit from anywhere—it's a localhost-bound server. If Burp crashes or you unload the extension, Claude loses access to all Burp functionality mid-conversation. The SSE connection will drop, the proxy will fail, and you'll need to restart both Burp and Claude Desktop to reestablish the link.

There's also a security consideration that's easy to overlook: this extension exposes powerful web security testing capabilities to any process that can connect to localhost:9876. While binding to 127.0.0.1 prevents remote access, any local process—including malicious software or browser-based attacks—could potentially interact with your Burp instance if you're not careful. The extension doesn't implement authentication by default, which is reasonable for local tooling but worth understanding. If you're testing sensitive applications, ensure your local environment is secure before running this extension. Additionally, MCP itself is still evolving. The protocol isn't yet at 1.0, and breaking changes in future versions could require updates to both the extension and the proxy. You're adopting bleeding-edge infrastructure here, which means occasional friction as the ecosystem matures.

Verdict

Use if: You're a security professional or developer who regularly uses Burp Suite and wants to experiment with AI-assisted security workflows. This is particularly valuable if you find yourself repeatedly performing similar analysis tasks ("find all POST requests with this parameter," "explain this vulnerability in simpler terms," "generate a report of CSRF issues") that could benefit from natural language interaction. It's also worth trying if you're interested in the MCP ecosystem and want to see a well-implemented example of how desktop tools can expose their capabilities to AI assistants. Skip if: You don't have an active Burp Suite license, you need remote or headless operation (this is strictly localhost and GUI-dependent), or you're not yet seeing concrete use cases for AI integration in your security workflow. The current tooling requires both Burp and Claude Desktop running simultaneously on the same machine, which won't fit every environment. Also skip if you need production-grade stability right now—MCP is promising but still maturing, and you should expect some rough edges as the protocol evolves.