How MCP Integrates with the reverse-skill Routing System: A Complete Technical Guide

The reverse-skill framework treats MCP (Modular Capability Provider) servers as first-class capabilities that are discovered, registered, and verified before routing engine execution.

The reverse-skill repository implements a sophisticated capability-based routing system where MCP integration follows a three-stage detect-register-verify pattern. This architecture enables dynamic skill execution gated by real-time MCP server availability, as defined in the routing matrix and capability index.

---

What Is MCP in the reverse-skill Context?

MCP (Modular Capability Provider) represents external AI service endpoints—such as Claude Desktop or Codex—that expose tools through a standardized protocol. In reverse-skill, these are not hardcoded dependencies but discoverable capabilities that the routing engine evaluates at runtime.

The framework supports multiple MCP clients:

• Claude Desktop — configuration stored in ~/.claude/mcp.json
• Codex — configuration stored in ~/.codex/config.toml

---

Stage 1: MCP Discovery and Registration

The bootstrap scripts handle initial MCP server registration. Located at skills/scripts/bootstrap-reverse.sh (lines 29-58), these scripts scan for MCP configuration files and inject server definitions when a target host is provided via --mcp-host.

Key registration logic from bootstrap-reverse.sh:

# Extracted from lines 29-58 of bootstrap-reverse.sh

# When --mcp-host is detected, the script writes a JSON payload

# to $HOME/.claude/mcp.json or $HOME/.codex/config.toml

if [[ -n "$MCP_HOST" ]]; then
    # Construct registration payload with host and port

    mcp_payload='{"host":"'"${MCP_HOST%%:*}"'","port":'${MCP_HOST##*:}'}'
    # Merge into existing configuration or create new

    python3 - "$CONFIG_PATH" "$MCP_NAME" "$mcp_payload" <<'PY'
import sys, json
cfg_path, name, payload = sys.argv[1], sys.argv[2], json.loads(sys.argv[3])
data = {}
try:
    with open(cfg_path) as f: data = json.load(f)
except FileNotFoundError: pass
data[name] = payload
with open(cfg_path, 'w') as f: json.dump(data, f, indent=2)
PY
fi

This registration makes the MCP server visible to the reverse-skill ecosystem without requiring manual configuration edits.

---

Stage 2: Capability Indexing with tool-index

Once registered, MCP servers are indexed by the tool-index generator (skills/scripts/refresh-tool-index.sh). This script reads bootstrap manifests and MCP configuration files to produce a capability table defined in skills/tool-index.md.template.

The generated table includes these MCP-specific columns:

Column	Meaning
MCP 已注册	MCP server configuration exists in client config file
服务在线	TCP connectivity to the MCP host:port succeeds
MCP HTTP	HTTP handshake with MCP endpoint returns valid response
Ready	All criteria met; skill can execute

Example output from refresh-tool-index.sh:

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

| 能力 | 工具可用 | Ready | MCP 已注册 | 服务在线 | MCP HTTP |
|------|----------|-------|-----------|----------|----------|
| anything-analyzer | ✅ | ✅ | ✅ | ✅ | ✅ |
| jshookmcp | ✅ | ✅ | ✅ | ✅ | ⚠️ |
| reqable-mcp | ❌ | ❌ | ❌ | — | — |

In this example, jshookmcp shows a warning (⚠️) for MCP HTTP—indicating the server is registered and reachable, but the HTTP handshake produced a non-200 response.

---

Stage 3: Routing Decision Engine

The routing engine consults skills/config/routing.json—the authoritative routing matrix—when evaluating skill execution. Each routing entry may specify an MCP-based capability.

Sample routing configuration:

// skills/config/routing.json (excerpt)
{
  "skills": {
    "javascript-analysis": {
      "capability": "jshookmcp",
      "fallback": "bootstrap-jshook"
    },
    "request-inspection": {
      "capability": "reqable-mcp",
      "fallback": "bootstrap-reqable"
    },
    "anything-llm-query": {
      "capability": "anything-analyzer",
      "fallback": null
    }
  }
}

The routing logic implements this decision flow (extracted from the router implementation):

def can_execute(skill_id: str) -> bool:
    """
    Determine if a skill can execute based on MCP readiness.
    Mirrors the actual router logic in reverse-skill.
    """
    # Load capability index from tool-index.md

    caps = load_capability_index()  # Parsed from generated markdown

    
    skill_config = ROUTING_MATRIX['skills'].get(skill_id)
    if not skill_config:
        raise SkillNotFoundError(f"Unknown skill: {skill_id}")
    
    mcp_name = skill_config['capability']
    mcp_cap = caps.get(mcp_name)
    
    # Gate 1: MCP must be registered

    if not mcp_cap or not mcp_cap.get('MCP 已注册'):
        trigger_bootstrap(mcp_name, skill_config.get('fallback'))
        return False
    
    # Gate 2: Service must be online

    if not mcp_cap.get('服务在线'):
        log.warning(f"MCP {mcp_name}: registered but unreachable")
        return False
    
    # Gate 3: Ready state (includes HTTP handshake)

    return mcp_cap.get('Ready', False)

This ToolOK → Bootstrap path is visualized in the system architecture diagram (docs/ARCHITECTURE.md), showing how routing decisions hinge on MCP registration status.

---

Complete Integration Flow

The three stages operate as a continuous lifecycle:

1. Bootstrap (bootstrap-reverse.sh) — Detects --mcp-host, writes to client config files
2. Index (refresh-tool-index.sh) — Rebuilds capability table from configs and live checks
3. Route (routing.json + engine) — Uses table to gate skill execution, triggers re-bootstrap if needed

---

Practical: Register and Verify an MCP Server

Complete workflow for adding a new MCP server to reverse-skill:

# Step 1: Register the MCP server

./skills/scripts/bootstrap-reverse.sh --mcp-host=127.0.0.1:23816 --name=demo-mcp

# Step 2: Refresh capability index to detect registration

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

# Step 3: Verify in routing (pseudo-execution check)

./skills/scripts/test-client-neutral-bootstrap.sh --check-ready=demo-mcp

The test-client-neutral-bootstrap.sh script specifically validates that MCP registration works across Claude and Codex clients without client-specific assumptions.

---

Key Files and Their Roles

File	Purpose	Critical Lines/Sections
skills/scripts/bootstrap-reverse.sh	MCP host registration	Lines 29-58: JSON payload construction and config file writing
skills/scripts/bootstrap-reverse.ps1	Windows equivalent of bootstrap	PowerShell implementation of registration logic
skills/tool-index.md.template	Capability table schema	Defines MCP 已注册, 服务在线, MCP HTTP, Ready columns
skills/scripts/refresh-tool-index.sh	Index regeneration	Reads ~/.claude/mcp.json and ~/.codex/config.toml
skills/config/routing.json	Authoritative routing matrix	Maps skills to MCP capability names
docs/ARCHITECTURE.md	System architecture	系统架构图 showing ToolOK → Bootstrap flow
skills/scripts/test-client-neutral-bootstrap.sh	Integration testing	Validates client-neutral MCP detection

---

Summary

• MCP servers are capabilities, not fixed dependencies—reverse-skill treats them as dynamically discoverable resources
• Three-stage integration: bootstrap registration → tool-index verification → routing engine gating
• Registration targets ~/.claude/mcp.json and ~/.codex/config.toml via bootstrap-reverse.sh (lines 29-58)
• Capability state is tracked in four columns: MCP registered, service online, HTTP valid, and final Ready status
• Routing decisions in routing.json reference MCP names; execution fails fast to bootstrap if capabilities are missing

---

Frequently Asked Questions

What happens if an MCP server is registered but offline?

The 工具可用 (tool available) and 服务在线 (service online) checks in the tool-index will fail. The routing engine receives Ready: false for that capability, and if a fallback is defined in routing.json, the bootstrap script triggers re-registration or installation.

Can reverse-skill work without any MCP servers registered?

Yes—the framework operates on a capability-gated model. Skills without MCP dependencies execute directly. For MCP-dependent skills, the router returns a clear "capability missing" state, enabling graceful degradation or user-directed bootstrap.

How does the tool-index detect MCP HTTP handshake failures?

The refresh-tool-index.sh script performs an HTTP health check to the registered host:port endpoint. A non-200 response or timeout produces the ⚠️ warning in the MCP HTTP column, distinguishing between "registered but broken" versus "not registered at all."

Is MCP registration client-specific or shared across Claude and Codex?

Registration is client-aware but capability-unified. The bootstrap script writes to the appropriate config file based on detected client installation, but both entries appear in the same capability index. The test-client-neutral-bootstrap.sh script specifically validates that the routing engine can execute skills regardless of which client originally registered the MCP.

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