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

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.

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
MCP Bridge (mcp-bridge.js)	Node.js shim converting stdio JSON-RPC to HTTP API, with automatic token injection	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
Tool Index (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, 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
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

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:

{
  "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:

# 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 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

{
  "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.

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:

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

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

As implemented in resolveToken() within 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	Node bridge normalizing HTTP-based MCP calls to stdio JSON-RPC
burp-mcp-full/README.md	Build, load, and authentication instructions for Burp MCP
kali/mcp-kali-example.json	Sample registry with Burp, Metasploit, HexStrike configurations
skills/tool-index.md	Auto-generated tool catalogue including MCP-exposed utilities
skills/MASTER-ROUTING.md	Core routing matrices for intent-to-tool mapping
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 handles protocol translation and automatic authentication token injection
• Refresh scripts discover servers and auto-generate skills/tool-index.md for the router
• Natural language prompts route through 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 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. 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 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}