Agent Web Search exposes one provider-neutral web_search tool. It dispatches the enabled providers concurrently, normalizes their responses into one schema, 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

Why Agent Web Search

• Concurrent, independent providers. All selected providers run at the same time, and one provider's failure never discards another provider's results.
• Zero-key start. The default providers — DDGS, Exa, and Parallel — work without any API key.
• One interface everywhere. MCP (stdio and HTTP), the CLI, the Python API, and the Hermes plugin share the same search engine, tool schema, and response model.
• Focused responses. Every provider response contains only a generated answer when available and normalized results.
• No telemetry, no shared secrets. Provider keys stay in server-side environment variables; there is no shared API-key service.

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

Requirements: Python 3.10+. No API key is needed; the default providers are free and keyless.

Install from PyPI with whichever package runner you already use:

# 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

The PyPI package agent-web-search-mcp installs two commands — agent-web-search (CLI) and agent-web-search-mcp (MCP server) — and imports as the Python module agent_web_search. uvx runs either command without a persistent installation.

Search right away:

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?"

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.

CLI

agent-web-search QUERY runs one search and prints a single JSON document to stdout.

# 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

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"
      }
    }
  }
}

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.

Response format

Each selected provider that succeeds appears under providers; failed providers are omitted:

{
  "query": "GPU kernel generation papers from the past month",
  "providers": {
    "ddgs": {
      "answer": "",
      "results": [
        {
          "title": "Example result",
          "url": "https://example.com/paper",
          "description": "Excerpt of the matching page",
          "provider": "ddgs",
          "published_at": "2026-08-02"
        }
      ]
    }
  }
}

If every selected provider fails, the MCP tool returns an error with the stable code all_providers_failed and per-provider diagnostics:

{
  "error": {
    "code": "all_providers_failed",
    "message": "All enabled search providers failed. Check provider configuration, credentials, quotas, and network access.",
    "provider_errors": {
      "ddgs": "RuntimeError: rate limited"
    }
  },
  "query": "GPU kernel generation papers from the past month"
}

Python API

The CLI, MCP servers, and Hermes plugin are thin wrappers around agent_web_search.SearchEngine, which is the public Python API. SearchRequest accepts the same fields as the MCP tool arguments:

from agent_web_search import SearchEngine, SearchRequest

engine = SearchEngine()  # reads AGENT_WEB_SEARCH_* variables at construction

response = engine.search(
    SearchRequest(query="latest MCP spec changes", max_results=5, time_range="m")
)

for name, provider in response.providers.items():
    print(f"{name}: searched={provider.searched}, results={len(provider.results)}")

if response.all_providers_failed:
    print(response.failed_provider_errors)

Configuration

Configuration is read from environment variables when the CLI, MCP server, or Hermes plugin starts. Restart the process after changing provider settings. See .env.example for a commented template of every variable.

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.

Troubleshooting

• all_providers_failed — every selected provider errored. The error carries per-provider diagnostics; check keys, quotas, and network access. Free backends can be rate-limited, so retrying or raising AGENT_WEB_SEARCH_TIMEOUT may help.
• HTTP 401 invalid_token — the Authorization: Bearer … header must match AGENT_WEB_SEARCH_AUTH_TOKEN, which must be at least 32 characters.
• A provider is missing from a response — failed providers are omitted from successful responses. The Python API exposes the reasons in response.failed_provider_errors.
• Provider changes have no effect — provider settings are read once at startup; restart the CLI, MCP server, or Hermes plugin after changing them.

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 .

ARCHITECTURE.md is the design source of truth, and AGENTS.md lists the non-negotiable invariants. Read both before changing transports, configuration, authentication, deployment, providers, or tool schemas, keep stdio and HTTP behavior identical, and keep pytest and ruff green in the same change.

License

MIT