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

> Learn how mcporter integrates with Exa in Agent-Reach for powerful semantic search. Centralized credential management ensures secure API access for advanced queries.

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

---

**The mcporter configuration system in Agent-Reach provides centralized credential management that enables the Exa channel to authenticate and execute semantic search queries through the Exa API.**

Agent-Reach routes read and search requests to platform-specific channel classes using the mcporter configuration structure. This integration allows the Exa semantic search service to authenticate API requests and return relevance-ranked results through a unified interface.

## Understanding the mcporter Configuration Structure

The mcporter integration begins with a JSON configuration file that stores sensitive credentials and endpoint parameters required by the Exa API.

### The config/mcporter.json File

The file [`config/mcporter.json`](https://github.com/Panniantong/Agent-Reach/blob/main/config/mcporter.json) acts as the single source of truth for Exa credentials. When Agent-Reach initializes, [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) reads this JSON file to extract the API key, optional organization ID, and custom endpoint overrides.

```json
{
  "exa": {
    "api_key": "YOUR_EXA_API_KEY",
    "base_url": "https://api.exa.ai"
  }
}

```

### Configuration Loading in agent_reach/config.py

The `Config` class exposes the `get_mcporter()` method that returns the parsed configuration dictionary. This centralized access pattern ensures that any component requiring Exa credentials receives them through a consistent interface, eliminating the need to hardcode secrets in individual modules.

## Exa Channel Implementation and Authentication

The Exa channel implementation bridges the mcporter configuration with the Exa API, handling HTTP client construction and request authentication.

### Channel Registration in agent_reach/core.py

[`agent_reach/core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py) maintains a registry of channel classes during initialization. The Exa channel ([`agent_reach/channels/exa.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/exa.py)) registers itself as a concrete subclass of `BaseChannel` and advertises its capability to handle URLs or queries targeted at Exa through the `can_handle()` method.

### HTTP Client Setup with mcporter Credentials

When the Exa channel constructor executes, it pulls settings from the global `Config` object via `Config.get_mcporter()`. The channel builds an HTTP client and stores the API key in the `Authorization` header for all subsequent requests to the Exa endpoints.

## Executing Semantic Search Requests

Semantic search operations flow through the Exa channel's search method, which transforms user queries into authenticated API calls and normalizes the responses.

### The search() Method Workflow

The `search(query: str)` method in [`agent_reach/channels/exa.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/exa.py) sends a POST request to the Exa endpoint `/v1/search` with the query string and the `"semantic": true` flag. The Exa service processes the semantic query and returns a list of results containing similarity scores and highlighted snippets.

```python
from agent_reach.core import AgentReach

# Initialise the library (loads mcporter config automatically)

agent = AgentReach()

# Execute a semantic search via the Exa provider

results = agent.search("latest advances in quantum computing", provider="exa")

for r in results:
    print(f"{r.title}\n{r.snippet}\nScore: {r.score:.2f}\n")

```

### Result Normalization to SearchResult Model

Raw JSON payloads from Exa undergo transformation into the common `SearchResult` model defined in [`agent_reach/core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py). This normalization ensures that downstream components—including CLI tools, libraries, and external agents—consume a uniform result shape regardless of the underlying search provider.

## CLI Integration and Usage

The top-level CLI ([`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)) exposes the `search` command, which forwards requests to the core routing layer. When users specify `--provider exa` or when queries match Exa-specific heuristics, the CLI dispatches to the Exa channel and prints formatted tables using the rich library.

```bash
python -m agent_reach.cli search "latest advances in quantum computing" --provider exa

```

The CLI output displays titles, snippets, and relevance scores returned by the Exa semantic engine, all authenticated through the mcporter configuration system.

## Summary

- **mcporter configuration** stores Exa API credentials in [`config/mcporter.json`](https://github.com/Panniantong/Agent-Reach/blob/main/config/mcporter.json) and exposes them via `Config.get_mcporter()` in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py).
- **Channel architecture** registers the Exa implementation in [`agent_reach/channels/exa.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/exa.py) as a `BaseChannel` subclass, enabling automatic discovery by the core system.
- **Authentication flow** injects mcporter credentials into HTTP headers during Exa channel construction, ensuring secure API access.
- **Semantic search** executes through POST requests to `/v1/search` with the semantic flag enabled, returning relevance-ranked results.
- **Result normalization** converts Exa responses into the standard `SearchResult` model for cross-platform compatibility.

## Frequently Asked Questions

### How does Agent-Reach handle Exa API authentication?

Agent-Reach retrieves the Exa API key from the mcporter configuration file and injects it into the Authorization header of every HTTP request sent by the Exa channel. This occurs during channel initialization in [`agent_reach/channels/exa.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/exa.py) when the constructor calls `Config.get_mcporter()`.

### What file path contains the mcporter configuration for Exa?

The configuration resides at [`config/mcporter.json`](https://github.com/Panniantong/Agent-Reach/blob/main/config/mcporter.json) in the repository root. This JSON file contains the Exa API key, base URL, and optional organization parameters required for authenticated semantic search operations.

### Can I use the Exa semantic search without the CLI?

Yes. You can import the `AgentReach` class from [`agent_reach/core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py) and call the `search()` method directly with the `provider="exa"` parameter. This programmatic approach uses the same mcporter authentication flow and returns normalized `SearchResult` objects containing titles, snippets, and similarity scores.

### What endpoint does the Exa channel use for semantic queries?

The Exa channel sends POST requests to `/v1/search` at the base URL specified in the mcporter configuration. The request payload includes the query string and `"semantic": true` to enable semantic rather than keyword-based matching.