Burp Suite MCP Server Won't Connect from WSL? Here's the Fix Nobody Talks About

How a simple cmd.exe wrapper solved the localhost networking nightmare between WSL and Burp Suite's MCP Server

If you've been pulling your hair out trying to connect Claude Code, Gemini CLI, or any AI coding assistant to Burp Suite's MCP Server from WSL — and you keep hitting cryptic errors like 403 Forbidden, connection refused, or Blocked browser request without Origin header — this article is for you.

I spent hours debugging this. The fix took 30 seconds once I understood why it was failing.

🧩 The Setup

Here's the scenario. You're a security researcher or bug bounty hunter running:

Burp Suite (Pro or Community) on Windows
Claude Code / Gemini CLI / Any MCP Client inside WSL (Windows Subsystem for Linux)
Burp's MCP Server extension enabled on 127.0.0.1:9876

You want your AI assistant to talk to Burp — send requests via Repeater, read proxy history, encode/decode payloads — all through the Model Context Protocol (MCP).

Sounds simple. It's not.

💥 The Error Parade

Here's the journey of errors you'll encounter, each more confusing than the last:

Error 1: The ClassDef Error (Red Herring)

Error: Could not find or load main class net.portswigger.mcp.ExtensionBase
Caused by: java.lang.NoClassDefFoundError: burp/api/montoya/BurpExtension

What happened: You pointed your MCP config at burp-mcp-all.jar — the Burp extension JAR. This JAR is meant to be loaded inside Burp Suite, not run standalone. Its main class implements BurpExtension, an interface that only exists in Burp's runtime.

The real JAR you need: mcp-proxy.jar — a separate, standalone proxy that bridges stdio ↔ SSE. You can extract it from Burp's MCP tab.

Error 2: Connection Refused

Error: connect: connection refused (127.0.0.1:9876)

What happened: You tried connecting directly via SSE (serverUrl: "http://localhost:9876/"). But from WSL's perspective, localhost is WSL's own loopback — not Windows'. Burp isn't listening inside WSL.

Error 3: The 403 Forbidden

Error: 403 Forbidden

What happened: You got clever and used the Windows host IP (172.x.x.x from /etc/resolv.conf). The connection reached Burp, but Burp's MCP server has a hardcoded localhost-only restriction. It rejected the connection because it didn't originate from 127.0.0.1.

Error 4: Blocked Browser Request

Blocked browser request without Origin header

What happened: Even when the connection reaches Burp, the MCP server validates the Origin header as a security measure against browser-based attacks. Non-browser MCP clients don't send this header, triggering the block.

🔍 Why Does This Happen? Understanding WSL Networking

Here's the key insight that makes everything click:

WSL and Windows have separate network stacks.

When your MCP client in WSL tries to reach 127.0.0.1:9876:

It hits WSL's own loopback → nothing is listening → connection refused

When it tries the Windows host IP (172.27.192.1:9876):

The request reaches Burp, but the source IP isn't 127.0.0.1 → Burp returns 403 Forbidden

Burp's MCP server only accepts connections from 127.0.0.1, and the host field is greyed out — you can't change it to 0.0.0.0.

✅ The Fix: The `cmd.exe` Bridge

The solution is elegant: run the MCP proxy JAR from Windows context using cmd.exe.

When WSL executes cmd.exe, the spawned process runs natively on Windows. When that process connects to 127.0.0.1:9876, the connection originates from Windows' loopback — which Burp accepts.

The proxy JAR communicates with the MCP client via stdio (stdin/stdout) — which works seamlessly across the WSL ↔ Windows boundary — and connects to Burp via SSE over Windows localhost.

📋 Step-by-Step Setup

Step 1: Extract the Proxy JAR

In Burp Suite:

Go to the MCP tab
Click Extract/Install to download mcp-proxy.jar
Save it to a Windows path, e.g.: C:\Users\YourUser\tools\mcp-proxy.jar

⚠️ Important: This is mcp-proxy.jar, NOT burp-mcp-all.jar. The proxy JAR is a standalone stdio-to-SSE bridge. The extension JAR is what runs inside Burp.

Step 2: Verify Java on Windows

Open PowerShell or CMD and run:

java --version

Note the path. If Java isn't in your Windows PATH, find Burp's bundled JRE:

C:\Program Files\BurpSuitePro\jre\bin\java.exe

Step 3: Update Your MCP Config

Edit your MCP configuration file. The location depends on your client:

Client	Config Path (in WSL)
Claude Code	`~/.claude/settings.local.json`
Gemini CLI	`~/.gemini/antigravity/mcp_config.json`
Generic	Varies by tool

Set the config to:

{
    "mcpServers": {
        "burp": {
            "command": "cmd.exe",
            "args": [
                "/c",
                "java",
                "-jar",
                "C:\\Users\\YourUser\\tools\\mcp-proxy.jar",
                "--sse-url",
                "http://127.0.0.1:9876"
            ]
        }
    }
}

📝 Note: Use double backslashes (\\) in JSON. These are Windows paths, not WSL paths — because cmd.exe executes in Windows context.

If Java isn't in your Windows PATH, use the full path:

"C:\\Program Files\\BurpSuitePro\\jre\\bin\\java.exe"

Step 4: Restart Your MCP Client

# For Claude Code
claude

# Then verify tools are connected
/tools

You should see all Burp MCP tools listed: send_http1_request, get_proxy_http_history, base64_encode, etc.

🔄 The Complete Flow

Here's what happens end-to-end when everything is working:

🆚 Approaches Compared

Approach	How	Result
Direct SSE from WSL to `localhost`	`serverUrl: "http://localhost:9876/"`	❌ `Connection refused` — WSL's loopback ≠ Windows'
Direct SSE from WSL to host IP	`serverUrl: "http://172.x.x.x:9876/"`	❌ `403 Forbidden` — Burp rejects non-localhost
`java -jar burp-mcp-all.jar`	Running the extension JAR standalone	❌ `NoClassDefFoundError` — wrong JAR
`netsh portproxy` forwarding	Forward WSL port to Windows	⚠️ Works but fragile, resets on reboot
`cmd.exe` + proxy JAR	Run proxy natively on Windows	✅ Clean, persistent, no hacks

🐛 Troubleshooting

"java is not recognized"

Java isn't in your Windows PATH. Use the full path to java.exe:

"C:\\Program Files\\BurpSuitePro\\jre\\bin\\java.exe"

"Unable to access jarfile"

The path to mcp-proxy.jar is wrong. Double-check:

The file exists at that Windows path
You're using double backslashes in JSON
No typos in the filename

"Connection refused" (still!)

Burp's MCP server isn't running. In Burp Suite:

Go to the MCP tab
Make sure the server is Enabled
Confirm it shows Started MCP server on 127.0.0.1:9876

Tools connect but don't work

Make sure you're using mcp-proxy.jar (the standalone proxy), not burp-mcp-all.jar (the Burp extension). They're different JARs with different purposes.

🧠 Key Takeaways

WSL and Windows have separate network stacks. localhost in WSL is not the same as localhost in Windows.
Burp's MCP server is hardcoded to localhost-only. You can't change it. Don't fight it.
cmd.exe is your bridge. Processes spawned via cmd.exe from WSL run natively on Windows, making their localhost connections go through Windows' loopback.
Use the right JAR. mcp-proxy.jar = standalone stdio proxy. burp-mcp-all.jar = Burp extension. They are not interchangeable.
stdio crosses the WSL boundary seamlessly. The MCP protocol over stdin/stdout works perfectly between WSL and Windows processes — no networking needed for that leg.

🚀 What You Can Do Now

With Burp MCP connected to your AI assistant, you can:

Send HTTP requests through Burp's Repeater from natural language
Search proxy history with regex patterns
Encode/decode payloads (Base64, URL encoding)
Analyze responses with AI-powered security review
Automate recon by chaining MCP tool calls

The combination of AI coding assistants + Burp Suite is a game-changer for security research. Don't let a networking quirk stop you.

If this saved you hours of debugging, give it a clap 👏 and share it with other security researchers running WSL + Burp Suite.

Found a different edge case? Drop a comment — I'd love to hear about it.

Tags: #BurpSuite #WSL #MCP #CyberSecurity #BugBounty #ClaudeCode #AITools #WebSecurity

xspatrian/BurpMCP.md

Select an option

No results found

Select an option

No results found

Burp Suite MCP Server Won't Connect from WSL? Here's the Fix Nobody Talks About

🧩 The Setup

💥 The Error Parade

Error 1: The ClassDef Error (Red Herring)

Error 2: Connection Refused

Error 3: The 403 Forbidden

Error 4: Blocked Browser Request

🔍 Why Does This Happen? Understanding WSL Networking

✅ The Fix: The `cmd.exe` Bridge

📋 Step-by-Step Setup

Step 1: Extract the Proxy JAR

Step 2: Verify Java on Windows

Step 3: Update Your MCP Config

Step 4: Restart Your MCP Client

🔄 The Complete Flow

🆚 Approaches Compared

🐛 Troubleshooting

"java is not recognized"

"Unable to access jarfile"

"Connection refused" (still!)

Tools connect but don't work

🧠 Key Takeaways

🚀 What You Can Do Now

xspatrian/BurpMCP.md

Burp Suite MCP Server Won't Connect from WSL? Here's the Fix Nobody Talks About

🧩 The Setup

💥 The Error Parade

Error 1: The ClassDef Error (Red Herring)

Error 2: Connection Refused

Error 3: The 403 Forbidden

Error 4: Blocked Browser Request

🔍 Why Does This Happen? Understanding WSL Networking

✅ The Fix: The cmd.exe Bridge

📋 Step-by-Step Setup

Step 1: Extract the Proxy JAR

Step 2: Verify Java on Windows

Step 3: Update Your MCP Config

Step 4: Restart Your MCP Client

🔄 The Complete Flow

🆚 Approaches Compared

🐛 Troubleshooting

"java is not recognized"

"Unable to access jarfile"

"Connection refused" (still!)

Tools connect but don't work

🧠 Key Takeaways

🚀 What You Can Do Now

✅ The Fix: The `cmd.exe` Bridge