# How MCP Server Integration Works with Exa Search in Agent Reach

> Discover how MCP server integration enables Agent Reach to query Exa Search availability. Learn about the diagnostic capabilities and status reporting process via the mcporter CLI.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: internals
- Published: 2026-07-19

---

**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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py)**: Orchestrates the full status report generation, coordinating between the core router and individual channel checks.
- **[`agent_reach/probe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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:

```bash
python -m agent_reach.integrations.mcp_server

```

### Programmatic Client Invocation

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

```python
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:

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

```

### Manual Status Check

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

```python
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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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.