# How Agent-Reach Uses mcporter to Integrate Exa for Semantic Search

> Learn how Agent-Reach integrates Exa for semantic search using mcporter. Discover how mcporter abstracts third-party services for streamlined RPC calls and eliminates direct API key management.

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

---

**Agent-Reach routes all Exa semantic search requests through mcporter, a Micro-Control-Plane gateway that abstracts third-party services into standardized RPC calls, eliminating the need for direct API key management within the application layer.**

The Panniantong/Agent-Reach repository implements a modular architecture for AI agents that requires external semantic search capabilities. Rather than embedding Exa API credentials directly into the Python codebase or environment variables, the system delegates authentication and request routing to **mcporter**, which acts as an intermediary MCP (Micro-Control-Plane) gateway.

## Configuration and Auto-Setup in Agent-Reach

### Declaring Exa Requirements

In [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), the Exa integration is declared as a feature requiring the configuration key `exa_api_key`. This declaration signals to the framework that any Exa functionality depends on external credentials managed outside the application layer. According to the source code at line 23, this requirement triggers the auto-configuration logic when users first attempt to invoke Exa search.

### CLI Auto-Configuration

The automated setup logic in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 926–952) handles mcporter initialization without manual intervention. When a user first invokes an Exa search command, the CLI executes:

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

```

This command persists the MCP endpoint to [`config/mcporter.json`](https://github.com/Panniantong/Agent-Reach/blob/main/config/mcporter.json), which mcporter subsequently reads to determine where to forward Exa-related RPC calls. Detailed manual setup instructions are also provided in [`agent_reach/guides/setup-exa.md`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/guides/setup-exa.md) for environments requiring custom configuration.

## Exa Channel Implementation

### The Exa Search Channel Architecture

The [`agent_reach/channels/exa_search.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/exa_search.py) file implements the Exa integration by inheriting from `BaseChannel`. This design pattern ensures that the channel never constructs direct HTTPS requests to Exa's REST API. Instead, it builds **mcporter RPC call strings** that delegate transport, authentication, and error handling to the MCP server.

### RPC Call Construction Methods

The channel exposes two primary methods that map directly to mcporter commands:

- **`search(query, numResults, …)`** → constructs the command `mcporter call 'exa.web_search_exa(query: "...", numResults: N)'`
- **`get_code_context(query, tokensNum)`** → constructs the command `mcporter call 'exa.get_code_context_exa(query: "...", tokensNum: …)'`

Critically, the channel implementation contains **no hardcoded API keys**. The MCP server injects the `exa_api_key` from [`config/mcporter.json`](https://github.com/Panniantong/Agent-Reach/blob/main/config/mcporter.json) at request time, ensuring credentials never appear in application memory, logs, or process lists.

## Runtime Execution Flow

When a user initiates a semantic search, Agent-Reach executes a three-step delegation process through mcporter.

First, the user invokes the search via the CLI or Python library:

```bash
python -m agent_reach.cli search "open source AI agents" --backend exa

```

Second, the Exa channel in [`agent_reach/channels/exa_search.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/exa_search.py) constructs the mcporter command and executes it as a subprocess. The channel translates the method parameters into the RPC string format expected by the MCP server.

Third, mcporter contacts `https://mcp.exa.ai/mcp`, which forwards the request to the Exa service, injects the necessary API key, and returns JSON results. Agent-Reach parses this response and returns structured data to the caller without handling raw authentication headers.

## Benefits of the mcporter Integration

The mcporter abstraction provides specific architectural advantages for Agent-Reach deployments:

- **Zero-configuration deployment** – The CLI auto-configuration in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) eliminates manual API key management, allowing agents to use Exa search immediately after installation.
- **Unified RPC interface** – All third-party services (Twitter, Reddit, Exa, etc.) use the identical `mcporter call` pattern, standardizing error handling and diagnostics across the entire codebase.
- **MCP extensibility** – Organizations can self-host the MCP server or modify the endpoint in [`config/mcporter.json`](https://github.com/Panniantong/Agent-Reach/blob/main/config/mcporter.json) to enable custom backends, proxy configurations, or caching layers without changing [`agent_reach/channels/exa_search.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/exa_search.py).

## Practical Code Examples

### Library Usage

To perform semantic web search programmatically:

```python
from agent_reach.core import AgentReach

ar = AgentReach()
results = ar.search_exa(query="machine learning advances", numResults=5)
for r in results["hits"]:
    print(r["title"], r["url"])

```

### CLI Invocation

Command-line usage that triggers the mcporter pipeline:

```bash
python -m agent_reach.cli search "open source AI agents" --backend exa

```

Under the hood, this executes:

```bash
mcporter call 'exa.web_search_exa(query: "open source AI agents", numResults: 10)'

```

### Debugging Configuration

Verify that mcporter is properly configured for Exa:

```bash
mcporter config list

```

Expected output includes:

```text
exa  https://mcp.exa.ai/mcp

```

## Summary

- Agent-Reach delegates all Exa API interactions to **mcporter**, a Micro-Control-Plane gateway that abstracts third-party service authentication and transport.
- Configuration is handled automatically in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 926–952) and stored in [`config/mcporter.json`](https://github.com/Panniantong/Agent-Reach/blob/main/config/mcporter.json), requiring no manual API key setup in application code.
- The Exa channel in [`agent_reach/channels/exa_search.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/exa_search.py) constructs RPC calls (such as `exa.web_search_exa`) rather than direct HTTP requests, eliminating credential exposure.
- The integration supports both **programmatic** (Python library) and **command-line** interfaces through a unified `mcporter call` mechanism.
- This architecture enables **zero-configuration** deployments and **MCP extensibility** for custom backend implementations or self-hosted proxies.

## Frequently Asked Questions

### How does mcporter handle authentication for Exa API calls?

The MCP server configured at `https://mcp.exa.ai/mcp` injects the `exa_api_key` at request time. The key is stored in [`config/mcporter.json`](https://github.com/Panniantong/Agent-Reach/blob/main/config/mcporter.json) and never exposed to the Agent-Reach application code, which only constructs RPC calls without embedding credentials.

### Can I use Exa search without installing mcporter separately?

No. Agent-Reach requires mcporter as a system dependency. However, the CLI auto-configuration logic automatically runs `mcporter config add exa https://mcp.exa.ai/mcp` on first use, making the setup process transparent to users who may not manually configure the gateway.

### What happens if the Exa MCP server is unavailable?

Since Agent-Reach invokes mcporter as a subprocess, any connection failures to `https://mcp.exa.ai/mcp` propagate as subprocess errors that the channel can catch and handle uniformly. Because all third-party services use the same mcporter interface, error handling logic remains consistent across Twitter, Reddit, and Exa integrations.

### Is it possible to self-host the MCP server for Exa integration?

Yes. The mcporter architecture supports swapping the endpoint URL in [`config/mcporter.json`](https://github.com/Panniantong/Agent-Reach/blob/main/config/mcporter.json). Organizations can deploy their own MCP server that proxies to Exa (or implements custom caching and rate limiting) without modifying [`agent_reach/channels/exa_search.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/exa_search.py), as the channel only references the service name `exa` and the RPC method signatures.