# How to Integrate External MCP Servers and Tools into reverse-skill's Skill Ecosystem

> Integrate external MCP servers and tools into reverse-skill easily. Discover how to register, refresh, and use JSON-RPC bridges for seamless AI agent request routing.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: how-to-guide
- Published: 2026-08-05

---

**Integrating external MCP servers into reverse-skill involves registering them in a JSON configuration file, refreshing the tool index, and letting the skill router automatically discover and route AI agent requests via JSON-RPC bridges.**

The reverse-skill framework treats every external **MCP** (Modular Command Protocol) server as a first-class tool provider, enabling AI agents like Claude Code or Cursor to invoke security tools through a unified interface. This guide walks through the architecture, configuration files, and step-by-step integration process based on the actual source code in [zhaoxuya520/reverse-skill](https://github.com/zhaoxuya520/reverse-skill).

## Architecture of reverse-skill's MCP Integration

Understanding how components interact helps you debug and extend the system correctly.

| Component | Purpose | Reference |
|-----------|---------|-----------|
| **MCP Server** | Any executable speaking the MCP JSON-RPC protocol (Burp MCP, Metasploit MCP, HexStrike AI, etc.) | [`burp-mcp-full/README.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/burp-mcp-full/README.md) |
| **MCP Bridge ([`mcp-bridge.js`](https://github.com/zhaoxuya520/reverse-skill/blob/main/mcp-bridge.js))** | Node.js shim converting stdio JSON-RPC to HTTP API, with automatic token injection | [`burp-mcp-full/mcp-bridge.js`](https://github.com/zhaoxuya520/reverse-skill/blob/main/burp-mcp-full/mcp-bridge.js) |
| **MCP Configuration (`*.json`)** | JSON registry of available MCP servers with commands, arguments, and environment variables | [`kali/mcp-kali-example.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/mcp-kali-example.json) |
| **Tool Index ([`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md))** | Auto-generated catalogue mapping tool names to MCP server endpoints | Generated by refresh scripts |
| **Skill Router** | Core decision engine mapping user tasks to tools via the tool index | [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md), [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md) |

When an AI agent requests a capability like "analyze Burp proxy history", the **skill router** follows this flow:

1. Looks up `burp_proxy_history` in [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md)
2. Identifies the providing MCP server (e.g., `burp-mcp-full` bridge)
3. Sends a JSON-RPC request over stdio or HTTP
4. Returns the JSON response to the agent

## Step-by-Step Integration Process

### 1. Deploy the MCP Server

For Burp Suite integration:
- Build and load `burp-mcp-full.jar` following the Quick Start in [`burp-mcp-full/README.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/burp-mcp-full/README.md)

For other tools:
- Install the server binary (e.g., `apt install metasploitmcp`, `npm i -g hexstrike-ai`)

### 2. Add a Server Definition

Create or edit a JSON file under `kali/` or your preferred path. Each server entry lives under the `mcpServers` key:

```json
{
  "mcpServers": {
    "my-http-scanner": {
      "command": "node",
      "args": ["/opt/http-scanner/mcp-server.js"],
      "env": {
        "SCANNER_API_KEY": "<your-api-key>"
      },
      "_comment": "Custom HTTP scanner exposing MCP tools like http_scan and http_crawl."
    }
  }
}

```

The router reads any `.json` file in the repository root or `kali/` directory.

### 3. Refresh the Tool Index

Run the platform-specific discovery script to populate [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md):

```bash

# Linux / macOS

bash skills/scripts/refresh-tool-index.sh

# Kali

bash kali/scripts/refresh-tool-index.sh

```

These scripts execute each `command` defined in your JSON configurations, capture the `/tools` endpoint output, and write the resulting tool definitions.

### 4. Verify Registration

Open [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) and confirm your new tools appear with their designated prefix (e.g., `burp_`, `nmap_`).

### 5. Use in AI Prompts

Once registered, invoke tools through natural language:

```

Analyze the last 20 entries of the Burp proxy history and highlight any URLs containing "login".

```

The router translates this to `burp_proxy_history`, forwards via the MCP bridge, and returns filtered results.

## Code Examples and Implementation Details

### Example 1: Registering an Nmap MCP Server

```json
{
  "mcpServers": {
    "nmap-mcp": {
      "command": "nmap-mcp",
      "args": ["--port", "4444"],
      "_comment": "Nmap MCP wrapper exposing nmap_scan and nmap_host_detail."
    }
  }
}

```

This pattern follows the structure in [`kali/mcp-kali-example.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/mcp-kali-example.json).

### Example 2: Complex Tool Invocation Flow

Consider this agent prompt:

```

Please run an Intruder numeric-range attack against https://test.example.com/api?id=@@ from 0 to 9999, using 6-digit padding, and return the first successful response.

```

Behind the scenes in [`mcp-bridge.js`](https://github.com/zhaoxuya520/reverse-skill/blob/main/mcp-bridge.js):

1. Router resolves `intruder_attack` → `burp_intruder_attack`
2. Bridge builds payload: `{"tool":"intruder_attack","params":{...}}`
3. HTTP POST to `http://127.0.0.1:9876/`
4. Burp MCP returns attack results as JSON

The bridge's `resolveToken()` function handles authentication automatically.

### Example 3: Secure Token Management

```bash
export BURP_MCP_TOKEN=$(cat ~/.burp-mcp-token)
node burp-mcp-full/mcp-bridge.js

```

As implemented in `resolveToken()` within [`mcp-bridge.js`](https://github.com/zhaoxuya520/reverse-skill/blob/main/mcp-bridge.js), the bridge reads `~/.burp-mcp-token` and injects `Authorization: Bearer <token>` on every request. Never hardcode tokens in your JSON configuration files.

## Key Configuration Files Reference

| File | Role |
|------|------|
| [`burp-mcp-full/mcp-bridge.js`](https://github.com/zhaoxuya520/reverse-skill/blob/main/burp-mcp-full/mcp-bridge.js) | Node bridge normalizing HTTP-based MCP calls to stdio JSON-RPC |
| [`burp-mcp-full/README.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/burp-mcp-full/README.md) | Build, load, and authentication instructions for Burp MCP |
| [`kali/mcp-kali-example.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/mcp-kali-example.json) | Sample registry with Burp, Metasploit, HexStrike configurations |
| [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) | Auto-generated tool catalogue including MCP-exposed utilities |
| [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) | Core routing matrices for intent-to-tool mapping |
| [`skills/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh) | Discovery script populating the tool index |

## Summary

- **MCP servers** integrate as first-class citizens through JSON configuration files under `kali/` or root
- **[`mcp-bridge.js`](https://github.com/zhaoxuya520/reverse-skill/blob/main/mcp-bridge.js)** handles protocol translation and automatic authentication token injection
- **Refresh scripts** discover servers and auto-generate [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) for the router
- **Natural language prompts** route through [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md) to invoke the correct MCP-backed tool
- Environment-specific tokens belong in shell exports or `~/.` files, never committed to repository JSON

## Frequently Asked Questions

### How does reverse-skill discover new MCP servers without manual code changes?

The [`refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/refresh-tool-index.sh) scripts execute each `command` defined in your JSON configuration files, call the server's `/tools` endpoint, and append discovered tools to [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md). The skill router reads this markdown file dynamically, so no code recompilation or manual registration in routing logic is required.

### Can I use environment variables for sensitive credentials like API keys?

Yes. The JSON configuration supports an `env` object where you define key-value pairs. For tokens that shouldn't appear in files at all, set shell environment variables before running the bridge or router—the bridge's `resolveToken()` function in [`mcp-bridge.js`](https://github.com/zhaoxuya520/reverse-skill/blob/main/mcp-bridge.js) specifically handles external token files like `~/.burp-mcp-token`.

### What protocols does reverse-skill support for MCP communication?

The primary path uses **JSON-RPC over stdio** converted to HTTP via [`mcp-bridge.js`](https://github.com/zhaoxuya520/reverse-skill/blob/main/mcp-bridge.js). The bridge enables any standard MCP client to communicate with HTTP-based MCP servers (like Burp's extension) without custom protocol implementations. Pure stdio servers work directly without the bridge shim.