# How mcporter Integrates with Exa for Semantic Search in Agent Reach

> Learn how Agent Reach integrates mcporter and Exa for seamless semantic search. mcporter acts as a gateway, enabling zero-configuration search without direct API key management.

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

---

**Agent Reach routes every Exa API request through mcporter, an MCP (Micro-Control-Plane) gateway that abstracts third-party services, enabling zero-configuration semantic search without direct API key management in the application code.**

Agent Reach leverages mcporter to provide semantic web search capabilities through Exa without embedding API credentials directly in the codebase. Instead of calling Exa's REST API directly, the framework channels all requests through an MCP gateway that handles authentication, routing, and uniform RPC serialization. This architecture centralizes third-party service management while maintaining consistent error handling across all integrations.

## Configuration and Auto-Setup

Agent Reach automates the mcporter configuration during initialization, eliminating manual setup steps for developers.

### 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 as a feature requiring the `exa_api_key` credential (line 23). This declaration signals to the CLI that Exa support is available but requires proper MCP gateway configuration before use.

### Automated CLI Configuration

The [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) module (lines 926-952) contains auto-configuration logic that detects missing mcporter entries 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), which mcporter references to route subsequent RPC calls to the Exa service. The CLI handles this automatically during the first invocation of an Exa-backed command, ensuring the gateway is ready before any search operations occur.

## The Exa Channel Implementation

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 search functionality by inheriting from `BaseChannel` and wrapping all operations in mcporter RPC calls.

### RPC Call Construction

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

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

### Credential Abstraction

The channel implementation contains **no API key references**. Instead, the MCP server specified in [`mcporter.json`](https://github.com/Panniantong/Agent-Reach/blob/main/mcporter.json) intercepts the outgoing request, injects the `exa_api_key` from its secure configuration store, and forwards the authenticated request to Exa's API. This separation ensures that sensitive credentials never appear in application logs or channel source code.

## Runtime Execution Flow

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

1. **Invocation**: The user calls the Exa channel via the Agent Reach CLI (`python -m agent_reach.cli search "query"`) or programmatically through the library interface.
2. **Command Construction**: The channel builds the appropriate mcporter RPC command string with escaped parameters.
3. **Subprocess Execution**: Agent Reach spawns a subprocess executing `mcporter call ...`, which reads the endpoint configuration from [`config/mcporter.json`](https://github.com/Panniantong/Agent-Reach/blob/main/config/mcporter.json).
4. **MCP Gateway Processing**: mcporter contacts the MCP server at `https://mcp.exa.ai/mcp`, which authenticates the request using the stored API key.
5. **Response Routing**: The MCP server returns the JSON result from Exa, which mcporter pipes back to Agent Reach for parsing and presentation.

## Practical Implementation Examples

### Library Usage

Access Exa semantic search programmatically through the Agent Reach interface:

```python
from agent_reach.core import AgentReach

ar = AgentReach()
results = ar.search_exa(query="machine learning advances", numResults=5)

for hit in results["hits"]:
    print(f"{hit['title']}: {hit['url']}")

```

### CLI Invocation

Execute searches directly from the command line:

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

```

The output should contain:

```

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

```

## Benefits of the mcporter Integration

- **Zero-configuration deployment**: The CLI auto-installs and configures mcporter, allowing agents to use Exa immediately without manual API key management.
- **Uniform RPC interface**: All upstream services (Twitter, Reddit, Exa) use the same `mcporter call ...` syntax, standardizing error handling and diagnostics across the codebase.
- **Simplified credential rotation**: API keys live only in the MCP server configuration, not in application code or environment variables scattered across deployments.
- **Backend flexibility**: The MCP server can be self-hosted or swapped for custom implementations without modifying [`exa_search.py`](https://github.com/Panniantong/Agent-Reach/blob/main/exa_search.py) or other Agent Reach components.

## Summary

- Agent Reach uses **mcporter** as an MCP gateway to route all Exa API requests, avoiding direct HTTP client integration.
- Configuration is automated through [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 926-952), which registers the Exa endpoint at `https://mcp.exa.ai/mcp` in [`config/mcporter.json`](https://github.com/Panniantong/Agent-Reach/blob/main/config/mcporter.json).
- The **Exa channel** ([`agent_reach/channels/exa_search.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/exa_search.py)) builds RPC call strings and delegates execution to mcporter, remaining agnostic to API keys.
- **Credentials are injected** by the MCP server, not the application, enhancing security and simplifying deployment.
- Users interact with Exa through standard Python method calls or CLI commands while mcporter handles the underlying protocol translation.

## Frequently Asked Questions

### What is mcporter in the context of Agent Reach?

**mcporter is an MCP (Micro-Control-Plane) gateway that acts as a generic abstraction layer for third-party services.** In Agent Reach, it functions as a local RPC router that forwards service-specific commands to appropriate MCP servers, handling authentication and protocol translation so that the main application code remains service-agnostic.

### Why doesn't Agent Reach call the Exa API directly?

**Direct API integration would require embedding authentication credentials and HTTP client logic throughout the codebase.** By routing through mcporter, Agent Reach maintains a clean separation between application logic and service-specific implementations, allowing the MCP server to centrally manage API keys, rate limiting, and endpoint URLs.

### How is the Exa API key managed if it's not in the code?

**The API key is stored in the MCP server configuration accessible to mcporter.** When [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) declares the `exa_api_key` requirement, the MCP server uses this value to authenticate requests to `https://mcp.exa.ai/mcp`. The Exa channel only constructs the RPC payload; the gateway injects the actual credentials before forwarding the request to Exa's servers.

### Can I use a custom MCP server instead of Exa's hosted endpoint?

**Yes, the architecture supports pluggable MCP servers.** By modifying the entry in [`config/mcporter.json`](https://github.com/Panniantong/Agent-Reach/blob/main/config/mcporter.json) or using `mcporter config add exa <your-custom-endpoint>`, you can redirect Exa traffic to a self-hosted MCP instance or proxy server without changing any code in [`agent_reach/channels/exa_search.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/exa_search.py).