How Exa Search Integration via mcporter Functions in Agent Reach

Agent Reach delegates semantic search operations to the external mcporter MCP binary, validating its presence and Exa endpoint configuration before exposing a zero-API-key search capability.

Agent Reach implements semantic search through the Exa service by integrating with the mcporter Model Context Protocol (MCP) command-line tool. The ExaSearchChannel class in agent_reach/channels/exa_search.py manages this integration by probing the system for the binary, verifying its configuration, and enabling the CLI to perform free, global semantic searches without internal search logic.

Validating the mcporter Binary

The integration begins with the check() method executing probe_command() from agent_reach/probe.py to run mcporter config list. This probe determines if the binary is present, executable, and returns a list of configured backends.

The probe logic distinguishes between critical states:

• Missing: The binary is not found in the system PATH
• Broken: The binary exists but cannot execute (e.g., stale interpreter or corrupted installation)
• Configured: The binary runs successfully and returns available MCP backends

If probe_command() returns status == "missing", the channel reports off and instructs the user to run npm install -g mcporter. When status == "broken", it returns an error state with a reinstall hint.

Configuring the Exa MCP Endpoint

Once the binary is confirmed executable, ExaSearchChannel analyzes the output of mcporter config list to verify the Exa endpoint exists. The code explicitly checks if the string "exa" appears in the configuration output.

If Exa is not configured, the channel remains off and prompts the user to add the endpoint:

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

When the output contains "exa", the channel sets self.active_backend = self.backends[0] and returns ok with the message "全网语义搜索可用（免费，无需 API Key）", indicating that global semantic search is available without requiring an API key.

Performing Semantic Searches

Agent Reach does not implement search logic internally. Instead, it delegates all operations to the mcporter binary after validation succeeds. The CLI or agent code calls mcporter directly with search queries.

To check the channel status programmatically:

from agent_reach.channels.exa_search import ExaSearchChannel
from agent_reach.config import Config

cfg = Config()                      # loads ~/.agent-reach/config.yaml

exa = ExaSearchChannel()
status, msg = exa.check(cfg)        # runs the mcporter probe

print(status, msg)                  # -> "ok"  "全网语义搜索可用（免费，无需 API Key）"

To execute a search from Python:

import subprocess
import shlex

def exa_search(query: str, limit: int = 10):
    cmd = f"mcporter search '{query}' --limit {limit}"
    result = subprocess.run(shlex.split(cmd), capture_output=True, text=True)
    result.check_returncode()
    return result.stdout   # JSON or plain text from the Exa MCP

Integration with System Diagnostics

The Exa search channel integrates with Agent Reach's diagnostic system through agent_reach/doctor.py. This module aggregates health checks from all channels to provide unified status reporting via the agent-reach doctor command.

The configuration handling in agent_reach/config.py supports this integration by managing global configuration state, though Exa specifically requires no API keys or additional configuration files beyond the mcporter setup.

Summary

• ExaSearchChannel validates the mcporter binary through probe_command() in agent_reach/probe.py, distinguishing between missing, broken, and functional states.
• The channel verifies Exa configuration by parsing mcporter config list output for the "exa" string before marking self.active_backend and returning ok status.
• All search operations are delegated to the external mcporter CLI tool, requiring no API keys or internal search implementation in Agent Reach.
• Users install mcporter via npm install -g mcporter and configure the Exa endpoint at https://mcp.exa.ai/mcp to enable the channel.
• Integration with agent_reach/doctor.py provides system-wide health diagnostics for the Exa search capability.

Frequently Asked Questions

What is mcporter and why does Agent Reach use it?

mcporter is a command-line Model Context Protocol (MCP) tool that Agent Reach uses to interface with the Exa semantic search service. According to the source code in agent_reach/channels/exa_search.py, Agent Reach delegates search operations to this external binary rather than implementing search logic internally, allowing the system to provide free, global semantic search without managing API keys or search algorithms directly.

How do I install and configure mcporter for Exa search?

Install the tool globally using npm with npm install -g mcporter. Then configure the Exa MCP endpoint by running mcporter config add exa https://mcp.exa.ai/mcp. The ExaSearchChannel.check() method verifies this configuration by probing the binary and checking for "exa" in the config list output before reporting the channel as active.

What happens if mcporter is installed but not working correctly?

If the binary exists but cannot execute—for example, due to a stale virtual environment or missing interpreter—probe_command() in agent_reach/probe.py returns a status of "broken". The ExaSearchChannel then reports an error state and suggests reinstalling the package to resolve the execution issue.

Does Agent Reach require an Exa API key?

No. The implementation in agent_reach/channels/exa_search.py explicitly confirms that the Exa search integration works without API keys. When properly configured, the channel returns the message "全网语义搜索可用（免费，无需 API Key）", confirming that the global semantic search is available for free without requiring API key authentication.

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