How Exa Search Integration Works with Agent Reach via mcporter

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. 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. 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 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:

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:

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:

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:

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: Implements ExaSearchChannel with the check() method that probes mcporter and manages backend activation.
• 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: 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 verifies mcporter installation via probe_command() from 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.

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