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

> Configure Exa search for web search in Agent-Reach using mcporter. Install mcporter, register the Exa MCP endpoint, and verify with the doctor command for free semantic web search.

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

---

**You can enable free semantic web search in Agent-Reach by installing the mcporter Node.js utility, running `mcporter config add exa https://mcp.exa.ai/mcp` to register the Exa MCP endpoint, and verifying the configuration with the built-in `doctor` command.**

Agent-Reach provides a dedicated **ExaSearchChannel** that leverages **mcporter** to perform AI-driven semantic searches without requiring an Exa API key. This integration routes web search requests through the Model Context Protocol (MCP), allowing the framework to query the entire internet using Exa's free tier. By configuring mcporter correctly, you unlock the `exa_search` backend for both CLI operations and programmatic skill invocations.

## Install mcporter

Before configuring the Exa backend, you must install the **mcporter** binary globally. This Node.js utility acts as a bridge between Agent-Reach and the Exa MCP server.

```bash

# Install globally (requires Node.js and npm)

npm install -g mcporter

# Verify installation

mcporter --version

# Expected output: version number (e.g., 1.2.0)

```

If the binary is not found in your system PATH, the Exa search channel will report a "missing dependency" status during initialization.

## Register the Exa MCP Endpoint

Once mcporter is installed, register the Exa MCP server endpoint. This step stores the configuration in mcporter's local JSON store (referenced in [`config/mcporter.json`](https://github.com/Panniantong/Agent-Reach/blob/main/config/mcporter.json) in the repository).

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

```

You should see a confirmation message like:

```

✅ Added exa → https://mcp.exa.ai/mcp

```

This command creates the necessary mapping that allows Agent-Reach to route search queries to Exa's semantic search engine without an API key.

## Verify Configuration with the Doctor Command

Agent-Reach includes a diagnostic tool that automatically probes the Exa search configuration. Run the following to verify the setup:

```bash
python -m agent_reach.cli doctor

```

The diagnostic logic in **[`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)** (lines 928-951) executes `ExaSearchChannel.check()`, which probes mcporter using `probe_command("mcporter", ["config","list"])`. 

If configured correctly, you will see:

```

✅ exa_search: 全网语义搜索可用（免费，无需 API Key）

```

If the status reports **"off"**, repeat the endpoint registration step or check that mcporter is in your system PATH.

## Performing Web Searches

### Command Line Interface

With the Exa channel active, execute semantic searches directly from the terminal:

```bash
python -m agent_reach.cli search "latest transformer architectures" --backend exa_search

```

The CLI forwards the request to **[`agent_reach/core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py)**, which routes the query through the MCP bridge and returns a list of URLs with semantic snippets.

### From Within a Skill

You can invoke Exa search programmatically from any Agent-Reach skill using the MCP call syntax documented in **[`agent_reach/skill/references/search.md`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/skill/references/search.md)**:

```text
mcporter call 'exa.web_search_exa(query: "python asyncio patterns", numResults: 5)'

```

The response returns structured JSON containing URLs, titles, and content snippets that your skill can parse and render.

## How the Integration Works

### Probe Logic and Channel Activation

The **[`agent_reach/channels/exa_search.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/exa_search.py)** module implements the `ExaSearchChannel` class. When initialized, it runs a probe via `probe_command("mcporter", ["config","list"])` to verify:

1. The mcporter binary exists in the system PATH.
2. An entry for the Exa MCP endpoint exists in the mcporter configuration.

If the Exa entry is found, `self.active_backend` is set to the Exa backend and the channel reports status **"ok"**. If mcporter is missing or the endpoint is not configured, the channel reports **"off"** and the CLI (lines 1486-1510 in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)) prints specific remediation instructions.

### Zero-API-Key Architecture

Unlike traditional search integrations that require authentication tokens, this configuration leverages Exa's free MCP tier. The endpoint `https://mcp.exa.ai/mcp` accepts JSON-RPC requests without API keys when accessed through mcporter, enabling **zero-cost semantic search** for Agent-Reach users.

### Configuration Storage

While mcporter maintains its own local configuration store, the repository includes a reference template at **[`config/mcporter.json`](https://github.com/Panniantong/Agent-Reach/blob/main/config/mcporter.json)**. This file documents the expected schema for MCP endpoints and serves as a fallback reference during automated installation scripts.

## Summary

- **Install mcporter** globally using npm to provide the MCP bridge binary.
- **Register the endpoint** with `mcporter config add exa https://mcp.exa.ai/mcp` to enable the Exa backend.
- **Verify setup** by running `python -m agent_reach.cli doctor`, which checks [`agent_reach/channels/exa_search.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/exa_search.py) probe logic.
- **Search via CLI** using `--backend exa_search` or from skills using the `mcporter call` syntax.
- **No API key required**—the integration uses Exa's free MCP tier for full-web semantic search.

## Frequently Asked Questions

### Do I need an Exa API key to use this feature?

No. The mcporter configuration uses the public MCP endpoint `https://mcp.exa.ai/mcp`, which provides free access to Exa's semantic search capabilities without authentication tokens. This is confirmed by the probe logic in [`agent_reach/channels/exa_search.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/exa_search.py) that activates the channel solely based on the endpoint configuration, not API credentials.

### What should I do if the doctor command reports "off" for exa_search?

First, verify that mcporter is installed and available in your PATH by running `mcporter --version`. If the binary exists but the status remains "off", the Exa endpoint is missing from your mcporter configuration. Run `mcporter config add exa https://mcp.exa.ai/mcp` and rerun the doctor command. The diagnostic output in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) will update to reflect the active backend once the probe detects the configured endpoint.

### How do I invoke Exa search from inside a custom skill?

Use the Model Context Protocol call syntax: `mcporter call 'exa.web_search_exa(query: "your search terms", numResults: 10)'`. This command is documented in [`agent_reach/skill/references/search.md`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/skill/references/search.md) and routes through [`agent_reach/core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py) to return structured search results that your skill can parse.

### Where is the MCP configuration stored locally?

mcporter maintains its own JSON configuration file separate from Agent-Reach. When you run `mcporter config add`, it updates this local store. The repository includes a reference template at [`config/mcporter.json`](https://github.com/Panniantong/Agent-Reach/blob/main/config/mcporter.json) showing the expected schema, but the active configuration resides in mcporter's user-specific data directory, not in the Agent-Reach project folder.