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

You can enable free semantic web search in Agent-Reach by installing the mcporter Node.js utility, running mcporter config add exa https://mcp.exa.ai/mcp to register the Exa MCP endpoint, and verifying the configuration with the built-in doctor command.

Agent-Reach provides a dedicated ExaSearchChannel that leverages mcporter to perform AI-driven semantic searches without requiring an Exa API key. This integration routes web search requests through the Model Context Protocol (MCP), allowing the framework to query the entire internet using Exa's free tier. By configuring mcporter correctly, you unlock the exa_search backend for both CLI operations and programmatic skill invocations.

Install mcporter

Before configuring the Exa backend, you must install the mcporter binary globally. This Node.js utility acts as a bridge between Agent-Reach and the Exa MCP server.

# Install globally (requires Node.js and npm)

npm install -g mcporter

# Verify installation

mcporter --version

# Expected output: version number (e.g., 1.2.0)

If the binary is not found in your system PATH, the Exa search channel will report a "missing dependency" status during initialization.

Register the Exa MCP Endpoint

Once mcporter is installed, register the Exa MCP server endpoint. This step stores the configuration in mcporter's local JSON store (referenced in config/mcporter.json in the repository).

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

You should see a confirmation message like:

✅ Added exa → https://mcp.exa.ai/mcp

This command creates the necessary mapping that allows Agent-Reach to route search queries to Exa's semantic search engine without an API key.

Verify Configuration with the Doctor Command

Agent-Reach includes a diagnostic tool that automatically probes the Exa search configuration. Run the following to verify the setup:

python -m agent_reach.cli doctor

The diagnostic logic in agent_reach/cli.py (lines 928-951) executes ExaSearchChannel.check(), which probes mcporter using probe_command("mcporter", ["config","list"]).

If configured correctly, you will see:

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

If the status reports "off", repeat the endpoint registration step or check that mcporter is in your system PATH.

Performing Web Searches

Command Line Interface

With the Exa channel active, execute semantic searches directly from the terminal:

python -m agent_reach.cli search "latest transformer architectures" --backend exa_search

The CLI forwards the request to agent_reach/core.py, which routes the query through the MCP bridge and returns a list of URLs with semantic snippets.

From Within a Skill

You can invoke Exa search programmatically from any Agent-Reach skill using the MCP call syntax documented in agent_reach/skill/references/search.md:

mcporter call 'exa.web_search_exa(query: "python asyncio patterns", numResults: 5)'

The response returns structured JSON containing URLs, titles, and content snippets that your skill can parse and render.

How the Integration Works

Probe Logic and Channel Activation

The agent_reach/channels/exa_search.py module implements the ExaSearchChannel class. When initialized, it runs a probe via probe_command("mcporter", ["config","list"]) to verify:

1. The mcporter binary exists in the system PATH.
2. An entry for the Exa MCP endpoint exists in the mcporter configuration.

If the Exa entry is found, self.active_backend is set to the Exa backend and the channel reports status "ok". If mcporter is missing or the endpoint is not configured, the channel reports "off" and the CLI (lines 1486-1510 in agent_reach/cli.py) prints specific remediation instructions.

Zero-API-Key Architecture

Unlike traditional search integrations that require authentication tokens, this configuration leverages Exa's free MCP tier. The endpoint https://mcp.exa.ai/mcp accepts JSON-RPC requests without API keys when accessed through mcporter, enabling zero-cost semantic search for Agent-Reach users.

Configuration Storage

While mcporter maintains its own local configuration store, the repository includes a reference template at config/mcporter.json. This file documents the expected schema for MCP endpoints and serves as a fallback reference during automated installation scripts.

Summary

• Install mcporter globally using npm to provide the MCP bridge binary.
• Register the endpoint with mcporter config add exa https://mcp.exa.ai/mcp to enable the Exa backend.
• Verify setup by running python -m agent_reach.cli doctor, which checks agent_reach/channels/exa_search.py probe logic.
• Search via CLI using --backend exa_search or from skills using the mcporter call syntax.
• No API key required—the integration uses Exa's free MCP tier for full-web semantic search.

Frequently Asked Questions

Do I need an Exa API key to use this feature?

No. The mcporter configuration uses the public MCP endpoint https://mcp.exa.ai/mcp, which provides free access to Exa's semantic search capabilities without authentication tokens. This is confirmed by the probe logic in agent_reach/channels/exa_search.py that activates the channel solely based on the endpoint configuration, not API credentials.

What should I do if the doctor command reports "off" for exa_search?

First, verify that mcporter is installed and available in your PATH by running mcporter --version. If the binary exists but the status remains "off", the Exa endpoint is missing from your mcporter configuration. Run mcporter config add exa https://mcp.exa.ai/mcp and rerun the doctor command. The diagnostic output in agent_reach/cli.py will update to reflect the active backend once the probe detects the configured endpoint.

How do I invoke Exa search from inside a custom skill?

Use the Model Context Protocol call syntax: mcporter call 'exa.web_search_exa(query: "your search terms", numResults: 10)'. This command is documented in agent_reach/skill/references/search.md and routes through agent_reach/core.py to return structured search results that your skill can parse.

Where is the MCP configuration stored locally?

mcporter maintains its own JSON configuration file separate from Agent-Reach. When you run mcporter config add, it updates this local store. The repository includes a reference template at config/mcporter.json showing the expected schema, but the active configuration resides in mcporter's user-specific data directory, not in the Agent-Reach project folder.

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