How to Configure Exa Search MCP via mcporter in Agent-Reach

Configure Exa search MCP via mcporter by installing the Node.js helper globally and registering the Exa endpoint at https://mcp.exa.ai/mcp, which enables free, full-text semantic search without requiring an API key.

Agent-Reach enables full-text semantic search through the Exa engine using a Model Context Protocol (MCP) architecture. The integration relies on mcporter, a lightweight Node.js helper that registers the Exa MCP endpoint, allowing the CLI to automatically detect and configure the connection according to the source code in Panniantong/Agent-Reach.

Understanding the Exa MCP Integration

The Exa search functionality operates through an MCP-based bridge rather than direct API integration. The mcporter tool registers https://mcp.exa.ai/mcp as a search provider, and the ExaSearchChannel class in agent_reach/channels/exa_search.py validates this registration. This architecture makes the Exa service free when accessed through its public MCP interface, eliminating the need for API key management.

Prerequisites

Before configuring, ensure you have Node.js version 12 or higher installed to support the mcporter package. The agent_reach/cli.py installer specifically checks for the mcporter executable using shutil.which("mcporter") (lines 830-838).

Manual Configuration Steps

Step 1: Install mcporter

Install the mcporter package globally using npm. This provides the executable that Agent-Reach detects during its setup routine.

npm install -g mcporter

Verify the installation by checking that mcporter is available on your PATH:

which mcporter

# Expected output: /usr/local/bin/mcporter (or similar path)

Step 2: Register the Exa MCP Endpoint

Register the Exa search endpoint using mcporter. This command corresponds to the logic found in agent_reach/cli.py lines 846-851, which executes automatically when the Exa MCP is not present.

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

If the endpoint is already registered, mcporter will skip registration without errors.

Step 3: Verify Registration

Confirm that the Exa MCP is properly listed in your configuration. This mirrors the inspection logic in agent_reach/cli.py lines 839-845, which searches the output of mcporter config list for the string "exa".

mcporter config list | grep exa

# Expected output contains: "exa    https://mcp.exa.ai/mcp"

Automated Configuration via Agent-Reach CLI

The agent-reach install command automates the entire configuration flow. According to the source code in agent_reach/cli.py (lines 830-851), the CLI performs a four-step detection and registration process:

1. Detection: Checks for the mcporter executable using shutil.which("mcporter") (lines 830-838)
2. Inspection: Runs mcporter config list and inspects stdout for the word exa (lines 839-845)
3. Registration: If exa is not found, executes mcporter config add exa https://mcp.exa.ai/mcp (lines 846-851)
4. Validation: The ExaSearchChannel.check() method confirms channel readiness

You can replicate this automation in Python:

import subprocess
import shutil

def ensure_exa_mcp():
    # Step 1: Ensure mcporter is installed

    if not shutil.which("mcporter"):
        subprocess.run(["npm", "install", "-g", "mcporter"], check=True)
    
    # Step 2: Check existing MCPs

    result = subprocess.run(
        ["mcporter", "config", "list"],
        capture_output=True,
        text=True,
        timeout=5
    )
    
    # Step 3: Add Exa if missing

    if "exa" not in result.stdout.lower():
        subprocess.run(
            ["mcporter", "config", "add", "exa", "https://mcp.exa.ai/mcp"],
            check=True
        )
    
    print("✅ Exa search MCP configured")

ensure_exa_mcp()

Verifying Configuration with ExaSearchChannel

After configuration, verify the integration programmatically using the channel's built-in health check. The check() method in agent_reach/channels/exa_search.py (lines 18-36) verifies that mcporter is present and the Exa MCP is registered, returning "ok" when ready.

from agent_reach.channels.exa_search import ExaSearchChannel

status, message = ExaSearchChannel().check()
print(f"Status: {status} - {message}")

# Expected: status == "ok" and message mentions "全网语义搜索可用（免费，无需 API Key）"

Summary

• Install mcporter globally using npm install -g mcporter to provide the MCP registration utility
• Register the endpoint at https://mcp.exa.ai/mcp using mcporter config add exa https://mcp.exa.ai/mcp
• Automated detection in agent_reach/cli.py (lines 830-851) handles the configuration flow when running agent-reach install
• Verify readiness by calling ExaSearchChannel().check(), which returns "ok" when the channel is operational
• No API key required for Exa search when accessed through the MCP interface

Frequently Asked Questions

Do I need an API key to use Exa search with Agent-Reach?

No. When accessing Exa through the MCP endpoint at https://mcp.exa.ai/mcp, the service is free and does not require an API key. The ExaSearchChannel.check() method confirms this by returning a message indicating that the global semantic search is available without API credentials.

What happens if mcporter is not installed?

The Agent-Reach CLI detects the missing executable via shutil.which("mcporter") in agent_reach/cli.py (lines 830-838) and will prompt you to install it. You can install it manually with npm install -g mcporter or allow the automated installer to handle the dependency.

How can I check if the Exa MCP is properly configured?

Run mcporter config list and look for the exa entry pointing to https://mcp.exa.ai/mcp. Alternatively, programmatically call ExaSearchChannel().check() from agent_reach/channels/exa_search.py (lines 18-36), which returns a tuple with status "ok" when the channel is ready for semantic search operations.

Can I use Exa search without mcporter?

No. According to the source code in agent_reach/channels/exa_search.py, the ExaSearchChannel explicitly verifies mcporter presence and MCP registration during its initialization check. Without mcporter, the channel cannot register or communicate with the Exa MCP endpoint, and the check will fail.

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