# Troubleshooting mcporter and Exa Search MCP Configuration in Agent Reach

> Troubleshoot mcporter and Exa Search MCP configuration in Agent Reach. Install mcporter, register Exa, and verify with agent-reach doctor for seamless search functionality.

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

---

**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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/probe.py) to assess the MCP client status:

```python

# 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`](https://github.com/Panniantong/Agent-Reach/blob/main/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:

```python

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

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

```

To run this installation flow, execute:

```bash
$ 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:

```bash
$ 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:

```bash
$ 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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) that validates the entire tool chain.

### Using the Doctor Command

The `check_all()` function in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) executes each channel’s `check()` method, including the Exa Search probe. Run:

```bash
$ 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:

```bash
$ 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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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.