# How Exa Search Integration Works with Agent Reach via mcporter

> Learn how Exa Search integrates with Agent Reach using mcporter. Discover the process of routing free semantic search queries and ensuring proper Exa endpoint configuration.

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

---

**Agent Reach integrates Exa Search through the `mcporter` MCP command-line tool, routing free semantic search queries to Exa after verifying the binary is installed, executable, and properly configured with the Exa endpoint.**

The `ExaSearchChannel` class in the Panniantong/Agent-Reach repository provides a zero-API-key semantic search capability by delegating search operations to the Exa service via the mcporter Model Context Protocol (MCP) implementation. This integration allows agents to perform global web searches without managing API credentials, relying instead on a local mcporter installation that acts as a bridge to Exa's free search tier.

## The ExaSearchChannel Architecture

`ExaSearchChannel` is a search-only channel implementation located in [`agent_reach/channels/exa_search.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/exa_search.py). Unlike channels that implement search logic directly, this class functions as a **health-check wrapper** that ensures the external `mcporter` binary is present and correctly configured before allowing search operations.

## Probing the mcporter Installation

The integration begins with the `check()` method executing `probe_command("mcporter", ["config", "list"], …)` from [`agent_reach/probe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/probe.py). This probe performs a live execution of `mcporter config list` to determine binary availability and configuration state.

The `probe_command` function in [`agent_reach/probe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/probe.py) distinguishes between four distinct states by analyzing exit codes and output streams:

- **missing**: The binary is not found in the system PATH
- **broken**: The binary exists but cannot execute (e.g., stale virtual environment, missing Node.js interpreter)
- **timeout**: The command failed to complete within the allotted time
- **error**: The command returned a non-zero exit code

## Handling Configuration States

Based on the probe results, `ExaSearchChannel.check()` handles four specific scenarios:

### 1. Missing mcporter Binary

When `probe` returns `status == "missing"`, the channel reports *off* and instructs the user to install the tool globally:

```bash
npm install -g mcporter

```

### 2. Broken mcporter Installation

If the binary exists but cannot execute, indicated by `status == "broken"`, the channel returns an *error* status with a reinstallation hint. This prevents false positives when a shim script remains but the underlying Node.js environment has been removed or corrupted.

### 3. Exa Endpoint Not Configured

When mcporter runs successfully but its output does not contain the word "exa", the channel reports *off* and prompts the user to add the Exa MCP endpoint:

```bash
mcporter config add exa https://mcp.exa.ai/mcp

```

### 4. Active Exa Configuration

If the output contains "exa", the channel marks the backend as active by setting `self.active_backend = self.backends[0]` and returns *ok* with the message "全网语义搜索可用（免费，无需 API Key）" (Global semantic search available, free, no API key required).

## Executing Semantic Searches

Once the channel status is "ok", Agent Reach delegates search execution directly to the mcporter CLI. The repository does not implement search logic internally; instead, it invokes the external binary:

```python
import subprocess
import shlex

def exa_search(query: str, limit: int = 10):
    cmd = f"mcporter search '{query}' --limit {limit}"
    result = subprocess.run(shlex.split(cmd), capture_output=True, text=True)
    result.check_returncode()
    return result.stdout

```

This delegation pattern allows the system to leverage Exa's semantic search capabilities without embedding API clients or authentication logic within the Agent Reach codebase.

## Checking Channel Status Programmatically

You can verify the Exa Search integration status from Python using the channel class directly:

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

cfg = Config()  # loads ~/.agent-reach/config.yaml

exa = ExaSearchChannel()
status, msg = exa.check(cfg)  # runs the mcporter probe

print(status, msg)  # -> "ok" "全网语义搜索可用（免费，无需 API Key）"

```

## Key Implementation Files

The integration relies on three core components:

- **[`agent_reach/channels/exa_search.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/exa_search.py)**: Implements `ExaSearchChannel` with the `check()` method that probes mcporter and manages backend activation.
- **[`agent_reach/probe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/probe.py)**: Provides `probe_command()`, the robust health-check routine that distinguishes between missing, broken, and error states by analyzing process exit codes and output.
- **[`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py)**: Aggregates channel health checks (including Exa) for the `agent-reach doctor` diagnostic command, providing users with a unified view of MCP configuration status.

## Summary

- **Exa Search integration** in Agent Reach operates as a bridge to the mcporter MCP rather than implementing direct API calls.
- 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) verifies mcporter installation via `probe_command()` from [`agent_reach/probe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/probe.py).
- Four distinct states are handled: missing binary, broken installation, unconfigured Exa endpoint, and active configuration.
- Once configured, searches execute via subprocess calls to `mcporter search`, requiring no API keys or embedded authentication logic.
- The system provides Chinese-language status messages indicating when free global semantic search becomes available.

## Frequently Asked Questions

### How do I install mcporter for Agent Reach Exa Search?

Install mcporter globally using npm to enable the Exa Search channel. Run `npm install -g mcporter` in your terminal. After installation, you must add the Exa MCP endpoint with `mcporter config add exa https://mcp.exa.ai/mcp` before the channel reports an active status.

### Why does Agent Reach report mcporter as "broken" instead of "missing"?

The "broken" status indicates that the mcporter binary exists in your PATH but cannot execute, typically due to a stale Node.js virtual environment, missing Node.js interpreter, or corrupted installation. This distinction prevents false positives where a shim script remains but the underlying runtime is gone. Reinstall mcporter using `npm install -g mcporter` to resolve this state.

### Does Agent Reach implement Exa search logic internally?

No, Agent Reach does not implement Exa search logic internally. The `ExaSearchChannel` class only verifies that mcporter is installed and configured correctly. Actual search queries are delegated to the external `mcporter` binary via subprocess execution, which then communicates with Exa's MCP endpoint at `https://mcp.exa.ai/mcp`.

### Is an API key required for Exa Search in Agent Reach?

No API key is required. The integration uses Exa's free tier accessible through the mcporter MCP. Once you configure the endpoint using `mcporter config add exa https://mcp.exa.ai/mcp`, the channel reports "全网语义搜索可用（免费，无需 API Key）" indicating that global semantic search is available without authentication credentials.