# How to Integrate VulnClaw with External Tools Like Burp Suite and Frida

> Integrate VulnClaw with Burp Suite and Frida using its Modular Control Protocol. Discover and register external tool APIs via SSE or stdio for enhanced security testing.

- Repository: [Unclecheng/VulnClaw](https://github.com/Unclecheng-li/VulnClaw)
- Tags: how-to-guide
- Published: 2026-06-30

---

**VulnClaw integrates with Burp Suite and Frida through its Modular Control Protocol (MCP) layer, which discovers and registers external tool APIs via SSE or stdio transports defined in [`vulnclaw/config/schema.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/config/schema.py).**

The Unclecheng-li/VulnClaw repository provides a unified framework for LLM-driven security testing by connecting to external tools through a standardized protocol. This integration allows security researchers to control Burp Suite for HTTP interception and Frida for runtime instrumentation using natural language prompts. All tool configurations, routing logic, and lifecycle management are implemented in the `vulnclaw/mcp/` directory.

## Understanding the MCP Architecture

VulnClaw communicates with external binaries through the **Modular Control Protocol (MCP)**, an abstraction layer that handles connection lifecycle, tool discovery, and JSON-RPC-like messaging. The architecture separates transport concerns from business logic, enabling seamless switching between local scripts and remote services.

### MCP Server Configuration

Built-in server definitions reside in [`vulnclaw/config/schema.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/config/schema.py) within the `BUILTIN_MCP_SERVERS` mapping. Each entry specifies the transport type, command path, or URL endpoint required to reach the external tool.

For Burp Suite, the default configuration uses an SSE transport pointing to `http://127.0.0.1:9876` (lines 72–80). The Frida MCP server follows the same pattern, typically exposed via SSE or stdio depending on your deployment model. When `enabled: true` is set in the user configuration, the `MCPLifecycleManager` initializes these connections at startup.

### Intent Routing and Tool Mapping

The router component in [`vulnclaw/mcp/router.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/mcp/router.py) translates natural language intents into concrete MCP tool calls. Lines 24–33 define Burp-specific mappings where phrases like `抓包` (capture traffic) and `修改数据包` (modify request) trigger calls to `get_proxy_http_history` and `send_http1_request` respectively.

This mapping extends to Frida operations such as "hook signer," which the router directs to the `frida_mcp` server tools including `spawn`, `attach`, and `get_messages`.

## Configuring Burp Suite Integration

Burp Suite integration requires enabling the MCP server in VulnClaw's configuration and launching Burp with its MCP plugin active.

### Step 1: Enable Burp in Config

Edit your VulnClaw configuration file (typically `~/.vulnclaw/config.yaml`) to activate the Burp server:

```yaml
mcp:
  servers:
    burp:
      enabled: true
      transport: sse
      url: http://127.0.0.1:9876

```

The lifecycle manager reads this configuration during initialization via `MCPLifecycleManager.start_enabled_servers` in [`vulnclaw/mcp/lifecycle.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/mcp/lifecycle.py).

### Step 2: Start Burp MCP Server

Launch Burp Suite with the MCP plugin that exposes the SSE endpoint on port 9876. Once active, VulnClaw probes the connection using `_check_http_reachable` and discovers available tools via `_probe_sse_server`. The available Burp tools—including proxy history access, repeater functions, and scanner controls—are registered automatically through `_register_runtime_tools` (lines 1291–1297 in lifecycle.py).

### Step 3: Programmatic Usage

Invoke Burp tools directly through the Python API:

```python
from vulnclaw.cli.main import VulnClawCLI

cli = VulnClawCLI()
result = cli.run_tool(
    server="burp",
    tool="send_http1_request",
    arguments={
        "content": "GET /api/users HTTP/1.1\r\nHost: target.com\r\n\r\n"
    },
)
print(result["content"])  # Access response data

```

The return dictionary contains `ok`, `content`, `structured_content`, and `error_type` keys for programmatic error handling.

## Configuring Frida Integration

Frida integration follows the same MCP pattern, enabling dynamic instrumentation of mobile and desktop applications through the LLM interface.

### Step 1: Enable Frida MCP

Add the Frida server entry to your configuration:

```yaml
mcp:
  servers:
    frida_mcp:
      enabled: true
      transport: sse
      url: http://127.0.0.1:9877  # Adjust port as needed

```

The server definition lives conceptually alongside the Burp entry in [`vulnclaw/config/schema.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/config/schema.py), utilizing the same schema validation for tool discovery.

### Step 2: Runtime Instrumentation Workflow

Start `frida-server` on your target device or host, then launch the Frida-MCP server. VulnClaw automatically discovers tools including `check_frida_status`, `list_applications`, `spawn`, `attach`, and `get_messages`.

A typical workflow involves checking server status, spawning a target process, and retrieving messages from your instrumentation script:

```python
import asyncio
from vulnclaw.mcp.lifecycle import MCPLifecycleManager
from vulnclaw.config.schema import VulnClawConfig

async def instrument_app():
    cfg = VulnClawConfig.parse_file("~/.vulnclaw/config.yaml")
    
    async with MCPLifecycleManager(cfg) as mgr:
        # Verify Frida server connectivity

        await mgr.health_check("frida_mcp")
        
        frida_session = await mgr._get_or_create_session("frida_mcp")
        
        # List installed applications

        apps = await frida_session.call_tool(
            "list_applications", 
            arguments={}
        )
        
        # Spawn target process (com.example.app)

        await frida_session.call_tool(
            "spawn",
            arguments={"package": "com.example.app"}
        )
        
        # Retrieve Frida script output

        messages = await frida_session.call_tool(
            "get_messages",
            arguments={}
        )
        print(messages["content"])

asyncio.run(instrument_app())

```

## Lifecycle Management Deep Dive

The `MCPLifecycleManager` class in [`vulnclaw/mcp/lifecycle.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/mcp/lifecycle.py) orchestrates server connections. When VulnClaw starts, the manager executes `start_enabled_servers`, which iterates through the configuration and initializes each MCP connection.

For Burp specifically, the manager uses the `_call_burp` dispatch method (lines 1525–1529) to handle tool invocations. The system lazily loads tool lists upon first connection, caching the available methods to minimize latency on subsequent calls.

Health check operations verify reachability before routing requests, ensuring the LLM receives immediate feedback if an external tool becomes unavailable.

## Practical Integration Examples

Enable both servers via the CLI helper and run interactive sessions:

```bash

# One-time configuration

vulnclaw config set mcp.servers.burp.enabled true
vulnclaw config set mcp.servers.frida_mcp.enabled true

# Start interactive mode

vulnclaw

```

In the interactive chat:

- **"抓包"** triggers `get_proxy_http_history` via Burp
- **"修改数据包"** opens the request editor through Burp's repeater
- **"hook signer"** initiates Frida instrumentation via `attach` and `spawn`

## Summary

- **MCP Architecture**: VulnClaw uses the Modular Control Protocol to abstract external tools, with configurations in [`vulnclaw/config/schema.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/config/schema.py) and routing logic in [`vulnclaw/mcp/router.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/mcp/router.py).
- **Burp Integration**: Enable via `mcp.servers.burp.enabled`, ensure the MCP plugin runs on `127.0.0.1:9876`, and use intents like `抓包` to trigger `get_proxy_http_history`.
- **Frida Integration**: Configure `frida_mcp` server settings, start `frida-server`, and access tools including `list_applications`, `spawn`, and `get_messages` through the lifecycle manager.
- **Lifecycle Management**: `MCPLifecycleManager` handles startup, health checks, tool discovery via `_probe_sse_server`, and registration through `_register_runtime_tools`.

## Frequently Asked Questions

### What transport protocols does VulnClaw support for external tool integration?

VulnClaw supports **SSE (Server-Sent Events)** and **stdio** transports as defined in the MCP server configuration. Burp Suite typically uses SSE over HTTP at `127.0.0.1:9876`, while Frida can operate via SSE or stdio depending on whether you run the MCP server as a persistent service or a subprocess.

### Where does VulnClaw store the mapping between user intents and specific tool functions?

Intent-to-tool mappings are defined in [`vulnclaw/mcp/router.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/mcp/router.py). For example, the Chinese phrase `抓包` maps to Burp's `get_proxy_http_history` tool, while `修改数据包` routes to `send_http1_request`. These mappings allow the LLM to translate natural language requests into concrete MCP tool calls without hard-coding API specifics in the prompts.

### How do I troubleshoot connection failures between VulnClaw and Burp Suite?

First, verify the Burp MCP plugin is active and listening on the configured port (default 9876). VulnClaw's `MCPLifecycleManager` runs `_check_http_reachable` during startup to validate connections. Check the `ok` and `error_type` fields in the tool response dictionary, or call `await mgr.health_check("burp")` programmatically to diagnose connectivity issues before attempting tool execution.

### Can I integrate tools other than Burp Suite and Frida using the same method?

Yes. Any tool implementing the MCP specification can be integrated by adding a new entry to `BUILTIN_MCP_SERVERS` in [`vulnclaw/config/schema.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/config/schema.py) or via user configuration. The `MCPLifecycleManager` automatically discovers available tools through `_probe_sse_server` or `_probe_http_server`, making the system extensible to custom security scanners, debuggers, or fuzzing frameworks.