# How Agent Reach Integrates with MCP Server and mcporter for Exa Semantic Search

> Discover how Agent Reach integrates with MCP server and mcporter to streamline Exa semantic search. Learn about abstracting API authentication and uniform RPC interfaces for third party services.

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

---

**Agent Reach routes all Exa semantic search requests through mcporter, an MCP (Micro-Control-Plane) gateway that abstracts API authentication and provides a uniform RPC interface for third-party services.**

Agent Reach provides semantic web search capabilities by integrating with Exa through an MCP server infrastructure. Rather than embedding API credentials directly in the application code, the Panniantong/Agent-Reach repository delegates authentication and request routing to mcporter, creating a secure abstraction layer for external service calls.

## Configuration and Auto-Setup

The integration relies on automatic configuration management to eliminate manual credential handling.

### Feature Declaration in config.py

In [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), the Exa integration is declared with a required credential field. Line 23 specifies that the `exa` feature requires the `exa_api_key` key, establishing the dependency without hardcoding sensitive values.

### CLI Auto-Configuration in cli.py

The command-line interface handles mcporter setup automatically. In [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 926-952), the CLI detects when the Exa configuration is missing and executes:

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

```

This command stores the MCP endpoint in [`config/mcporter.json`](https://github.com/Panniantong/Agent-Reach/blob/main/config/mcporter.json), enabling mcporter to forward subsequent RPC calls to the Exa service.

## Exa Channel Implementation via exa_search.py

The Exa channel implementation resides in [`agent_reach/channels/exa_search.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/exa_search.py). This module inherits from `BaseChannel` and acts as a thin wrapper around mcporter RPC calls.

### Search Methods

The channel exposes two primary methods:

- **search(query, numResults, ...)** → Constructs an mcporter call to `exa.web_search_exa`
- **get_code_context(query, tokensNum)** → Constructs an mcporter call to `exa.get_code_context_exa`

Neither method handles API keys directly. Instead, the MCP server injects authentication credentials configured in [`mcporter.json`](https://github.com/Panniantong/Agent-Reach/blob/main/mcporter.json) at runtime.

## Runtime Execution Flow

When an agent or user initiates a semantic search, the following flow occurs:

1. **Invocation** – The user calls the Exa channel via CLI (`python -m agent_reach.cli search "query"`) or programmatically through the Agent Reach library.
2. **RPC Construction** – The channel builds an mcporter command string, such as `mcporter call 'exa.web_search_exa(query: "...", numResults: N)'`.
3. **Subprocess Execution** – Agent Reach executes the mcporter command as a subprocess.
4. **MCP Routing** – mcporter contacts the MCP server at `https://mcp.exa.ai/mcp`, which forwards the request to Exa with the injected API key.
5. **Response Parsing** – The JSON result returns through mcporter to Agent Reach, which presents the structured data to the caller.

## Benefits of MCP Integration

The mcporter abstraction provides several architectural advantages:

- **Zero-Configuration Deployment** – The CLI auto-installs and configures mcporter, eliminating manual API key management for end users.
- **Uniform Interface** – All upstream services (Twitter, Reddit, Exa) use the identical `mcporter call` syntax, simplifying error handling and diagnostics.
- **Backend Flexibility** – The MCP server can be self-hosted or replaced without modifying Agent Reach application code.

## Code Examples

### Programmatic Usage

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

```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)'

```

### Configuration Verification

```bash
mcporter config list

```

Expected output includes:

```

exa  https://mcp.exa.ai/mcp

```

## Summary

- Agent Reach delegates Exa authentication to mcporter rather than managing API keys internally.
- 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).
- The Exa channel in [`agent_reach/channels/exa_search.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/exa_search.py) wraps mcporter RPC calls for `web_search_exa` and `get_code_context_exa`.
- Runtime execution follows a subprocess pattern where mcporter routes requests through the MCP server at `https://mcp.exa.ai/mcp`.
- This architecture provides API-key-free operation and consistent interfaces across multiple third-party services.

## Frequently Asked Questions

### Does Agent Reach store the Exa API key in its source code?

No. According to the source code in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), the application only declares that the `exa_api_key` is required. The actual credential is stored in [`config/mcporter.json`](https://github.com/Panniantong/Agent-Reach/blob/main/config/mcporter.json) and injected by the MCP server at runtime, keeping sensitive data out of the application repository.

### What happens if mcporter is not configured when I run an Exa search?

The CLI auto-detection logic in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 926-952) automatically runs `mcporter config add exa https://mcp.exa.ai/mcp` if the configuration is missing. This ensures the MCP endpoint is registered before attempting the semantic search.

### Can I use the Exa channel without installing mcporter?

No. The [`agent_reach/channels/exa_search.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/exa_search.py) implementation relies entirely on mcporter subprocess calls to communicate with the Exa service. Without mcporter installed and configured, the channel cannot execute search queries or retrieve code context.

### How does the MCP server handle authentication for Exa requests?

The MCP server at `https://mcp.exa.ai/mcp` injects the API key configured in [`mcporter.json`](https://github.com/Panniantong/Agent-Reach/blob/main/mcporter.json) when forwarding requests to Exa. This allows Agent Reach to make authenticated requests without ever handling the actual credentials in its Python code.