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

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 repository:

• mcporter binary – A Node.js CLI that reads 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), 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), 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.

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.

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

This command creates the entry:

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

You can also use --scope project to write to 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:

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/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:

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:

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).

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/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)	ExaSearchChannel.check() implements configuration detection
[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)	Project-level mcporter configuration template
[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)	Core routing for search() API calls

Troubleshooting Common Issues

mcporter Not Found

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

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
• 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:

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() 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}