# How to Integrate a New MCP Server with the Reverse-Skill Routing System

> Integrate a new MCP server with the reverse skill routing system. Learn to register servers, update tools, and extend routing rules for seamless integration.

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

---

**To integrate a new MCP server, register it in the bootstrap script to write to `~/.claude/mcp.json`, update the tool index to expose capabilities, optionally extend [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) for new skills, and run verification scripts to ensure coherence.**

The reverse-skill repository by zhaoxuya520 implements a unified routing architecture where [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) serves as the **single source of truth** for all skill resolution. When you need to integrate a new MCP (Multi-Channel Protocol) server as an execution backend, the system requires specific updates across bootstrap scripts, tool indices, and routing configuration files to maintain the integrity of the skill matrix. This guide walks through the exact implementation steps using the actual source file paths and shell scripts found in the repository.

## Understanding the Routing Architecture

Before adding a new MCP server, understand that the reverse-skill system resolves every user request through [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json). The **routing matrix** defined in this JSON file determines which sub-skill ([`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md)) handles each request based on keyword matching. MCP servers provide the execution capabilities that these sub-skills invoke, but they must be registered in two places: the user's MCP configuration file (`~/.claude/mcp.json`) and the repository's internal tool index.

The human-readable view of this matrix lives in [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md), which is auto-generated from [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) and displays MCP registration status columns including "Ready", "MCP 已注册", and "服务在线".

## Step 1: Register the MCP Server in the Bootstrap Script

The first integration point is [`skills/scripts/bootstrap-reverse.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-reverse.sh) (or `bootstrap-reverse.ps1` for PowerShell environments), which writes the server definition into the user's MCP configuration. According to the source code at lines 29-71, the script constructs a JSON payload and uses an inline Python script to safely inject the configuration into `~/.claude/mcp.json`.

Execute the registration by defining your server parameters and running the bootstrap logic:

```bash
#!/usr/bin/env bash
MCP_CONFIG_PATH="${CLAUDE_MCP_CONFIG:-$HOME/.claude/mcp.json}"
SERVER_NAME="my-mcp"
SERVER_PORT=12345
SERVER_URL="http://localhost:${SERVER_PORT}"

python3 - "$MCP_CONFIG_PATH" "$SERVER_NAME" <<'PY'
import json, sys
config_path = sys.argv[1]
name = sys.argv[2]

new_server = {
  "name": name,
  "port": 12345,
  "url": "http://localhost:12345",
  "capabilities": ["my-capability"]
}

# Load existing config and merge

try:
    with open(config_path, 'r') as f:
        config = json.load(f)
except FileNotFoundError:
    config = {"mcpServers": {}}

config["mcpServers"][name] = new_server

with open(config_path, 'w') as f:
    json.dump(config, f, indent=2)
PY

echo "✅ MCP server '$SERVER_NAME' registered in $MCP_CONFIG_PATH"

```

This ensures the **MCP server metadata**—including name, port, URL, and capabilities—is available to the Claude Desktop environment or other MCP clients.

## Step 2: Update the Tool Index for Capability Discovery

Next, expose the MCP server's capabilities to the routing matrix UI by modifying [`skills/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh). Around line 220, this script generates the capability table that powers the `[Capability]` view in [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md).

Add a new row to the tool index using the pipe-delimited format:

```bash

# Inside refresh-tool-index.sh, append the capability row

echo "my-mcp|my-skill|My MCP Server|npx|npx --version|" >> "$TOOL_INDEX_TMP"

```

The columns represent: `server_id|skill_dir|display_name|command_type|version_command|`. Updating this file ensures the new MCP appears in the capability inventory alongside its "Ready" and service online status indicators.

## Step 3: Extend the Routing Configuration (Optional)

If your MCP server introduces a brand-new functional area rather than extending an existing skill, you must add a **route object** to [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json). Each route uses a unique identifier (e.g., "R41") and specifies the target skill file, display label, and keyword triggers.

Insert the new route following this structure:

```json
{
  "R41": {
    "label": "My New Capability",
    "skill": "my-new-skill/SKILL.md",
    "keywords": [
      { "must": "mynew|awesome|tool", "note": "Triggers the new MCP-backed skill" }
    ]
  }
}

```

After defining the route object, update the `"priority"` array in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) to include "R41" at the appropriate position. The router evaluates routes in the order specified by this array, so place higher-specificity matches before generic fallbacks.

## Step 4: Execute Bootstrap and Verify Integration

With the configuration updated, run the bootstrap script to persist the MCP registration:

```bash

# Bash environments

bash skills/scripts/bootstrap-reverse.sh

# PowerShell environments

powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/bootstrap-reverse.ps1

```

Finally, validate that the integration maintains routing coherence through the CI-style verification suite:

```bash

# Verify JSON and markdown matrix parity

powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/verify-routing-coherence.ps1

# Execute full routing test suite (162+ cases)

powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/test-routing.ps1

```

A clean execution confirms that [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) and the generated [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md) remain synchronized, and that the new MCP server is correctly registered without breaking existing routing rules.

## Summary

Integrating a new MCP server into the reverse-skill ecosystem requires coordinated updates across four components:

- **Bootstrap scripts** ([`bootstrap-reverse.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/bootstrap-reverse.sh) or `.ps1`) write server definitions to `~/.claude/mcp.json`
- **Tool index** ([`refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/refresh-tool-index.sh)) exposes capabilities in the routing matrix UI
- **Routing JSON** ([`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json)) optionally adds new skill routes with keyword triggers
- **Verification scripts** (`verify-routing-coherence.ps1`, `test-routing.ps1`) ensure system integrity across 162+ test cases

By following this workflow, you maintain the repository's single-source-of-truth architecture while extending execution capabilities through MCP server integration.

## Frequently Asked Questions

### How does the reverse-skill repository handle MCP server conflicts?

The [`bootstrap-reverse.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/bootstrap-reverse.sh) script uses an inline Python utility to merge new server configurations into the existing `~/.claude/mcp.json` structure without overwriting unrelated entries. If a server with the same name exists, the script typically updates its definition, ensuring the latest endpoint and capability specifications take precedence while preserving other registered servers.

### Where is the routing priority defined if multiple skills match a query?

The `"priority"` array in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) defines the exact evaluation order for route matching. The system checks routes sequentially using this array, so you control precedence by positioning specific routes (like "R41" for your new MCP-backed skill) before more generic fallbacks. This declarative approach prevents routing collisions through explicit ordering rather than heuristic resolution.

### Why must I update both the tool index and the bootstrap script?

The **bootstrap script** handles runtime MCP client configuration (writing to `~/.claude/mcp.json`), while the **tool index** ([`refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/refresh-tool-index.sh)) generates the static capability documentation viewed in [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md). The bootstrap makes the server executable; the tool index makes it visible in the routing matrix with status columns like "MCP 已注册" and "服务在线". Both steps are necessary for complete integration into the reverse-skill ecosystem.

### What happens if I skip the verification scripts?

Running `verify-routing-coherence.ps1` and `test-routing.ps1` validates that your changes to [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) syntax are valid and that the generated markdown matrix reflects the updated routing logic. Skipping these checks risks desynchronization between the JSON source of truth and the human-readable documentation, potentially causing routing failures or orphaned skill references in production environments according to the repository's CI standards.