Agent Web Search exposes one provider-neutral web_search tool. It dispatches independent providers concurrently, normalizes their responses, keeps partial failures isolated, and lets the calling agent choose which enabled providers to use for each request.

Agent / MCP client
        │
        ▼
    web_search
        │
        ▼
  SearchEngine ──┬── DDGS
                 ├── Exa
                 ├── Parallel
                 ├── ARK
                 ├── Brave
                 ├── Gemini
                 ├── Grok
                 ├── Perplexity
                 ├── Tavily
                 └── You.com

Providers

Free, keyless defaults: DDGS, Exa, and Parallel all work without an API key. Exa and Parallel automatically use their free MCP transports until a paid API key is provided.

The provider architecture is intentionally open: another search-capable backend can be added without changing the MCP, Hermes, CLI, or Python-facing interfaces.

Quick start

Install from PyPI using whichever Python package runner you already have:

# Standard Python installation
python -m pip install agent-web-search-mcp

# Isolated persistent installation
pipx install agent-web-search-mcp

# Run without a persistent installation
uvx agent-web-search-mcp

pip and pipx install both commands below. uvx runs the command named in its invocation directly.

Run a search without configuring a paid API key after a persistent install:

agent-web-search "What changed in the latest OpenAI Codex CLI?"

Or run the CLI through uvx without installing it:

uvx --from agent-web-search-mcp agent-web-search \
  "What changed in the latest OpenAI Codex CLI?"

Or start the stdio MCP server for an MCP client:

agent-web-search-mcp

To use uvx directly from an MCP client without installing the package first, configure the client to run uvx agent-web-search-mcp. For example:

{
  "mcpServers": {
    "agent-web-search": {
      "command": "uvx",
      "args": ["agent-web-search-mcp"]
    }
  }
}

pipx install 'git+https://github.com/JerryLiu369/agent-web-search.git'

[!IMPORTANT] Do not place API keys in shell history, source code, Git commits, screenshots, or checked-in MCP configuration. Export them from a secret manager or a local environment file that is not committed.

Remote MCP over HTTPS

The same agent-web-search-mcp command supports both MCP transports. It keeps stdio as the zero-argument default and enables stateless Streamable HTTP with a transport switch:

# Generate a deployment token once.
python -c "import secrets; print(secrets.token_urlsafe(32))"

export AGENT_WEB_SEARCH_AUTH_TOKEN="replace-with-the-generated-token"
agent-web-search-mcp --transport http

The HTTP server exposes POST /mcp and public GET /healthz. /mcp requires the deployment Bearer Token by default and never creates an MCP-Session-Id.

Remote MCP client example:

{
  "mcpServers": {
    "agent-web-search": {
      "url": "https://your-deployment.example/mcp",
      "headers": {
        "Authorization": "Bearer your-deployment-token"
      }
    }
  }
}

Deploy

Every public deployment must set AGENT_WEB_SEARCH_AUTH_TOKEN to at least 32 characters. Provider keys remain optional server-side environment variables.

Generic Docker deployment:

docker build -t agent-web-search .
docker run --rm -p 8000:8000 \
  -e AGENT_WEB_SEARCH_AUTH_TOKEN="replace-with-a-32-character-token" \
  agent-web-search

Tool interface

The MCP server and Hermes plugin register one tool named web_search.

Example call:

{
  "query": "GPU kernel generation papers from the past month",
  "max_results": 5,
  "time_range": "m",
  "providers": ["ddgs", "exa"]
}

Provider selection has two levels:

1. AGENT_WEB_SEARCH_PROVIDERS defines the provider set when the process starts.
2. The request-level providers argument may narrow that set, but cannot enable a provider that was disabled at startup.

Failed providers are omitted from successful responses. If every selected provider fails, MCP returns a tool error with the stable code all_providers_failed and includes per-provider diagnostics.

Configuration

Configuration is read from environment variables when the CLI, MCP server, or Hermes plugin starts. Restart the process after changing provider settings.

General settings

Example:

export AGENT_WEB_SEARCH_PROVIDERS="ddgs,exa,brave"
export AGENT_WEB_SEARCH_TIMEOUT="30"

$env:AGENT_WEB_SEARCH_PROVIDERS = "ddgs,exa,brave"
$env:AGENT_WEB_SEARCH_TIMEOUT = "30"

HTTP transport settings

HTTP settings remain environment-only; the deployment files do not introduce a second application configuration format.

Provider settings

Default providers are listed first; optional providers then follow alphabetical order.

1. DDGS

DDGS uses DuckDuckGo and requires no API key or provider-specific environment variables. The ddgs Python dependency is installed with the package.

2. Exa

Exa supports both paid and keyless modes.

Without EXA_API_KEY, Exa falls back to its free MCP endpoint on a best-effort basis. The paid API generally provides higher quota and reliability.

3. Parallel

Parallel returns information-dense excerpts ranked for LLM context. One parallel provider automatically selects its transport:

• Without a key, it uses Parallel's free Search MCP.
• With PARALLEL_API_KEY, it uses the paid Search REST API.

Both transports map excerpts into the common result description, so the calling agent does not need to distinguish parallel-free from parallel.

Parallel is enabled by default and its key is optional.

4. ARK (Recommended)

Volcengine ARK uses model-backed search grounding through the Responses API. Add ark to AGENT_WEB_SEARCH_PROVIDERS after providing the key.

One model stays fixed; multiple models are selected round-robin for successive requests. When multiple ARK keys are configured, a key is selected per request.

5. Brave

Add brave to AGENT_WEB_SEARCH_PROVIDERS after providing the key.

6. Gemini

Gemini maps common result and time controls into best-effort prompt constraints. One configured model stays fixed; multiple models are selected round-robin for successive requests.

7. Grok

One configured model stays fixed; multiple models are selected round-robin for successive requests.

When Grok is enabled, the public tool schema adds grok_search_mode:

• web_search searches the web.
• x_search searches X with native date filters when available.
• both exposes both server-side tools in one request and lets Grok choose; it does not issue two independent model requests.

8. Perplexity

This provider uses Perplexity's native structured Search API. It returns result rows rather than a Sonar-generated prose answer; OpenRouter compatibility is intentionally outside this provider's scope.

Add perplexity to AGENT_WEB_SEARCH_PROVIDERS after providing the key.

9. Tavily

Add tavily to AGENT_WEB_SEARCH_PROVIDERS after providing the key.

10. You.com

You.com returns unified web and news sections. Agent Web Search merges both, deduplicates URLs, and applies max_results to the combined result list.

Add you to AGENT_WEB_SEARCH_PROVIDERS after providing the key.

Common search controls

Each provider maps the shared controls to its native API when possible and ignores unsupported controls.

Prompt-based controls are best-effort and are not strict guarantees.

Integrations

Codex CLI

codex mcp add agent-web-search -- agent-web-search-mcp
codex mcp list

Claude Code

claude mcp add agent-web-search -- agent-web-search-mcp

Or add a project .mcp.json:

{
  "mcpServers": {
    "agent-web-search": {
      "command": "agent-web-search-mcp",
      "args": [],
      "env": {
        "AGENT_WEB_SEARCH_PROVIDERS": "ddgs,exa,parallel"
      }
    }
  }
}

OpenCode

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "agent-web-search": {
      "type": "local",
      "command": ["agent-web-search-mcp"],
      "environment": {
        "AGENT_WEB_SEARCH_PROVIDERS": "ddgs,exa,parallel"
      },
      "enabled": true
    }
  }
}

Hermes

Install the native plugin directly from GitHub:

pip install 'ddgs>=9.0'
hermes plugins install JerryLiu369/agent-web-search --no-enable
hermes plugins enable agent-web-search --allow-tool-override

The plugin intentionally replaces Hermes' built-in web_search tool, so the explicit --allow-tool-override grant is required. Start a new Hermes session after enabling it; restart the gateway when using a messaging channel.

Hermes can also connect through its generic MCP integration instead of the native plugin.

CLI examples

# Use every startup-enabled provider.
agent-web-search "What changed in the latest OpenAI Codex CLI?"

# Limit results and publication time.
agent-web-search "GPU kernel generation papers" --time-range m --max-results 5

# Select a provider subset for this request.
agent-web-search "latest AI news" --provider ark --provider ddgs

Design principles

• One core, multiple adapters. MCP, Hermes, CLI, and Python use the same search engine and response models.
• Independent providers. A failed provider does not discard successful providers; all-provider failure is surfaced explicitly.
• Transparent execution. Responses expose searched and model instead of treating every HTTP 200 as a completed search.
• No shared secrets. There is no telemetry or shared API-key service.

Development

Using uv keeps the development environment isolated and reproducible:

git clone https://github.com/JerryLiu369/agent-web-search.git
cd agent-web-search
uv venv
uv pip install -e '.[dev]'
uv run pytest -q
uv run ruff check .

python -m venv .venv
# Linux/macOS: source .venv/bin/activate
# Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install -e '.[dev]'
pytest -q
ruff check .

License

MIT