Agent Reach MCP Integration: Configuring mcporter for Exa Search

Agent Reach exposes the health status of its mcporter-based Exa semantic search through a dedicated MCP server that registers a get_status tool, allowing external clients to verify backend availability via the AgentReach.doctor_report() aggregation method.

Agent Reach is an open-source framework that routes AI-agent requests to native internet platform tools. The repository includes an optional MCP (Machine-Readable Control Protocol) integration that exposes internal diagnostics, specifically for the Exa semantic search backend managed by mcporter, enabling standardized health monitoring across distributed systems.

Architecture of the MCP Integration

Core Components

The integration spans four primary modules:

• AgentReach core (agent_reach/core.py): Central orchestrator that loads configurations and builds the channel registry. It aggregates health reports from all channels via the doctor_report() method.

• MCP server (agent_reach/integrations/mcp_server.py): Implements the create_server() entry point (lines 27‑57) that registers the get_status tool (lines 36‑42). When invoked, it calls eyes.doctor_report() to return serialized channel status.

• Exa Search channel (agent_reach/channels/exa_search.py): Implements ExaSearchChannel with a check() method (lines 21‑41) that probes the local mcporter installation to verify Exa backend availability.

• Probe utility (agent_reach/probe.py): Executes external commands like mcporter config list safely, capturing status, stdout, and stderr for health determination.

Health Check States

The check() method in exa_search.py returns one of three states based on the probe outcome:

• off: The mcporter binary is missing or Exa is not configured.
• error: mcporter is installed but broken. The error includes _MCPORTER_BROKEN_HINT (line 9) suggesting reinstallation.
• ok: Exa backend detected successfully (self.active_backend = self.backends[0] at line 35).

How the Integration Works

When you start the MCP server, the system follows this execution flow:

1. Server initialization: Running python -m agent_reach.integrations.mcp_server executes create_server() (lines 27‑57 of mcp_server.py). The server exits with an error if mcporter or the agent-reach[mcp] extras are absent (lines 28‑30).

2. Tool registration: The server registers the get_status tool via the @server.list_tools() decorator (lines 36‑42).

3. Status aggregation: When a client calls get_status, the handler invokes eyes.doctor_report(). Here, eyes is an AgentReach instance (line 34) that iterates through all registered channels, including the Exa search channel.

4. Channel probing: The ExaSearchChannel.check() method runs probe_command("mcporter", ["config", "list"], ...) to verify the backend.

5. JSON serialization: The resulting status map is wrapped in a TextContent object (line 52) and returned to the MCP client, making Exa search capability discoverable by any MCP-compatible consumer.

Implementation Examples

Starting the MCP Server

To expose the Exa search status endpoint, start the dedicated MCP server:

python -m agent_reach.integrations.mcp_server

The server performs a guard check at lines 28‑30 and exits if the required dependencies are missing.

Querying Status via MCP Client

With an MCP client (such as the official Python mcp package), retrieve the aggregated health status:

from mcp.client import Client

client = Client()
tools = client.list_tools()               # Discovers "get_status"

status = client.call_tool("get_status", {})
print(status)  # JSON output includes {"exa_search": {"state":"ok","msg":"全网语义搜索可用（免费，无需 API Key）"}}

Manual Channel Verification

Bypass the MCP layer to check the Exa channel directly:

from agent_reach.channels.exa_search import ExaSearchChannel
from agent_reach.config import Config

channel = ExaSearchChannel(Config())
state, msg = channel.check()
print(state, msg)  # Output: ok 全网语义搜索可用（免费，无需 API Key）

Installing mcporter and Exa

Before the integration can report ok status, install the mcporter CLI and configure the Exa backend:

npm install -g mcporter
mcporter config add exa https://mcp.exa.ai/mcp

If the check returns error, consult the _MCPORTER_BROKEN_HINT constant at line 9 of exa_search.py, which typically recommends reinstalling mcporter.

Summary

• Agent Reach provides a lightweight orchestration layer that exposes internal tool health via an MCP server defined in agent_reach/integrations/mcp_server.py.
• The get_status tool aggregates channel health through AgentReach.doctor_report() in agent_reach/core.py.
• Exa semantic search availability is verified by the ExaSearchChannel.check() method in agent_reach/channels/exa_search.py, which probes the local mcporter installation.
• Three distinct states—off, error, and ok—provide clear diagnostics for troubleshooting the Exa MCP backend.
• Configuration and environment variables are managed through agent_reach/config.py, while command execution safety is handled by agent_reach/probe.py.

Frequently Asked Questions

What is the role of mcporter in Agent Reach?

mcporter acts as the local MCP gateway that hosts the Exa semantic search backend. Agent Reach queries this binary via probe_command() to verify the Exa configuration is active and accessible, returning ok when the backend responds correctly.

How do I troubleshoot a "broken" mcporter error?

When exa_search.py detects a non-zero exit code from mcporter config list, it returns the error state alongside _MCPORTER_BROKEN_HINT. Resolve this by reinstalling mcporter globally: npm install -g mcporter, then re-run the health check.

Can I use the Exa search channel without the MCP server?

Yes. Instantiate ExaSearchChannel directly with a Config object and call channel.check() to receive the state tuple manually. This bypasses the MCP protocol while using the same underlying probe logic in agent_reach/probe.py.

Where is the MCP server entry point defined?

The server entry point is agent_reach/integrations/mcp_server.py, specifically the create_server() function (lines 27‑57). This module is executed via python -m agent_reach.integrations.mcp_server and registers the get_status tool for external clients.

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