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

> Learn to set up Exa search via mcporter for Agent-Reach web search. Leverage Exa MCP with Node.js and mcporter CLI for efficient, zero-configuration semantic search.

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

---

**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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py).
- **ExaSearchChannel**: Located in [`agent_reach/channels/exa_search.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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:

```bash
node --version
npm --version

```

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

```bash

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

```bash
npm install -g mcporter

```

The automated installer in `_install_mcporter()` (lines 99-110 of [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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:

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

```

According to the source code in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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:

```bash
agent-reach doctor

```

The doctor executes `ExaSearchChannel.check()`, which internally calls `probe_command("mcporter", ["config", "list"])` from [`agent_reach/probe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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:

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

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

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

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

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