How MCP Server Integration Works with Exa Search in Agent Reach

Agent Reach exposes its diagnostic capabilities through an MCP server that registers a get_status tool, which queries the ExaSearchChannel.check() method to verify Exa Search availability via the mcporter CLI, returning JSON-formatted status reports to any MCP-compatible client.

The Agent-Reach repository provides a modular diagnostic framework that integrates with Exa Search through the Modular Communication Protocol (MCP). This integration allows agents and automation tools to query the operational status of Exa Search capabilities without importing Python modules directly. The MCP server integration with Exa search relies on a cascading chain of method calls across multiple modules to surface diagnostic information as machine-readable data.

MCP Server Architecture

The integration follows a cascading diagnostic pattern where the MCP server acts as a thin wrapper around the core Agent-Reach logic. When a client invokes the get_status tool, the server delegates to AgentReach.doctor_report(), which iterates through registered channel classes to collect status information.

The data flow proceeds as follows:

1. MCP client calls get_status tool
2. Server invokes eyes.doctor_report() on the AgentReach instance
3. doctor_report() calls check() on each channel, including ExaSearchChannel
4. ExaSearchChannel.check() executes probe_command("mcporter", ["config", "list"], ...)
5. Results are marshaled into JSON and returned as TextContent

Key Implementation Files

The integration spans four primary modules that handle server setup, channel logic, diagnostic aggregation, and command execution.

MCP Server Definition

The file agent_reach/integrations/mcp_server.py sets up the MCP server using decorators to register capabilities. It creates an AgentReach instance (eyes = AgentReach(config)) during initialization and exposes a single tool named get_status.

The server uses two critical decorators:

• @server.list_tools() registers the available tools
• @server.call_tool() implements the call_tool coroutine that forwards requests to eyes.doctor_report()

Results are serialized using json.dumps(result, ...) and wrapped in a TextContent payload for MCP protocol compliance.

Exa Search Channel

The file agent_reach/channels/exa_search.py contains the ExaSearchChannel class that encapsulates Exa Search-specific diagnostics. Its check() method determines whether the channel is installed, active, or broken by probing the environment.

Specifically, it calls probe_command("mcporter", ["config", "list"], ...) to verify that:

• The mcporter Node-based CLI is installed and available in PATH
• The Exa MCP backend is properly configured

Core Diagnostic Components

Three additional files provide supporting infrastructure:

• agent_reach/core.py: Contains the AgentReach class that aggregates all channel instances and provides the doctor_report() method used by the MCP server.
• agent_reach/doctor.py: Orchestrates the full status report generation, coordinating between the core router and individual channel checks.
• agent_reach/probe.py: Provides the probe_command utility for safely executing external commands like mcporter with error handling and timeout management.

The Diagnostic Execution Flow

When the MCP server receives a get_status invocation, it executes a precise sequence to evaluate Exa Search readiness.

First, the server instantiates AgentReach with the loaded configuration, which initializes all registered channels including ExaSearchChannel. When doctor_report() runs, it iterates over each channel class and invokes the respective check() method.

For Exa Search specifically, the check() method runs mcporter config list via the probe utility. If the command succeeds, the method returns an "ok" status indicating that Exa Search is available for free semantic web search without requiring an API key. If the command fails, it returns either "broken" (if the environment is misconfigured) or "off" with installation instructions.

The server then aggregates these results into a dictionary, serializes it to JSON, and returns it to the MCP client.

Practical Usage Examples

Starting the MCP Server

Expose the get_status tool via standard input/output:

python -m agent_reach.integrations.mcp_server

Programmatic Client Invocation

Access the status from another Python process using the MCP client library:

from mcp.client import Client

async def get_agent_reach_status():
    async with Client() as client:
        # Connect to the running MCP server (STDIO by default)

        result = await client.call_tool("get_status", {})
        print(result)  # JSON-formatted status report

Sample Output Structure

The resulting JSON includes the Exa Search status under the exa_search key:

{
  "exa_search": {
    "status": "ok",
    "message": "全网语义搜索可用（免费，无需 API Key）"
  }
}

Manual Status Check

Verify Exa Search without the MCP server by interacting directly with the channel class:

from agent_reach.channels.exa_search import ExaSearchChannel

channel = ExaSearchChannel()
status, msg = channel.check()
print(status, msg)

When mcporter is missing, this outputs instructions for installation:

off 需要 mcporter + Exa MCP。安装：
  npm install -g mcporter
  mcporter config add exa https://mcp.exa.ai/mcp

Summary

• The MCP server integration with Exa search is implemented in agent_reach/integrations/mcp_server.py, which exposes a get_status tool that returns JSON diagnostics to MCP-compatible clients.
• The ExaSearchChannel.check() method in agent_reach/channels/exa_search.py validates Exa Search availability by executing mcporter config list through the probe utility.
• Agent Reach aggregates channel statuses via AgentReach.doctor_report() in agent_reach/core.py, making Exa Search operational state discoverable without direct API integration.
• No API key is required for Exa Search when properly configured through the mcporter CLI, which requires Node.js and the Exa MCP backend to be installed.

Frequently Asked Questions

What dependencies are required for the MCP server to report Exa Search as operational?

The MCP server requires the mcporter CLI tool to be installed globally via npm (npm install -g mcporter) and configured with the Exa MCP backend endpoint (mcporter config add exa https://mcp.exa.ai/mcp). These components verify that the Node-based wrapper is available in the system PATH before reporting status as "ok".

How does the get_status tool communicate with Exa Search?

The tool does not communicate directly with Exa Search APIs. Instead, it invokes AgentReach.doctor_report(), which calls ExaSearchChannel.check(). This method uses probe_command() from agent_reach/probe.py to execute mcporter config list locally, validating that the Exa MCP backend is configured without requiring network calls to Exa's servers.

Can I check Exa Search status without running the MCP server?

Yes. You can instantiate ExaSearchChannel directly from agent_reach/channels/exa_search.py and call its check() method. This bypasses the MCP protocol entirely and returns the status tuple immediately, which is useful for debugging or integration with non-MCP workflows.

What is the difference between "broken" and "off" statuses in the diagnostic report?

An "off" status indicates that mcporter is not installed or the Exa MCP configuration is missing, typically accompanied by installation instructions. A "broken" status suggests that mcporter is installed but the environment is misconfigured—such as corrupted config files or incompatible Node versions—requiring environment repair rather than fresh installation.

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