# How to Configure Exa Search with mcporter MCP Integration in Agent Reach

> Easily configure Exa Search with mcporter MCP integration in Agent Reach. Install mcporter, add Exa server, and run Doctor. No API key needed.

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

---

**To configure Exa search in Agent Reach, install the mcporter CLI, add the Exa server to your mcporter configuration, and run the Doctor command to verify the integration—no API key required.**

Agent Reach integrates **Exa semantic search** through the **mcporter** MCP (Micro-Connector Platform), enabling zero-configuration web search capabilities. This guide explains how to set up the `ExaSearchChannel` by configuring the mcporter binary and validating the connection using Agent Reach's built-in diagnostics tools.

## Understanding the mcporter MCP Architecture

The integration operates across three layers as implemented in the [Panniantong/Agent-Reach](https://github.com/Panniantong/Agent-Reach) repository:

- **mcporter binary** – A Node.js CLI that reads [`mcporter.json`](https://github.com/Panniantong/Agent-Reach/blob/main/mcporter.json) or `mcporter.jsonc` configuration files and exposes MCP services to external tools.

- **`inspect_mcporter_config()`** – Located in [[`agent_reach/channels/mcporter.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/mcporter.py)](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/mcporter.py), this function parses the effective mcporter configuration without launching the binary, returning server names and editor import status.

- **`ExaSearchChannel`** – Defined in [[`agent_reach/channels/exa_search.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/exa_search.py)](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/exa_search.py), this channel checks the inspector's results for the `"exa"` server name and reports `"warn"` when configured or `"off"` when absent.

## Installation and Configuration Steps

### Step 1: Install mcporter Globally

The mcporter binary must be available on your `$PATH` for Agent Reach to detect any MCP-backed channels.

```bash
npm install -g mcporter

```

### Step 2: Add Exa to mcporter Configuration

Register the Exa MCP server using the mcporter CLI. The `--scope home` flag writes to `~/.mcporter/mcporter.json`.

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

```

This command creates the entry:

```json
{
  "exa": {
    "baseUrl": "https://mcp.exa.ai/mcp"
  }
}

```

You can also use `--scope project` to write to [`config/mcporter.json`](https://github.com/Panniantong/Agent-Reach/blob/main/config/mcporter.json) in your working directory.

### Step 3: Verify with Agent Reach Doctor

Run the diagnostic command to confirm the `ExaSearchChannel` detects your configuration:

```bash
python -m agent_reach.cli doctor | grep Exa

```

Expected output:

```

✅ Exa search configured (free, no API key needed)

```

The Doctor's `check()` method in [[`exa_search.py`](https://github.com/Panniantong/Agent-Reach/blob/main/exa_search.py)](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/exa_search.py) (lines 19-44) performs this verification by:

1. Confirming `mcporter` exists on `$PATH`
2. Calling `inspect_mcporter_config()` to retrieve `McporterConfigInspection.server_names`
3. Checking if `"exa"` is present in the server list

### Step 4: Test the MCP Connection (Optional)

Validate the Exa endpoint directly without Agent Reach:

```bash
mcporter call 'exa.web_search_exa(query: "hello world", numResults: 1)'

```

A successful response returns JSON search results, confirming the MCP layer is functional.

## Using Exa Search in Agent Reach Code

Once configured, invoke Exa search programmatically through the core Agent Reach interface:

```python
from agent_reach.core import AgentReach

ar = AgentReach()
result = ar.search("exa_search", query="latest AI breakthroughs", num_results=3)
print(result)  # List of semantic search snippets from Exa

```

The `ar.search()` method routes to `ExaSearchChannel` based on the channel name `"exa_search"`, as handled in [[`agent_reach/core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py)](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py).

## Understanding Doctor Status Messages

| Status | Meaning | Resolution |
|--------|---------|------------|
| **off** | `"exa"` not found in mcporter config | Repeat Step 2 to add the server |
| **warn** | `"exa"` present but not remotely verified | Normal state—channel ready for use |
| **✅ confirmed** | Full validation passed | Exa search fully operational |

The `"warn"` state is intentional design. Per lines 31-35 of [[`exa_search.py`](https://github.com/Panniantong/Agent-Reach/blob/main/exa_search.py)](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/exa_search.py), Agent Reach avoids remote service checks during Doctor runs to maintain tight credential boundaries.

## Key Configuration Files and Functions

| File | Purpose |
|------|---------|
| [[`agent_reach/channels/exa_search.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/exa_search.py)](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/exa_search.py) | `ExaSearchChannel.check()` implements configuration detection |
| [[`agent_reach/channels/mcporter.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/mcporter.py)](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/mcporter.py) | `inspect_mcporter_config()` parses mcporter JSON without execution |
| [[`config/mcporter.json`](https://github.com/Panniantong/Agent-Reach/blob/main/config/mcporter.json)](https://github.com/Panniantong/Agent-Reach/blob/main/config/mcporter.json) | Project-level mcporter configuration template |
| [[`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) | Entry point for `python -m agent_reach.cli doctor` |
| [[`agent_reach/core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py)](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py) | Core routing for `search()` API calls |

## Troubleshooting Common Issues

### mcporter Not Found

Ensure the npm global bin directory is in your `$PATH`:

```bash
which mcporter  # Should return path to binary

# If missing, add to ~/.bashrc or ~/.zshrc:

export PATH="$PATH:$(npm bin -g)"

```

### Doctor Reports "off" After Configuration

- Check if using correct scope: `cat ~/.mcporter/mcporter.json` vs [`./config/mcporter.json`](https://github.com/Panniantong/Agent-Reach/blob/main/./config/mcporter.json)
- Verify JSON syntax: `mcporter config validate`
- Force rescan: `python -m agent_reach.cli doctor --refresh`

### Empty Search Results

The Exa MCP endpoint requires internet connectivity. Test directly:

```bash
curl -I https://mcp.exa.ai/mcp

```

## Summary

- **Install mcporter** via `npm install -g mcporter` to enable MCP support
- **Add Exa server** using `mcporter config add exa https://mcp.exa.ai/mcp --scope home`
- **Verify configuration** with `python -m agent_reach.cli doctor` checking for the ✅ Exa status
- **No API key required**—Exa's MCP endpoint is free for semantic search operations
- **Programmatic access** uses `ar.search("exa_search", query=..., num_results=...)`

## Frequently Asked Questions

### What is mcporter and why does Agent Reach require it?

**mcporter** is a Node.js-based MCP host that bridges external services like Exa to Agent Reach's channel system. Agent Reach requires it because all MCP integrations—including Exa search—are abstracted through this micro-connector platform rather than direct API implementations. This design keeps credentials and connection logic outside the Python codebase.

### Why does the Doctor show "warn" instead of "confirmed" for Exa?

The `"warn"` status indicates the `exa` server is present in your mcporter configuration but Agent Reach did not perform a live service check. This is by design: the [`ExaSearchChannel.check()`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/exa_search.py) method avoids remote calls during diagnostics to prevent credential exposure. The channel is fully functional for searches despite this status.

### Can I configure Exa at the project level instead of globally?

Yes. Replace `--scope home` with `--scope project` when running `mcporter config add`. This writes to [`config/mcporter.json`](https://github.com/Panniantong/Agent-Reach/blob/main/config/mcporter.json) in your current working directory rather than `~/.mcporter/mcporter.json`. Agent Reach's `inspect_mcporter_config()` automatically merges project and home scope configurations.

### Does Exa search in Agent Reach require an API key?

No. Exa provides a free MCP endpoint at `https://mcp.exa.ai/mcp` that requires no authentication. Agent Reach's status message explicitly notes **"free, no API key needed"** when the integration is detected.