How to Configure Exa Search via mcporter MCP for Full-Web Semantic Search in Agent Reach

Agent Reach enables free, AI-driven semantic web search through the ExaSearchChannel by routing requests via mcporter, a Node.js MCP bridge that requires no API key when configured with the Exa MCP endpoint.

Agent Reach is an open-source AI agent framework that supports full-web semantic search without requiring paid API credentials. By leveraging the Exa MCP (Model Context Protocol) through mcporter, you can configure Agent Reach to perform intelligent web searches across the entire internet using AI-powered semantic understanding.

Installing mcporter

Before configuring Exa search, you must install the mcporter utility globally. This Node.js application acts as the MCP bridge between Agent Reach and Exa's semantic search API.

# Install mcporter globally using npm

npm install -g mcporter

# Verify installation

mcporter --version

The mcporter binary must be available in your system PATH for Agent Reach to detect it. If the command returns a version number (e.g., 1.2.0), the installation succeeded.

Configuring the Exa MCP Endpoint

Once mcporter is installed, add the Exa MCP endpoint to enable semantic search capabilities. This configuration stores the endpoint URL in mcporter's local JSON config file.

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

You should see a confirmation message similar to ✅ Added exa → https://mcp.exa.ai/mcp. This command creates or updates the local MCP configuration that Agent Reach queries during its initialization phase.

The repository includes a default reference configuration at config/mcporter.json that documents the expected structure for the Exa endpoint.

Verifying the Configuration

Agent Reach provides a built-in diagnostic command to verify that Exa search is properly configured. The doctor command in agent_reach/cli.py (lines 928-951 and 1486-1510) automatically probes the mcporter configuration and reports the channel status.

python -m agent_reach.cli doctor

Look for the output line indicating Exa search availability:

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

If the channel reports "off", the diagnostic checks failed. This occurs when:

• mcporter is missing: The binary was not found in PATH. Re-run the npm installation.
• Exa endpoint not configured: Run mcporter config add exa https://mcp.exa.ai/mcp to register the endpoint.

The verification logic is implemented in agent_reach/channels/exa_search.py, where the ExaSearchChannel.check() method executes probe_command("mcporter", ["config","list"]) to validate the setup.

Performing Semantic Searches

Once configured, you can invoke Exa search through two primary interfaces: the CLI and skill-based MCP calls.

Command Line Interface

Use the search command with the --backend flag to specify Exa search:

python -m agent_reach.cli search "latest AI research trends" --backend exa_search

The CLI routes the query through agent_reach/core.py, which forwards the request to the active Exa backend via mcporter. Results return as numbered entries with URLs and semantic snippets.

Skill and Agent Integration

Inside Agent Reach skills or prompts, invoke Exa search using the MCP call syntax documented in agent_reach/skill/references/search.md:

mcporter call 'exa.web_search_exa(query: "python asyncio tutorial", numResults: 3)'

This command executes the JSON-RPC protocol through mcporter, returning structured search results that skills can parse and render. The numResults parameter controls the number of semantic matches returned (default varies by implementation).

Architecture and Implementation Details

Understanding the underlying architecture helps troubleshoot configuration issues and optimize search behavior.

ExaSearchChannel Probe Logic

The ExaSearchChannel class in agent_reach/channels/exa_search.py implements a three-state verification system:

1. Binary Check: Verifies mcporter exists via probe_command("mcporter", ["config","list"])
2. Endpoint Validation: Confirms the Exa entry exists in the MCP configuration
3. Backend Activation: Sets self.active_backend to the Exa backend when validation passes

If the Exa MCP entry is missing, the channel returns status "off" with instructions to run the configuration command.

Core Routing

The agent_reach/core.py dispatcher handles all search requests generically. When a search request arrives, it checks the active channel status. If the Exa channel is active, the request routes through the MCP bridge, converting the internal search API into mcporter-compatible JSON-RPC calls to https://mcp.exa.ai/mcp.

Zero-API-Key Access

A key advantage of this configuration is zero API key requirement. Exa's free tier is accessible through the MCP endpoint without authentication tokens, making it ideal for development and production deployments without credential management overhead.

Summary

• Install mcporter globally via npm install -g mcporter to enable the MCP bridge
• Configure the endpoint using mcporter config add exa https://mcp.exa.ai/mcp to register Exa's semantic search
• Verify setup by running python -m agent_reach.cli doctor to confirm the ExaSearchChannel reports "ok"
• Execute searches via CLI commands or MCP calls using exa.web_search_exa(query: "...", numResults: N)
• No API key required when using the MCP endpoint, reducing deployment complexity

Frequently Asked Questions

Why does the doctor command report "off" for exa_search?

The "off" status indicates that either mcporter is not installed in your system PATH or the Exa MCP endpoint is not configured. First, verify mcporter is installed with mcporter --version. If installed, run mcporter config add exa https://mcp.exa.ai/mcp to add the endpoint, then re-run the doctor command.

Can I use Exa search without installing mcporter?

No. Agent Reach requires mcporter as the intermediary to handle the JSON-RPC protocol and MCP communication with Exa's servers. The ExaSearchChannel explicitly probes for this binary in agent_reach/channels/exa_search.py and will not activate without it.

How do I change the number of search results returned?

When invoking Exa search from a skill or prompt, include the numResults parameter in the MCP call: mcporter call 'exa.web_search_exa(query: "your query", numResults: 10)'. The default value varies by implementation, but you can override it up to Exa's service limits.

Where is the mcporter configuration stored?

mcporter maintains its configuration in a local JSON file managed by the utility itself, not within Agent Reach's directory. The repository includes a reference file at config/mcporter.json showing the expected structure, but live configuration is handled by mcporter's config subcommands.

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