Troubleshooting mcporter and Exa Search MCP Configuration in Agent Reach

To restore Exa Search functionality in Agent Reach, install the mcporter MCP client globally via npm, register the Exa endpoint with mcporter config add exa https://mcp.exa.ai/mcp, and verify the configuration using agent-reach doctor.

Agent Reach acts as a glue layer that routes AI-agent requests to external tools through the Multipurpose Connect Protocol (MCP). For semantic web search capabilities, it relies on mcporter—a Node.js-based MCP client—to communicate with the Exa Search backend. When troubleshooting mcporter and Exa search MCP configuration issues, you must validate both the binary presence and the specific endpoint registration, as implemented in the ExaSearchChannel class.

How mcporter Integrates with Agent Reach

The search functionality is implemented in agent_reach/channels/exa_search.py through the ExaSearchChannel class. This channel does not directly call Exa’s API; instead, it validates that the mcporter binary is installed and configured to route requests to the Exa MCP server.

The Probe Validation Mechanism

The check() method in ExaSearchChannel uses probe_command() from agent_reach/probe.py to assess the MCP client status:

# agent_reach/channels/exa_search.py

probe = probe_command("mcporter", ["config", "list"], timeout=10, package="mcporter")

The probe evaluates four distinct states:

• Missing: The mcporter binary is not found in $PATH. The doctor reports this as "mcporter 未配置".
• Broken: The binary exists but crashes on execution (Node.js environment issues). The doctor reports "mcporter 执行异常".
• Installed but unconfigured: mcporter runs but config list lacks an exa entry. The doctor prompts you to run mcporter config add exa https://mcp.exa.ai/mcp.
• Operational: The output contains exa https://mcp.exa.ai/mcp. The doctor reports "全网语义搜索可用（免费，无需 API Key）".

Installing and Configuring mcporter

Agent Reach provides automated installation logic in agent_reach/cli.py that handles both the mcporter binary and the Exa MCP configuration.

Automated Installation via the CLI

The _install_mcporter() function checks for Node.js prerequisites before attempting installation:

# agent_reach/cli.py

if shutil.which("mcporter"):
    print("  ✅ mcporter already installed")
else:
    subprocess.run(["npm", "install", "-g", "mcporter"], …)

After successful installation, the CLI automatically configures the Exa MCP endpoint:

subprocess.run(
    ["mcporter", "config", "add", "exa", "https://mcp.exa.ai/mcp"],
    …
)

To run this installation flow, execute:

$ agent-reach install --channels all

Safe Mode and Manual Installation

If you prefer to review commands before execution, use _install_mcporter_safe() via the --safe flag:

$ python -m agent_reach.cli install --safe

This prints the required npm commands without modifying your system. For a manual installation, ensure Node.js is present, then run:

$ npm install -g mcporter
$ mcporter config add exa https://mcp.exa.ai/mcp

Verifying Your MCP Configuration

Agent Reach includes a diagnostic system in agent_reach/doctor.py that validates the entire tool chain.

Using the Doctor Command

The check_all() function in agent_reach/doctor.py executes each channel’s check() method, including the Exa Search probe. Run:

$ agent-reach doctor

Look for the line under "✅ 装好即用" indicating "全网语义搜索可用（免费，无需 API Key）". If this appears, the MCP client is correctly installed and configured.

Manual Configuration Checks

You can manually verify the configuration by running the same probe command used by the channel:

$ mcporter config list

# Expected output should include:

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

If the command fails or the exa entry is missing, the configuration is incomplete.

Common Failure Modes and Solutions

Symptom	Root Cause	Fix
"mcporter 未配置" in doctor	Binary not in $PATH or not installed	Install Node.js, then run npm install -g mcporter
"mcporter 执行异常"	Node.js environment corrupted or mismatched	Reinstall Node.js and mcporter: npm install -g mcporter
"Exa 未配置"	MCP endpoint not registered	Execute mcporter config add exa https://mcp.exa.ai/mcp
Doctor warns after fresh install	Silent npm failure or outdated version	Uninstall and reinstall: npm uninstall -g mcporter && npm install -g mcporter
Permission denied on Linux	npm attempting system-wide write without sudo	Configure user-local prefix: npm config set prefix "$HOME/.npm" and reinstall

Why Agent Reach Uses mcporter Instead of Direct API Keys

Exa Search offers a free, no-API-key endpoint via its MCP server at https://mcp.exa.ai/mcp. By using mcporter, Agent Reach abstracts the JSON-RPC communication over stdin/stdout, eliminating the need to embed API secrets in the repository. This architecture aligns with security best practices—no keys are stored in agent_reach/config.py or environment variables—while providing full semantic search capabilities. The mcporter_utf8_env_args() function in agent_reach/utils/process.py ensures proper UTF-8 encoding for these stdio-based interactions.

Summary

• Installation: Use npm install -g mcporter or the Agent Reach CLI installer in agent_reach/cli.py.
• Configuration: Register the Exa endpoint with mcporter config add exa https://mcp.exa.ai/mcp.
• Validation: Run agent-reach doctor to execute the check_all() diagnostics, or manually probe with mcporter config list.
• Troubleshooting: Match doctor error messages to the specific failure modes—missing binary, broken execution, or missing endpoint configuration.
• Security: The mcporter approach requires no API keys, leveraging the free Exa MCP endpoint securely.

Frequently Asked Questions

Do I need an API key for Exa Search in Agent Reach?

No. According to the ExaSearchChannel implementation in agent_reach/channels/exa_search.py, Exa Search operates through a free MCP endpoint at https://mcp.exa.ai/mcp that requires no authentication. Agent Reach does not store or request Exa API keys, as mcporter handles the protocol-level communication.

Why does the doctor command report mcporter as broken even after installation?

This indicates the Node.js environment is corrupted or the mcporter binary is incompatible with your system. The _install_mcporter() function in agent_reach/cli.py detects this as a broken probe status. Reinstall Node.js from the official distribution, then reinstall mcporter using npm install -g mcporter to resolve path or dependency issues.

Can I install mcporter without using the Agent Reach CLI?

Yes. While agent_reach/cli.py provides automated installation via _install_mcporter(), you can manually install mcporter using npm install -g mcporter and then manually add the Exa configuration with mcporter config add exa https://mcp.exa.ai/mcp. The CLI installer is a convenience wrapper around these standard npm commands.

How do I fix permission errors when installing mcporter with npm?

On Linux systems, npm may fail when attempting to write to system directories without elevated privileges. Instead of using sudo, configure a user-local npm prefix by running npm config set prefix "$HOME/.npm", ensure $HOME/.npm/bin is in your $PATH, and then reinstall mcporter. This avoids permission issues while maintaining a user-specific installation.

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