How Exa Search Is Auto-Configured in Agent Reach: Zero-Config Setup Guide

Agent Reach automatically configures Exa search during the install command by detecting the mcporter CLI tool, adding the free Exa MCP endpoint if absent, and validating the connection through health checks—all without requiring API keys.

Agent Reach treats Exa search as a tier-0 "zero-config" channel that activates immediately after installation. This guide explains the auto-configuration mechanism implemented in the Panniantong/Agent-Reach repository, covering the CLI installation flow in agent_reach/cli.py, channel health checks, and verification methods.

The Auto-Configuration Flow in agent_reach/cli.py

The installation routine handles Exa search setup through a three-step process that executes automatically during python -m agent_reach.cli install.

Detecting the mcporter Dependency

First, the CLI verifies that mcporter is installed using shutil.which("mcporter"). If the binary is missing, the installation prompts you to run npm install -g mcporter before proceeding.

Querying Existing MCP Configurations

After confirming mcporter availability, the CLI executes mcporter config list via subprocess.run to inspect current Model Context Protocol configurations (lines 21-33 in agent_reach/cli.py):

r = subprocess.run(
    ["mcporter", "config", "list"], capture_output=True, encoding="utf-8",
    errors="replace", timeout=5
)

Automatically Adding the Exa Endpoint

If the output lacks the exa keyword, the CLI automatically registers the free Exa MCP endpoint (lines 24-33 in agent_reach/cli.py):

subprocess.run(
    ["mcporter", "config", "add", "exa", "https://mcp.exa.ai/mcp"],
    capture_output=True, encoding="utf-8", errors="replace", timeout=10,
)
print("  ✅ Exa search configured (free, no API key needed)")

This configuration requires no API key because the service operates through the free MCP endpoint at https://mcp.exa.ai/mcp.

Runtime Validation in agent_reach/channels/exa_search.py

The ExaSearchChannel class validates the auto-configuration through its check method (lines 21-38 in agent_reach/channels/exa_search.py). This method reuses the same mcporter config list probe.

When the output contains exa, the channel sets self.active_backend = self.backends[0] and returns "ok", marking the channel as active and ready for semantic search queries.

Verifying Auto-Configuration with the Doctor Command

When you run agent-reach doctor, the doctor module in agent_reach/doctor.py (lines 12-34) aggregates channel statuses. For Exa search, it displays:

✅ 全网语义搜索可用（免费，无需 API Key）

This confirms the MCP endpoint persists correctly in your configuration and the channel is operational.

Manual Configuration and Troubleshooting

If automatic setup fails, manually add the Exa MCP endpoint:

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

Verify installation programmatically using the same probe pattern from the channel implementation:

from agent_reach.probe import probe_command

probe = probe_command("mcporter", ["config", "list"], timeout=10, package="mcporter")
if "exa" in probe.output.lower():
    print("Exa is configured")
else:
    print("Exa not configured")

Run the installation to trigger auto-configuration:

python -m agent_reach.cli install

Expected output includes:

  ✅ mcporter installed
  ✅ Exa search configured (free, no API key needed)

Summary

• Agent Reach auto-configures Exa search during the install command as a zero-config tier-0 channel.
• The CLI in agent_reach/cli.py detects mcporter, lists existing configs, and automatically adds the Exa MCP endpoint if missing.
• No API key is required because the service uses the free MCP endpoint at https://mcp.exa.ai/mcp.
• The ExaSearchChannel.check method in agent_reach/channels/exa_search.py validates the configuration by scanning mcporter config list output.
• Use agent-reach doctor to verify the auto-configuration status displays the confirmation message indicating free, keyless access.

Frequently Asked Questions

Does Exa search require an API key in Agent Reach?

No. Agent Reach configures Exa search using the free MCP endpoint at https://mcp.exa.ai/mcp, which does not require authentication. The auto-configuration in agent_reach/cli.py adds this endpoint automatically during installation.

What happens if mcporter is not installed when I run agent-reach install?

The CLI checks for mcporter using shutil.which("mcporter") at the beginning of the installation routine. If the tool is missing, the user is prompted to install it globally via npm install -g mcporter before the Exa auto-configuration proceeds.

How can I verify that Exa search is properly configured?

Run python -m agent_reach.cli doctor or agent-reach doctor. The doctor module aggregates channel statuses from agent_reach/doctor.py and will display "✅ 全网语义搜索可用（免费，无需 API Key）" if the Exa MCP endpoint is properly registered in your mcporter configuration.

Where is the Exa search configuration stored?

The configuration is stored within the mcporter tool's internal configuration, not in Agent Reach files. The CLI modifies this configuration by running mcporter config add exa https://mcp.exa.ai/mcp, which persists the endpoint for use by the ExaSearchChannel class.

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