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

> Discover how MCP integrates with the reverse-skill routing system. Learn how MCP servers are discovered, registered, and verified for efficient routing engine execution in this technical guide.

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

---

**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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/bootstrap-reverse.sh):

```bash

# 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/refresh-tool-index.sh):

```bash
$ 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json)—the authoritative routing matrix—when evaluating skill execution. Each routing entry may specify an MCP-based capability.

Sample routing configuration:

```json
// 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):

```python
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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/bootstrap-reverse.sh)) — Detects `--mcp-host`, writes to client config files
2. **Index** ([`refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/refresh-tool-index.sh)) — Rebuilds capability table from configs and live checks
3. **Route** ([`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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:

```bash

# 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh) | Index regeneration | Reads `~/.claude/mcp.json` and `~/.codex/config.toml` |
| [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) | Authoritative routing matrix | Maps skills to MCP capability names |
| [`docs/ARCHITECTURE.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/ARCHITECTURE.md) | System architecture | **系统架构图** showing ToolOK → Bootstrap flow |
| [`skills/scripts/test-client-neutral-bootstrap.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/test-client-neutral-bootstrap.sh) script specifically validates that the routing engine can execute skills regardless of which client originally registered the MCP.