How to Integrate Custom MCP Servers into Agent Reach

To integrate a custom MCP server into Agent Reach, implement an MCP-compliant server, register it with the mcporter CLI, and optionally create a channel class in agent_reach/channels/ to enable diagnostic visibility.

Agent Reach serves as a glue layer that allows AI agents to install, diagnose, and route to native tools across internet platforms via the Multi-Channel Protocol (MCP). While the framework ships with built-in channels like weibo.py and xiaohongshu.py that auto-register their MCP servers, you can integrate custom MCP servers for unsupported platforms by following the repository's established patterns for server implementation and registration.

Understanding Agent Reach's MCP Architecture

Agent Reach delegates MCP server lifecycle management to mcporter, a CLI registry that maps logical MCP names to executable server commands. The framework discovers available MCP servers through channel definitions in agent_reach/channels/, where each channel class inherits from the base Channel class defined in agent_reach/channels/base.py.

When you run the doctor command, Agent Reach invokes AgentReach().doctor_report() (implemented in agent_reach/core.py) to verify that registered MCP servers respond correctly. This architecture separates the transport protocol (MCP) from platform-specific logic, allowing you to add new capabilities without modifying core framework code.

Step-by-Step Integration Guide

Step 1: Implement Your MCP Server

Create a standalone MCP server that exports a Server instance with a name, tool list, and call_tool handler. The repository provides a reference implementation in agent_reach/integrations/mcp_server.py that exposes Agent Reach's own status tool.

Your server must conform to the MCP specification, exposing tools that mcporter can discover and invoke. The server can be written in Python or any language that implements the protocol.

Step 2: Register with mcporter

Once your server executable is ready, register it with the mcporter CLI to create the mapping between a logical name and your server command:

mcporter config add <mcp_name> --command "<path-to-your-server>"

After registration, verify the entry appears in the registry:

mcporter list

You can now invoke tools through the MCP layer using mcporter call <mcp_name>.<tool>(), which routes requests to your custom server.

Step 3: Create a Custom Channel Class (Optional)

To enable Agent Reach's diagnostic tools to recognize your MCP server and provide URL handling logic, create a new file in agent_reach/channels/ that inherits from Channel. This allows the doctor report to verify your server's health and exposes a can_handle(url) predicate for routing decisions.

Following the pattern established in agent_reach/channels/weibo.py, implement the required interface:

# agent_reach/channels/myplatform.py

from __future__ import annotations
import shutil
import subprocess
from .base import Channel

class MyPlatform(Channel):
    name = "myplatform"
    description = "MyPlatform – custom MCP‑enabled service"
    backends = ["myplatform-mcp"]   # Name used in mcporter registration

    def can_handle(self, url: str) -> bool:
        return url.startswith("https://myplatform.example.com/")

    def check(self, config=None):
        mcporter = shutil.which("mcporter")
        if not mcporter:
            return "error", "mcporter not installed"
        
        result = subprocess.run(
            [mcporter, "config", "list"], 
            capture_output=True, 
            text=True
        )
        if "myplatform" in result.stdout:
            return "ok", "myplatform‑mcp"
        return "warn", "myplatform MCP not configured"

Import this module in agent_reach/channels/__init__.py to auto-register it with the framework's channel discovery system.

Working Code Examples

Registering and Calling a Custom MCP Server

Assuming your server implementation lives in ./my_mcp_server.py:

# Install dependencies

pip install -e .

# Register the server with mcporter

mcporter config add myplatform --command "python -m my_mcp_server"

# Verify registration

mcporter list

# Output: myplatform

# Invoke a tool through the MCP layer

mcporter call myplatform.get_status()

Using the Built-in MCP Bridge

Agent Reach exposes its own diagnostic capabilities via an MCP bridge defined in agent_reach/integrations/mcp_server.py:

# Start the Agent Reach MCP server

python -m agent_reach.integrations.mcp_server

# Query status from any MCP client

mcporter call agent-reach.get_status()

This bridge allows external MCP clients to query Agent Reach's internal state without direct Python dependencies.

Verifying Integration with the Doctor Tool

After adding your custom channel file and reinstalling the package:

# Reinstall in editable mode to pick up new channel

pip install -e .

# Run diagnostics

python -m agent_reach.cli doctor

# Expected output includes:

# myplatform – MyPlatform – custom MCP‑enabled service → ok

The doctor command validates that mcporter is installed and that your MCP server appears in the configuration registry.

Summary

• Implement an MCP-compliant server following the specification and reference implementation in agent_reach/integrations/mcp_server.py.
• Register your server with mcporter config add to enable command routing through the CLI.
• Extend Agent Reach's diagnostic capabilities by creating a channel class in agent_reach/channels/ that implements can_handle() and check() methods.
• Verify integration using the built-in doctor command, which inspects all channels registered in agent_reach/channels/__init__.py.

Frequently Asked Questions

What is the role of mcporter in Agent Reach?

mcporter acts as the MCP registry and routing layer. It maintains a configuration mapping logical MCP names to executable server commands, allowing Agent Reach to discover and invoke tools from custom MCP servers without hardcoding paths or dependencies in the core framework.

Do I need to create a channel class to use a custom MCP server?

No, the channel class is optional but recommended. You can register and call custom MCP servers directly through mcporter without Agent Reach-specific integration. However, creating a channel in agent_reach/channels/ enables the doctor diagnostic tool to verify your server's health and allows Agent Reach to intelligently route URLs to your platform handler.

How does Agent Reach verify that my MCP server is functioning?

The doctor_report() method in agent_reach/core.py queries each channel's check() method. For MCP-enabled channels like the one shown in weibo.py, this involves running mcporter config list and verifying that the expected MCP name appears in the output, confirming the server is registered and executable.

Can I write my MCP server in a language other than Python?

Yes, MCP is protocol-based, not Python-specific. While Agent Reach and mcporter are implemented in Python, any executable that implements the MCP specification and communicates via the expected transport can be registered using mcporter config add and integrated into the ecosystem.

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