# MCP Server Integration Architecture in the Reverse‑Skill Framework: A Layered Bridge Design

> Explore the reverse skill framework's MCP server integration architecture. Discover how this layered bridge design connects AI agents and security tools via JSON-RPC 2.0 for automated discovery and invocation.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: architecture
- Published: 2026-08-18

---

**The *reverse‑skill* repository implements a four‑layer modular architecture where MCP servers act as a JSON‑RPC 2.0 tool‑bridge layer between AI agents and security utilities, enabling automatic discovery, registration, and invocation of tools like Burp Suite and jshookmcp.**

This architecture treats **MCP (Model Context Protocol) servers** as interchangeable adapters that expose complex reverse‑engineering tools through a standardized remote procedure call interface. According to the *reverse‑skill* source code, this design keeps skill logic platform‑agnostic while allowing any security tool to be integrated by publishing a new manifest.

## Four‑Layer System Architecture

The core system layout is defined in [[`docs/ARCHITECTURE.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/ARCHITECTURE.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/ARCHITECTURE.md) and organizes components into concentric sub‑systems:

- **Shared layer** – Platform‑agnostic skill definitions, routing logic, and documentation generators (`skills/`, `CTF‑Sandbox‑Orchestrator/`, `field‑journal/`)
- **Platform‑specific layer** – OS‑aware bootstrap scripts and installation manifests (`skills/scripts/`, `kali/`, `WINDOWS/`)
- **Tool‑Bridge (MCP) layer** – JSON‑RPC 2.0 endpoints wrapping each security tool (`burp-mcp-full/`, [`mcp-jshook.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/mcp-jshook.md) references)
- **Output layer** – Report generation and journal updates (`docs/`, `diagram‑generator/`)

The **MCP server** sits exclusively within the *Tool‑Bridge* layer. When a skill requires concrete capabilities—such as capturing HTTP traffic or hooking JavaScript—the runtime queries the **tool‑index** to locate the appropriate MCP bridge.

## MCP Integration Workflow: Six Steps

### Step 1: Discovery

The `ToolIndex` component scans the filesystem for executable MCP bridges. For example, it locates [`mcp-bridge.js`](https://github.com/zhaoxuya520/reverse-skill/blob/main/mcp-bridge.js) for Burp Suite or `jshookmcp` binaries. Each discovery entry records:

- Host and port
- Authentication token
- Tool capability tags

### Step 2: Registration

Each bridge publishes a **tool‑manifest** ([`.omc/tool-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/.omc/tool-manifest.json)) declaring its RPC method names and parameter schemas. A Burp Suite manifest might expose `proxy_history`, `intruder_attack`, or `register_proxy_rule`.

### Step 3: Client Configuration

AI clients add the bridge to their `mcpServers` JSON configuration. The [[`burp-mcp-full/README.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/burp-mcp-full/README.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/burp-mcp-full/README.md) provides this canonical example:

```json
{
  "mcpServers": {
    "burpsuite": {
      "command": "node",
      "args": ["<repo-root>/burp-mcp-full/mcp-bridge.js"]
    }
  }
}

```

### Step 4: Authorization

Bridges generate random tokens stored in `~/.burp-mcp-token`, with override support via `BURP_MCP_TOKEN` environment variable or `-Dburp.mcp.token` JVM property. The client library automatically attaches these as `Bearer` headers.

### Step 5: Invocation

Skills invoke tools through plain JSON‑RPC calls:

```json
POST http://127.0.0.1:9876
{
  "tool": "proxy_history",
  "params": { "limit": 10, "url_filter": "personalblog" }
}

```

The bridge forwards requests to native tools (Java, Node, Python) and returns normalized JSON responses.

### Step 6: Error Handling and Fallback

If connection fails, the MCP client receives a structured `CONNECT_ERROR`. The bootstrap flow—driven by [`bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/bootstrap-manifest.json)—can then reinstall or reconfigure the missing server.

## MCP Server Types in the Ecosystem

| MCP Server | Domain | Exposed Capabilities |
|------------|--------|----------------------|
| **BurpSuite MCP** | Web proxy analysis | `proxy_history`, `intruder_attack`, `scan`, `register_proxy_rule` ([source](https://github.com/zhaoxuya520/reverse-skill/blob/main/burp-mcp-full/README.md)) |
| **jshookmcp** | JS runtime / CDP / Hook | Browser automation, Frida memory, WASM reverse, source‑map reconstruction ([source](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/pentest-tools/src-hunter/references/tools/mcp-jshook.md)) |
| **anything‑analyzer MCP** | General browser + HTTP | Capture/replay on port 23816 |
| **MetasploitMCP, HexStrike AI, pentestMCP** | Exploit frameworks | 150+ security utilities per [[`docs/platforms/kali.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/platforms/kali.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/platforms/kali.md) |

All servers share the same JSON‑RPC contract, making them interchangeable at the skill level.

## Practical Code Examples

### Registering the Burp Suite MCP Bridge

```json
{
  "mcpServers": {
    "burpsuite": {
      "command": "node",
      "args": ["<repo-root>/burp-mcp-full/mcp-bridge.js"]
    }
  }
}

```

*(Source: [[`burp-mcp-full/README.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/burp-mcp-full/README.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/burp-mcp-full/README.md), lines 49–58)*

### Querying Proxy History via MCP

```http
POST http://127.0.0.1:9876
Content-Type: application/json
Authorization: Bearer <token>

{
  "tool": "proxy_history",
  "params": { "limit": 10, "url_filter": "example.com" }
}

```

*(Source: [[`burp-mcp-full/README.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/burp-mcp-full/README.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/burp-mcp-full/README.md), lines 21–24)*

### Launching jshookmcp in Search Mode

```bash
export JSHOOK_BASE_PROFILE=search   # use "full" for complete toolset

npx -y @jshookmcp/jshook@0.3.4      # stdio mode MCP server

```

*(Source: [[`docs/platforms/kali.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/platforms/kali.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/platforms/kali.md), lines 44–51)*

### Skill‑Level jshookmcp Activation

Skills activate specific tool subsets before executing workflows:

```json
{
  "tool": "mcp__jshook__activate_tools",
  "params": ["js_obfuscation"]
}

```

*(Source: [[`skills/pentest-tools/src-hunter/references/playbooks/xss.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/pentest-tools/src-hunter/references/playbooks/xss.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/pentest-tools/src-hunter/references/playbooks/xss.md), line 307)*

The `mcp__jshook__*` naming convention prefixes all jshookmcp tool calls for routing purposes.

## Key Implementation Files

| File | Purpose |
|------|---------|
| [[`docs/ARCHITECTURE.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/ARCHITECTURE.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/ARCHITECTURE.md) | High‑level system diagram with MCP bridge layer |
| [[`burp-mcp-full/mcp-bridge.js`](https://github.com/zhaoxuya520/reverse-skill/blob/main/burp-mcp-full/mcp-bridge.js)](https://github.com/zhaoxuya520/reverse-skill/blob/main/burp-mcp-full/mcp-bridge.js) | Node.js bridge implementation for Burp Suite |
| [[`burp-mcp-full/README.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/burp-mcp-full/README.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/burp-mcp-full/README.md) | Configuration, auth, and invocation documentation |
| [[`skills/pentest-tools/src-hunter/references/tools/mcp-jshook.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/pentest-tools/src-hunter/references/tools/mcp-jshook.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/pentest-tools/src-hunter/references/tools/mcp-jshook.md) | jshookmcp tool index and profile definitions |
| [[`skills/scripts/bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-manifest.json)](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-manifest.json) | Automatic MCP server installation manifest |
| [[`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md) | Task‑to‑MCP server routing matrix |

## Summary

- **Modular bridge design**: MCP servers isolate tool complexity behind a unified JSON‑RPC 2.0 interface
- **Automatic lifecycle**: Discovery, registration, authorization, and fallback are handled by the bootstrap system
- **Cross‑platform portability**: Same skill code runs across Kali Linux, Windows, and macOS via platform‑specific manifests
- **Extensible contract**: New tools integrate by publishing a [`tool-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-manifest.json) and exposing standard RPC methods
- **Security‑first auth**: Token‑based authentication with environment and JVM property overrides

## Frequently Asked Questions

### What protocol does the MCP server integration use?

The *reverse‑skill* framework uses **JSON‑RPC 2.0** over HTTP for all MCP communications. Each bridge exposes tools as RPC methods with typed parameter schemas, enabling language‑agnostic invocation from any AI client.

### How does the framework handle missing or failed MCP servers?

The **Bootstrap** flow—triggered by `CONNECT_ERROR` responses—can automatically reinstall or reconfigure missing servers. This is driven by [`bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/bootstrap-manifest.json) and `bootstrap-reverse.ps1`, which reference the required tool versions and installation commands.

### Can multiple MCP servers run simultaneously?

Yes. The `ToolIndex` maintains a registry of all discovered bridges, and the [[`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md) matrix selects the appropriate server based on task type. For example, a single workflow might call `burpsuite` for proxy analysis and `jshookmcp` for JavaScript instrumentation.

### What authentication mechanism protects MCP endpoints?

Each bridge generates a **random Bearer token** stored in `~/.burp-mcp-token` (or tool‑specific equivalents). Clients read this token automatically and attach it to every request. Tokens can be overridden via environment variables or JVM system properties for containerized deployments.