Agent Web Search

Agent Web Search（PyPI：agent-web-search-mcp）は、AI エージェント向けのオープンソース、MIT ライセンスのウェブ検索 MCP サーバー、CLI、および Python ライブラリです。エージェントが、プロバイダーに依存しない同一の検索コアを利用するための手段を3つ提供します。ネイティブ MCP ツール、ネイティブプラグイン（Hermes、DeepSeek Harness）、または標準の Agent Skill を通じて使い方を学習させた CLI です。

AI エージェントの方へ： pipx install agent-web-search-mcp でインストールしてください （または uvx --from agent-web-search-mcp agent-web-search "<question>" ですぐにお試しいただけます）。 次に skills/agent-web-search/SKILL.md をお読みください。 このファイルでは CLI を使う方法のみを説明しています（MCP の設定については、代わりにオプション1に従ってください）。 llms.txt は、機械可読なドキュメントのインデックスです。

これは、Google／Bing／Baidu のメタ検索ラッパーではありません。従来の検索集約では、キーワードクエリを従来型の検索エンジンに振り分け、その結果ページを統合します。一方、Agent Web Search はエージェント向けに構築された検索機能を集約します。モデルネイティブなウェブグラウンディング、エージェント向け検索 API、そして自然言語の質問を受け付け、エージェントがそのまま利用できる形式で回答、引用、または構造化された根拠を返す、コンテキスト対応の情報源です。現在のプロバイダー群で従来型検索バックエンドを採用しているのは DDGS のみです。

          Natural-language question
                      |
                      v
                 SearchEngine
          +-----------+-----------+
          |           |           |
          v           v           v
        DDGS        Model       Agent
                  grounding     APIs
                 (Responses,   (Exa,
                  ARK, Grok,    Parallel,
                  Gemini...)    Tavily...)

インストールとクイックスタート

3つのステップで、所要時間は約1分です。すぐに試し、一度インストールしてから、エージェントを接続します。 要件： Python 3.10 以降。デフォルトのプロバイダー（DDGS、Exa、Parallel）では API キーは不要です。

インストールせずに試す

uvx を使って検索機能をすぐに試せます（環境は変更されません）。

# Direct natural-language search with keyless defaults
uvx --from agent-web-search-mcp agent-web-search "What changed in the latest OpenAI Codex CLI?"

# Inspect MCP server arguments
uvx agent-web-search-mcp --help

インストール

グローバルなユーザー環境に一度だけインストールします（推奨）。

# Recommended isolated installation
pipx install agent-web-search-mcp

# Or install into the active Python environment
python -m pip install agent-web-search-mcp

確認

# 1. Verify the CLI and run a real search
agent-web-search --version
agent-web-search "What changed in the latest OpenAI Codex CLI?"

# 2. Verify the MCP server binary
agent-web-search-mcp --help

2つのコマンド、それぞれの役割：

• agent-web-search：ターミナル、シェルスクリプト、Agent Skills 向けの直接検索 CLI です。
• agent-web-search-mcp：MCP クライアント向けの Stdio および Streamable HTTP MCP サーバーです。

エージェント連携を選ぶ

ヒント

シェルを利用できるエージェントに CLI + Skill を推奨する理由： エージェントがすでにターミナル／bash の実行機能を備えている場合（Claude Code、Codex CLI、OpenCode、Hermes など）、CLI + Skill の方式が最も手軽で、信頼性も最も高くなります。デバッグが必要な MCP の JSON 設定も、管理が必要なバックグラウンドのトランスポートライフサイクルもなく、標準的な Skill を通じて学習された、クリーンな stdout の JSON 出力が得られます。

Agent Web Search を選ぶ理由

従来の検索集約（Google／Bing／Baidu のラッパーや、スクレイピングした SERP）は、キーワードクエリを従来型の検索エンジンに送り、結果ページを統合します。一方、Agent Web Search はエージェント向けに構築された検索機能を集約します。1回のツール呼び出しで、引用にすぐ使える構造化された根拠を返します。また、モデルネイティブのグラウンディングプロバイダーを通じて、明示的な引用を含む統合回答を返すこともできます。実測ベンチマークでは、その実用上の違いが示されています。公式情報源を尋ねる自然言語の中国語クエリに対し、従来型の SERP バックエンドは上位5件に政府ドメインの結果を返さなかった一方、グラウンディングプロバイダーは、有効な引用を添えて中国税関総署の公式数値を返しました。

• エージェントネイティブな設計です。 主なインターフェースは、Google、Bing、Baidu への単純なキーワード振り分けではなく、自然言語による完全な質問です。
• モデルネイティブの検索バックエンド。 ARK、Gemini、Grok、DeepSeek、Responses、Messages、Zhipu Chat Search、Codex Alpha は、ウェブ検索とモデル生成による統合、明示的な引用を組み合わせられます。
• エージェント向け検索プロバイダー。 Exa、Parallel、Brave、Perplexity、Tavily、You.com、Zhipu Web Search は、後続のエージェントに構造化された、引用しやすい、またはコンテキストにすぐ使える根拠を提供するための検索 API を公開しています。
• プロバイダーに依存しない単一の仕様。 すべてのバックエンドは、同じ MCP ツール、CLI、Python API、正規化された results を通じて利用できます。モデルベースのプロバイダーは answer も返す場合があります。
• 独立したプロバイダー。 選択したプロバイダーは並行して実行され、あるプロバイダーが失敗しても、別のプロバイダーが正常に返した結果が破棄されることはありません。
• DDGS はシンプルなフォールバックとして利用できます。 DDGS は唯一の従来型検索バックエンドです。API キーは不要で、有料プロバイダーの認証情報がなくてもプロジェクトを利用できます。Exa と Parallel も、デフォルトではキー不要です。
• テレメトリーなし、共有シークレットなし。 プロバイダーキーは実行時の環境変数に保持され、共有 API キーサービスはありません。

プロバイダー

プロバイダーの一覧は、検索機能の種類ごとに意図的に分けています。従来型の検索バックエンドは DDGS のみで、ほかの 2 つのグループは、モデルネイティブのグラウンディング、またはエージェント向け検索サービスを中心に構成されています。

無料でキー不要のデフォルト設定： DDGS、Exa、Parallel は、いずれも API キーなしで動作します。Exa と Parallel は、有料 API キーが設定されるまで、無料の MCP トランスポートを自動的に使用します。

従来型の検索バックエンド

モデルプロバイダー

これらのプロバイダーは、モデルネイティブの検索機能またはグラウンディング機能を使用します。応答には、モデルが生成した回答とともに、引用やその他の明示的な検索根拠が含まれる場合があります。

エージェント向け検索プロバイダー

これらのプロバイダーは、従来型の検索ページではなく、自然言語のクエリ、構造化されたソース行、有用性の高い抜粋、引用しやすいメタデータなど、エージェントが利用するための検索サービスを提供します。

プロバイダーのアーキテクチャは意図的に拡張可能な設計になっており、MCP、Hermes、CLI、Python 向けのインターフェースを変更せずに、別の検索対応バックエンドを追加できます。

エージェントでの使用

前提条件： 先にインストールとクイックスタートを完了してください。以下のセクションでは、各連携方法について、クライアントの詳細な設定とコマンドのリファレンスを説明します。

オプション 1：MCP

エージェントがツールサーバーに対応していて、型付きの検出、プロトコルレベルのエラー、またはリモートアクセスが必要な場合は、MCP を選択してください。同じ agent-web-search-mcp コマンドで、ローカルの stdio とステートレスな Streamable HTTP の両方を利用できます。

ローカル stdio MCP

パッケージを一度インストールします。

# Recommended isolated installation
pipx install agent-web-search-mcp

# Or install into the active Python environment
python -m pip install agent-web-search-mcp

次に、MCP クライアントが agent-web-search-mcp を起動するように設定します。

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

uvx がすでに利用可能な場合、クライアントはコマンド uvx と引数 ["agent-web-search-mcp"] を使って、永続的にインストールせずにパッケージを実行できます。

# Codex CLI
codex mcp add agent-web-search -- agent-web-search-mcp

# Claude Code
claude mcp add agent-web-search -- agent-web-search-mcp

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

HTTPS 経由のリモート MCP

この README の先頭にあるデプロイボタンのいずれかを使うか、同じサーバーを自分で実行します。

python -c "import secrets; print(secrets.token_urlsafe(32))"
export AGENT_WEB_SEARCH_AUTH_TOKEN="<your-generated-token>"
agent-web-search-mcp --transport http

サーバーは、認証が必要な POST /mcp と、公開されている GET /healthz を公開します。リモート MCP クライアントは次のように接続します。

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

すべての公開デプロイでは、AGENT_WEB_SEARCH_AUTH_TOKEN を 32 文字以上に設定する必要があります。サーバーはステートレスで、MCP-Session-Id の値を生成しません。

オプション 2：CLI + Agent Skill

エージェントがすでにシェルアクセスを利用でき、Agent Skills に対応している場合は、この構成を選択してください。Skill は、CLI の呼び出し方法、コントロールの選択方法、results の解釈方法、構造化されたエラーへの対処方法をエージェントに教えます。MCP の設定は不要です。

1. CLI をインストールします。

   pipx install agent-web-search-mcp
   # Or: python -m pip install agent-web-search-mcp
   

2. 同梱の agent-web-search Skill をインストールします。

   npx skills add JerryLiu369/agent-web-search --skill agent-web-search
   

   エージェントが skills インストーラーを使用しない場合は、 skills/agent-web-search をそのクライアントの Skills ディレクトリにコピーしてください。

3. CLI を確認してから、エージェントに検索させます。

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

CLI は、成功時に 1 つの JSON ドキュメントを stdout に書き込みます。すべてのプロバイダーが失敗した場合は、共通の all_providers_failed JSON を stderr に書き込み、終了ステータス 1 で終了します。そのため、シェルを利用できるエージェントは、実際のエラーと結果が空である状態を区別できます。

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

重要

API キーをシェルの履歴、ソースコード、Git のコミット、スクリーンショット、またはチェックインする MCP 設定に含めないでください。サーバー側またはローカルの環境変数を通じて指定してください。

共通のリクエストとレスポンス

MCP は web_search という名前のツールを 1 つ公開します。CLI も同じ入力に対応します。

呼び出し例：

{
  "query": "What GPU kernel generation papers were published in the past month?",
  "max_results": 5,
  "time_range": "m",
  "providers": ["ddgs", "exa"]
}

プロバイダーの選択には 2 つのレベルがあります。

1. AGENT_WEB_SEARCH_PROVIDERS は、プロセスの起動時にプロバイダーのセットを定義します。
2. リクエストレベルの providers 引数でそのセットを絞り込むことはできますが、起動時に無効化されたプロバイダーを有効にすることはできません。

レスポンス形式

成功した各プロバイダーは providers の下に表示されます。失敗した プロバイダーは省略されます。

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

選択したすべてのプロバイダーが失敗した場合、MCP はツールエラーを返します。CLI は同じペイロードを stderr に書き込み、ステータス 1 で終了します。どちらの場合も、安定したコード all_providers_failed が使われ、プロバイダーごとの診断情報が含まれます。

{
  "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": "What GPU kernel generation papers were published in the past month?"
}

Python API

CLI、MCP サーバー、Hermes プラグインは、公開 Python API である agent_web_search.SearchEngine を薄くラップしています。 SearchRequest は、MCP ツールの引数と同じフィールドを受け付けます。

from agent_web_search import SearchEngine, SearchRequest

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

response = engine.search(
    SearchRequest(
        query="What are the latest changes to the MCP specification?",
        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)

設定

設定は、CLI、MCP サーバー、Hermes プラグインの起動時に環境変数から読み込まれます。プロバイダーの設定を変更した後は、プロセスを再起動してください。すべての変数についてコメント付きのテンプレートは .env.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 トランスポート設定

HTTP 設定は引き続き環境変数のみで行います。デプロイ用ファイルによって、別のアプリケーション設定形式が導入されることはありません。

プロバイダー設定

以下のプロバイダー固有設定には、すべてのプロバイダーの認証情報とモデル制御が含まれます。サポート対象プロバイダーの概要は機能別に分類されていますが、このセクションでは詳細な設定を説明します。

1. DDGS

DDGS は DuckDuckGo を使用し、API キーやプロバイダー固有の環境変数を必要としません。ddgs Python 依存関係はパッケージとともにインストールされます。

2. Exa

Exa は有料モードとキー不要モードの両方に対応しています。

EXA_API_KEY が設定されていない場合、Exa はベストエフォートで無料の MCP エンドポイントにフォールバックします。有料 API は通常、より高い利用枠と信頼性を提供します。

3. Parallel

Parallel は、LLM のコンテキスト向けにランキングされた情報密度の高い抜粋を返します。parallel プロバイダーは、トランスポートを自動的に選択します。

• キーがない場合は、Parallel の無料 Search MCP を使用します。
• PARALLEL_API_KEY がある場合は、有料の Search REST API を使用します。

どちらのトランスポートも excerpts を共通の結果説明にマッピングするため、呼び出すエージェントが parallel-free と parallel を区別する必要はありません。

Parallel はデフォルトで有効になっており、キーは任意です。

4. ARK（推奨）

Volcengine ARK は Responses API を通じて、モデルを利用した検索グラウンディングを行います。キーを設定した後、AGENT_WEB_SEARCH_PROVIDERS に ark を追加してください。

モデルが 1 つの場合は固定され、複数の場合は後続のリクエストでラウンドロビン方式により選択されます。複数の ARK キーが設定されている場合は、リクエストごとにキーが選択されます。

5. Brave

キーを設定した後、AGENT_WEB_SEARCH_PROVIDERS に brave を追加してください。

6. Gemini

Gemini は、共通の結果および時間制御を、ベストエフォートのプロンプト制約にマッピングします。設定されたモデルが 1 つの場合は固定され、複数の場合は後続のリクエストでラウンドロビン方式により選択されます。

7. Grok

設定されたモデルが 1 つの場合は固定され、複数の場合は後続のリクエストでラウンドロビン方式により選択されます。

Grok が有効な場合、公開ツールのスキーマに grok_search_mode が追加されます。

• web_search はウェブを検索します。
• x_search は、利用可能な場合、ネイティブの日付フィルターを使用して X を検索します。
• both はサーバー側の両方のツールを 1 つのリクエストで提示し、Grok に選択させます。独立したモデルリクエストを 2 回実行するわけではありません。

8. Codex Alpha（実験的）

codex_alpha プロバイダーは、ゲートウェイ API キーと /v1/alpha/search を実装する完全なエンドポイントのみを使用します（プロバイダーはパスを追加しません）。Codex OAuth トークンには対応していません。エンドポイント、キー、任意のモデルを設定してから、AGENT_WEB_SEARCH_PROVIDERS に codex_alpha を追加してください。

このプロバイダーは通常の search_query コマンドを送信し、標準的なウェブ検索結果を返します。

9. DeepSeek

DeepSeek は、Anthropic 互換の公式 Messages API とネイティブの web_search_20250305 サーバーツールを使用します。モデルが生成した最終テキストを保持し、 明示的な web_search_result ブロックのみを正規化された結果にマッピングします。そのため、 有効なレスポンスでも answer があり、results リストが空の場合があります。

キーを設定した後、AGENT_WEB_SEARCH_PROVIDERS に deepseek を追加します。 プロバイダーは、設定されたベース URL に /v1/messages を追加します。複数のモデルを設定すると、 リクエストごとにラウンドロビン方式で選択されます。

10. Perplexity

このプロバイダーは、Perplexity のネイティブな構造化 Search API を使用します。Sonar が生成した文章の回答ではなく、 検索結果の行を返します。OpenRouter との互換性は、意図的にこのプロバイダーの対象外としています。

キーを設定した後、AGENT_WEB_SEARCH_PROVIDERS に perplexity を追加します。

11. Tavily

キーを設定した後、AGENT_WEB_SEARCH_PROVIDERS に tavily を追加します。

12. You.com

You.com は、ウェブとニュースの統合セクションを返します。Agent Web Search は両方を統合し、 URL を重複排除して、統合された結果リストに max_results を適用します。

キーを設定した後、AGENT_WEB_SEARCH_PROVIDERS に you を追加します。

13. Zhipu Web Search

Zhipu Web Search は、中国向けの単独 Web Search API を使用し、 構造化された検索結果の行を返します。Zhipu Chat Search とは別のプロバイダーであり、 実装ではこの 2 つのインターフェース間でフォールバックしません。

キーを設定した後、AGENT_WEB_SEARCH_PROVIDERS に zhipu_web_search を追加します。 プロバイダーは、設定されたベース URL に /api/paas/v4/web_search を追加します。

14. Zhipu Chat Search

Zhipu Chat Search は、ネイティブのウェブ検索機能を備えた中国向け GLM Chat Completions API を使用します。 モデルの回答と、トップレベルに明示された検索結果の行のみを返します。 回答の文章中に記載された URL は、引用として扱われません。Zhipu Web Search とは別のプロバイダーであり、 API と Chat 間のフォールバックはありません。

キーを設定した後、AGENT_WEB_SEARCH_PROVIDERS に zhipu_chat_search を追加します。 プロバイダーは、設定されたベース URL に /api/paas/v4/chat/completions を追加します。 複数のモデルを設定すると、リクエストごとにラウンドロビン方式で選択されます。

15. Responses

Responses は、サーバー側のウェブ検索ツールを POST {base_url}/responses で公開するゲートウェイ向けの汎用 OpenAI Responses API クライアントです。output 配列を走査し（output[0] に結果が含まれるとは限りません）、web_search_call のアクションソースと url_citation アノテーションを正規化された結果にマッピングし、モデルが生成した回答を保持します。メッセージのみで URL がないレスポンスでは回答を保持し、results を空にして、searched を false にします。

キーを設定した後、AGENT_WEB_SEARCH_PROVIDERS に responses を追加します。 複数のモデルを設定した場合、リクエストごとに順番に選択されます。

16. Messages

Messages は、サーバー側のウェブ検索ツールを POST {base_url}/v1/messages で公開するゲートウェイ向けの汎用 Anthropic Messages API クライアントです。content 配列を走査し（単一のブロックに結果が含まれるとは限りません）、web_search_tool_result／web_search_result ブロックを正規化された結果にマッピングし、引用情報または結果のドメインから不足しているタイトルを補完し、モデルが生成した回答を保持します。テキストのみで URL がないレスポンスでは回答を保持し、results を空にして、searched を false にします。

キーを設定した後、AGENT_WEB_SEARCH_PROVIDERS に messages を追加します。 複数のモデルを設定した場合、リクエストごとに順番に選択されます。

共通の検索コントロール

各プロバイダーは、可能な場合は共通のコントロールをネイティブ API にマッピングし、サポートされていないコントロールは無視します。

プロンプトベースのコントロールは可能な範囲で適用されるものであり、厳密な保証ではありません。

その他のインターフェース

ネイティブの Hermes プラグイン

GitHub からネイティブプラグインを直接インストールします。

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

このプラグインは Hermes の組み込み web_search ツールを意図的に置き換えるため、明示的な --allow-tool-override の許可が必要です。有効にした後、新しい Hermes セッションを開始してください。メッセージングチャネルを使用する場合は、ゲートウェイを再起動してください。

ネイティブプラグインの代わりに、Hermes の汎用 MCP 統合を介して接続することもできます。

ネイティブの DeepSeek Harness プラグイン

GitHub からネイティブプラグインを直接インストールします（デスクトップと CLI の両方のプロファイルに対応しています。デスクトップアプリには独自の dsh plugin コマンドが含まれているため、ファイルを手動で配置する必要はありません）。

dsh plugin --profile <profile> add github:JerryLiu369/agent-web-search
python -m pip install agent-web-search-mcp

このプラグインは、DSH のネイティブな web_search 接続部分の実装を意図的に置き換えます。モデルに公開されるツール名、プロンプト、正規化されたソース、引用 UI は同じです。mcp__...__web_search ツールは公開しません。agent-web-search-mcp Python コマンドを DSH と同じ環境にインストールし、新しいプロバイダーがすぐに認識されない場合は DSH を再起動してください。ブリッジは組み込みプロバイダーの処理をそのコマンドに委譲し、DSH はネイティブの設定、履歴、診断機能を引き続き保持します。詳しい手順とコピーして貼り付けられるインストール用プロンプトは、 integrations/dsh/docs/INSTALL.md にあります。

ネイティブプラグインの代わりに、DSH の組み込み MCP クライアントを介して接続することもできます。

トラブルシューティング

• all_providers_failed — 選択したプロバイダーがすべてエラーになりました。MCP は呼び出しをエラーとして扱い、CLI は診断情報を stderr に書き込んで終了コード 1 で終了します。キー、クォータ、ネットワークアクセスを確認してください。一時的な制限であれば、1 回再試行すると解決する場合があります。
• agent-web-search が見つからない — PyPI パッケージを pipx または pip でインストールしてから、新しいシェルを起動し、スクリプトのディレクトリが PATH に含まれるようにしてください。
• HTTP 401 invalid_token — Authorization: Bearer … ヘッダーは AGENT_WEB_SEARCH_AUTH_TOKEN と一致している必要があり、値は 32 文字以上でなければなりません。
• レスポンスにプロバイダーが含まれていない — 成功したレスポンスでは、失敗したプロバイダーは省略されます。Python API では、理由を response.failed_provider_errors で確認できます。
• プロバイダーを変更しても反映されない — プロバイダー設定は起動時に一度だけ読み込まれます。変更後は CLI、MCP サーバー、または Hermes プラグインを再起動してください。
• ツールが戻る前に MCP クライアントがタイムアウトする — AGENT_WEB_SEARCH_TIMEOUT は、検索全体ではなく、個々の上流 HTTP 呼び出しのタイムアウトを設定します。キー不要の Parallel では最大 3 回の呼び出しが行われ、ARK では継続リクエストが追加される場合があるため、最悪の場合は 3 × AGENT_WEB_SEARCH_TIMEOUT となります。MCP クライアントのツールタイムアウトを適切に設定してください。

FAQ

Agent Web Search とは何ですか？

Agent Web Search は、AI エージェント向けのオープンソースのウェブ検索レイヤーです。MCP サーバー（stdio または Streamable HTTP）、CLI、Python API を通じて、1 つの web_search ツールを提供します。このツールの背後では、モデルネイティブな検索グラウンディングプロバイダー（ARK、Gemini、Grok、DeepSeek、Zhipu Chat Search、Codex Alpha、汎用の Responses/Messages ゲートウェイ）、エージェント検索 API（Exa、Parallel、Brave、Perplexity、Tavily、You.com、Zhipu Web Search）、そして従来型のフォールバックとして DuckDuckGo を実行し、正規化された JSON レスポンスを 1 つ返します。

API キー不要で使える、無料のウェブ検索 MCP サーバーはありますか？

はい。デフォルトのプロバイダーセットである DDGS、Exa、Parallel は、API キーなしで動作します。Exa と Parallel は、EXA_API_KEY または PARALLEL_API_KEY が設定されるまでは、ベストエフォートで無料の MCP エンドポイントを使用します。有料プロバイダーは、AGENT_WEB_SEARCH_PROVIDERS を通じてオプトインできます。

Google／Bing のメタ検索 MCP とは何が違いますか？

メタ検索サーバーは、従来型の検索結果ページをスクレイピングして統合します。Agent Web Search は、引用付きの合成された answer を返すモデルネイティブなグラウンディングを含め、エージェント向けに構築された検索サービスを集約します。open-webSearch との直接比較ベンチマークでは、注意点も含めて違いを説明しています。データセンターの IP からの SERP スクレイピングは頻繁にボット対策でブロックされましたが、API を利用するプロバイダーは、結果がゼロになるのではなく、返す行数が減少しました。

どのエージェントやクライアントで使えますか？

Codex CLI、Claude Code、OpenCode、Cursor、Cline、Claude Desktop など、stdio または Streamable HTTP に対応する MCP クライアントであれば、どれでも使えます。Hermes にはネイティブプラグインがあります。シェルを利用できるエージェントは、MCP の代わりに、同梱の Agent Skill と CLI を使用できます。

MCP サーバーと CLI + Skill のどちらを使うべきですか？

クライアントがツールサーバーに対応しており、型付きのツール検出、プロトコルレベルのエラー、またはリモートでのデプロイが必要な場合は MCP を使用してください。エージェントがすでにシェルを備えていて、Agent Skills に対応している場合は CLI + Skill を使用してください。MCP の設定は不要です。どちらも同じ形式のレスポンスを返します。

検索グラウンディングに、独自の OpenAI または Anthropic 互換ゲートウェイを使えますか？

はい。responses プロバイダーは、サーバー側のウェブ検索ツールを備えた任意の OpenAI Responses API ゲートウェイを呼び出します。messages プロバイダーも、Anthropic Messages API ゲートウェイに対して同様に動作します。プロバイダー設定に記載されている変数で、ベース URL、キー、モデルを設定してください。

リモート MCP サーバーとしてホストできますか？

はい。agent-web-search-mcp --transport http は、Bearer トークン認証を使用して POST /mcp でステートレスな Streamable HTTP を提供します。Vercel、Railway、Render、Zeabur 用のワンクリックテンプレートが用意されており、リポジトリには Dockerfile も含まれています。

テレメトリーを収集したり、API キーを保存したりしますか？

いいえ。テレメトリーはなく、共有キーサービスもありません。プロバイダーの認証情報は、検索を実行するマシンまたはサーバー上の環境変数から読み取られ、ツール引数として渡されることはありません。

開発

uv を使用すると、開発環境を分離し、再現可能な状態に保てます。

git clone https://github.com/JerryLiu369/agent-web-search.git
cd agent-web-search
uv venv
uv pip install -e '.[dev]'
uv run --extra dev 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 は設計上の正本であり、AGENTS.md には、必ず守るべき不変条件が記載されています。トランスポート、設定、認証、デプロイ、プロバイダー、ツールスキーマを変更する前に、両方を読んでください。また、stdio と HTTP の動作を同一に保ち、同じ変更内で pytest と ruff が正常に実行できる状態を維持してください。

ライセンス

MIT