How to Set Up Exa Search via mcporter for Web Search in Agent-Reach

Agent-Reach enables zero-configuration, whole-web semantic search by leveraging the Exa MCP through mcporter, requiring only Node.js and the mcporter CLI to be installed and configured.

Agent-Reach (Panniantong/Agent-Reach) provides AI agents with unrestricted web-search capabilities through a lightweight integration with Exa's free semantic search service. Unlike traditional API-based search requiring authentication keys, the Exa search channel in Agent-Reach delegates all operations to the mcporter CLI tool, which manages the Model Context Protocol (MCP) connection. This architecture keeps the codebase minimal while providing powerful semantic search functionality across the entire web.

Architecture Overview

The Exa search integration in Agent-Reach follows a deliberate thin-wrapper design. The ExaSearchChannel class in agent_reach/channels/exa_search.py does not re-implement search logic; instead, it validates that the mcporter backend is present and correctly configured, then allows direct invocation of the upstream CLI.

Key components include:

• mcporter (npm package): Provides a uniform CLI interface to multiple MCP backends, including Exa's free semantic-search endpoint at https://mcp.exa.ai/mcp. The installer handles this in _install_mcporter() within agent_reach/cli.py.
• ExaSearchChannel: Located in agent_reach/channels/exa_search.py, this channel reports health status through the doctor and sets self.active_backend = "Exa via mcporter" when validated.
• Doctor/Probe System: The probe_command function in agent_reach/probe.py executes mcporter config list to verify the binary exists and the Exa MCP entry is configured.
• Configuration: While agent_reach/config.py lists exa_search under FEATURE_REQUIREMENTS (historically for API keys), the free MCP implementation ignores this and requires no authentication.

Step-by-Step Setup Guide

Install Node.js and npm

The mcporter tool requires Node.js. The installer (_install_system_deps in agent_reach/cli.py) checks for node and npm, auto-installing them on Debian/Ubuntu or suggesting Homebrew on macOS if missing.

Ensure Node.js is available:

node --version
npm --version

If not installed, use your system's package manager:

# Ubuntu/Debian

sudo apt install nodejs npm

# macOS

brew install node

Install mcporter Globally

Install the mcporter package globally using npm. This provides the mcporter command used by Agent-Reach's Exa integration:

npm install -g mcporter

The automated installer in _install_mcporter() (lines 99-110 of agent_reach/cli.py) executes this command and verifies the installation.

Configure the Exa MCP Endpoint

Add the Exa MCP configuration to mcporter. This step connects the CLI to Exa's free semantic search endpoint:

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

According to the source code in agent_reach/cli.py, the installer automatically runs this configuration if the entry is missing (lines 21-33).

Verify Installation with the Doctor

Run the Agent-Reach doctor to validate the Exa search channel:

agent-reach doctor

The doctor executes ExaSearchChannel.check(), which internally calls probe_command("mcporter", ["config", "list"]) from agent_reach/probe.py. A successful configuration displays:

✅ 全网语义搜索 (Exa) – ok – 全网语义搜索可用（免费，无需 API Key）

If the status shows off or error, the doctor provides specific remediation steps.

Performing Web Searches

Agent-Reach does not wrap search functionality; you invoke mcporter directly.

Command Line Search

Execute searches from the terminal using the mcporter CLI:

mcporter search exa "large language models"

The output is a JSON array of result objects containing titles, URLs, and semantic relevance scores.

Python Integration

To perform searches programmatically within your Agent-Reach workflows, invoke mcporter via subprocess:

import subprocess
import json

def exa_search(query: str):
    """Perform Exa search via mcporter CLI."""
    result = subprocess.run(
        ["mcporter", "search", "exa", query],
        capture_output=True,
        encoding="utf-8",
        errors="replace",
        timeout=15,
    )
    result.check_returncode()
    return json.loads(result.stdout)

# Example usage

hits = exa_search("agent reach open source")
for hit in hits[:3]:
    print(f"{hit['title']} → {hit['url']}")

This approach uses the same binary validated by the doctor, ensuring consistency across shell and Python environments.

Troubleshooting Common Issues

mcporter Command Not Found

If the terminal reports command not found, Node.js or npm may not be installed, or the npm global bin directory is not in your $PATH.

Fix: Install Node.js (apt install nodejs npm or brew install node), then ensure ~/.npm-global/bin or your npm prefix directory is exported in your shell configuration.

Doctor Reports "broken" with Node Environment Errors

When the doctor reports "broken" with the hint mcporter 无法执行（node 环境损坏）, this indicates a stale mcporter shim, often after system upgrades.

Fix: Reinstall the package using npm install -g mcporter or force reinstall via uv tool install --force mcporter.

Exa MCP Configuration Missing

If the doctor reports "off – mcporter 未配置", the Exa MCP entry is missing from the mcporter configuration.

Fix: Manually add the configuration:

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

Alternatively, rerun the Agent-Reach installer, which executes this automatically in _install_mcporter().

Empty Results or Network Proxy Requirements

Search returning empty JSON or connection errors often indicates network restrictions, common in regions requiring proxy access.

Fix: Configure proxy settings through Agent-Reach:

agent-reach configure proxy http://user:pass@host:port

The system exports these as HTTP_PROXY and HTTPS_PROXY environment variables before invoking mcporter.

Summary

• Agent-Reach provides Exa search through a lightweight mcporter integration, requiring no API keys for the free MCP tier.
• Installation requires Node.js and the global mcporter npm package, configured with the Exa MCP endpoint at https://mcp.exa.ai/mcp.
• Health validation occurs through agent-reach doctor, which executes probe_command in agent_reach/probe.py to verify the mcporter binary and configuration.
• Actual searches execute via mcporter search exa "<query>", callable from shell or Python subprocess, returning JSON results.
• Common issues involve Node.js path configuration, stale mcporter installations, or missing MCP entries, all resolvable through CLI commands or the automated installer in agent_reach/cli.py.

Frequently Asked Questions

Do I need an Exa API key to use web search in Agent-Reach?

No. Exa's free MCP endpoint does not require an API key. While agent_reach/config.py historically lists exa_api_key under FEATURE_REQUIREMENTS for backward compatibility, the ExaSearchChannel.check() method in agent_reach/channels/exa_search.py ignores this requirement and only validates that the mcporter CLI has the Exa MCP configured.

Why does Agent-Reach use mcporter instead of implementing the search directly?

Agent-Reach deliberately delegates search operations to mcporter to maintain a minimal codebase and leverage the Model Context Protocol standard. This architecture allows the agent to call the upstream mcporter CLI directly without re-implementing MCP client logic or managing Exa API authentication, keeping the integration lightweight and maintainable.

How can I verify Exa search is working without running an actual search?

Run agent-reach doctor or call the Python API directly:

from agent_reach.doctor import check_all
from agent_reach.config import Config

status = check_all(Config())
print(status["exa_search"]["status"])  # Outputs: "ok", "off", or "error"

The doctor probes mcporter config list via agent_reach/probe.py to confirm the binary exists and the Exa backend is registered, reporting "ok" when the configuration is valid.

Can I use Exa search behind a corporate firewall or proxy?

Yes. Configure the proxy through Agent-Reach using agent-reach configure proxy <url>. The system exports these settings as HTTP_PROXY and HTTPS_PROXY environment variables before executing mcporter commands, allowing the search traffic to route through your corporate proxy.

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