CatchAll

Newscatcher CatchAll MCP サーバー

NewsCatcher CatchAll Web Search API 用の MCP サーバーです。

クイックスタート — ホスト型サーバーを利用する

MCP を利用するために、このリポジトリをクローンしたり実行したりする必要はありません。NewsCatcher がホスト型インスタンスを運用しています。

https://catchall-mcp.newscatcherapi.com/mcp?apiKey=YOUR_CATCHALL_API_KEY

platform.newscatcherapi.com で CatchAll API キーを取得し、接続します。

{
  "mcpServers": {
    "catchall": {
      "type": "http",
      "url": "https://catchall-mcp.newscatcherapi.com/mcp?apiKey=YOUR_CATCHALL_API_KEY"
    }
  }
}

または、Claude Code CLI を使います。

claude mcp add --transport http catchall "https://catchall-mcp.newscatcherapi.com/mcp?apiKey=YOUR_CATCHALL_API_KEY"

詳しい統合ドキュメント：https://www.newscatcherapi.com/docs/web-search-api/integrations/mcp

サーバーを自分で実行する（ローカルまたはセルフホスト可能な環境で運用する）場合は、以下の実行方法を参照してください。

ツールとエンドポイントの対応

ジョブ

MCP ツール	メソッド	エンドポイント
initialize_query	POST	/catchAll/initialize
submit_query	POST	/catchAll/submit
validate_query	POST	/catchAll/validate
continue_job	POST	/catchAll/continue
list_user_jobs	GET	/catchAll/jobs/user
get_job_status	GET	/catchAll/status/{job_id}
pull_results	GET	/catchAll/pull/{job_id}
pull_job_csv	GET	/catchAll/pull/{job_id}/csv
delete_job	DELETE	/catchAll/jobs/{job_id}

ジョブ一覧のフィルター： list_user_jobs は、page／page_size に加えて、search、ownership、project_id、mode（base または lite）のフィルターに対応しています。

モニター

MCP ツール	メソッド	エンドポイント
create_monitor	POST	/catchAll/monitors/create
update_monitor	PATCH	/catchAll/monitors/{monitor_id}
delete_monitor	DELETE	/catchAll/monitors/{monitor_id}
list_monitors	GET	/catchAll/monitors/
list_monitor_jobs	GET	/catchAll/monitors/{monitor_id}/jobs
get_monitor_status	GET	/catchAll/monitors/{monitor_id}/status
pull_monitor_results	GET	/catchAll/monitors/pull/{monitor_id}
pull_monitor_csv	GET	/catchAll/monitors/pull/{monitor_id}/csv
enable_monitor	POST	/catchAll/monitors/{monitor_id}/enable
disable_monitor	POST	/catchAll/monitors/{monitor_id}/disable

Webhook

MCP ツール	メソッド	エンドポイント
list_webhooks	GET	/catchAll/webhooks
create_webhook	POST	/catchAll/webhooks
get_webhook	GET	/catchAll/webhooks/{webhook_id}
update_webhook	PATCH	/catchAll/webhooks/{webhook_id}
delete_webhook	DELETE	/catchAll/webhooks/{webhook_id}
test_webhook	POST	/catchAll/webhooks/{webhook_id}/test
assign_webhook_resource	POST	/catchAll/webhooks/{webhook_id}/resources
list_webhook_resources	GET	/catchAll/webhooks/{webhook_id}/resources
remove_webhook_resource	DELETE	/catchAll/webhooks/{webhook_id}/resources/{resource_type}/{resource_id}
list_resource_webhooks	GET	/catchAll/resources/{resource_type}/{resource_id}/webhooks
get_webhook_history	GET	/catchAll/webhook-history
trigger_webhook	POST	/catchAll/webhook/trigger/{resource_type}/{resource_id}

Webhook に関する注意： create_webhook では、作成時に Webhook をプロジェクトに関連付けるための project_id を任意で指定できます。list_webhooks でも、特定のプロジェクトに属する Webhook に絞り込むために project_id を任意で指定できます。get_webhook_history には、2 つのモードがあります。ジョブ／モニター／monitor_group の配信履歴を取得するには resource_type と resource_id を指定し、1 つの Webhook を介したすべての配信を取得するには webhook_id を指定します（1 回の呼び出しにつき、いずれか一方のモードのみ指定できます）。手動のテスト配信（test_webhook）は Webhook モードでのみ表示され、resource_type: "test" として記録されます。

プロジェクト

MCP ツール	メソッド	エンドポイント
create_project	POST	/catchAll/projects/
list_projects	GET	/catchAll/projects/
get_project	GET	/catchAll/projects/{project_id}
update_project	PATCH	/catchAll/projects/{project_id}
delete_project	DELETE	/catchAll/projects/{project_id}
get_project_overview	GET	/catchAll/projects/{project_id}/overview
add_project_resources	POST	/catchAll/projects/{project_id}/resources
list_project_resources	GET	/catchAll/projects/{project_id}/resources
remove_project_resource	DELETE	/catchAll/projects/{project_id}/resources/{resource_type}/{resource_id}

プロジェクトのリソース： resource_type は job、monitor、dataset、 monitor_group、webhook のいずれかです。Webhook は複数のプロジェクトに同時に所属できます。 delete_resources=true を指定して delete_project を実行すると、含まれるジョブ、モニター、 データセット、モニターグループが削除されますが、Webhook は関連付けが解除されるだけで、削除はされません。 レスポンスの deleted_resources では、Webhook は webhook_unlinked の数として報告されます。

データセット

MCP ツール	メソッド	エンドポイント
create_dataset	POST	/catchAll/datasets/
list_datasets	GET	/catchAll/datasets/
get_dataset	GET	/catchAll/datasets/{dataset_id}
update_dataset	PATCH	/catchAll/datasets/{dataset_id}
delete_dataset	DELETE	/catchAll/datasets/{dataset_id}
add_dataset_entities	POST	/catchAll/datasets/{dataset_id}/entities
remove_dataset_entities	DELETE	/catchAll/datasets/{dataset_id}/entities
list_dataset_entities	POST	/catchAll/datasets/{dataset_id}/entities/list
get_dataset_status	GET	/catchAll/datasets/{dataset_id}/status
create_dataset_from_csv	POST	/catchAll/datasets/upload
append_csv_to_dataset	POST	/catchAll/datasets/{dataset_id}/upload

CSV アップロード（v1.6.1）： create_dataset_from_csv と append_csv_to_dataset は、 file パラメーターで CSV の内容を受け取ります。生の CSV テキストまたは標準の base64 を指定します。 サーバーのファイルシステムからパスを読み取ることはないため、リモート／ホスト型の MCP でも安全です。インラインの CSV 内容は、base64 デコード後に最大 10 MB に制限されます。 create_dataset_from_csv では、新しい省略可能な project_id フィールドも使用できます。

エンティティ

MCP ツール	メソッド	エンドポイント
create_entity	POST	/catchAll/entities/
list_entities	GET	/catchAll/entities/
create_entities_batch	POST	/catchAll/entities/batch
get_entity	GET	/catchAll/entities/{entity_id}
update_entity	PATCH	/catchAll/entities/{entity_id}
delete_entity	DELETE	/catchAll/entities/{entity_id}

external_entity_id（v1.6.3）： create_entity と update_entity は、省略可能な external_entity_id 文字列を受け付けます。これは、エンティティを外部システムのレコードに紐付ける、 顧客指定の識別子です。project_id（v1.8.0）： list_entities は省略可能な project_id を受け付け、特定のプロジェクトに属するエンティティに絞り込めます。

ソースグループ

MCP ツール	メソッド	エンドポイント
list_source_groups	GET	/catchAll/source-groups

ソースグループ（v1.8.0）： 名前付きで再利用可能なドメイン許可リストです（公開グループ、および組織がアクセスできる組織公開グループ）。list_source_groups は、各グループの slug、name、description を返します。直接 API の POST /catchAll/submit では、ドメイン許可リストを指定して取得対象を絞り込むための slug の source_groups フィールドが 使用できるようになりました。submit_query はまだこのパラメーターを公開していません。この機能が 将来のリリースで追加されるまでは、直接 API を使用してください。

ユーザーとメタ情報

MCP ツール	メソッド	エンドポイント
get_user_limits	POST	/catchAll/user/limits
check_health	GET	/health
get_version	GET	/version

認証

API キーの優先順位（高い順）：

1. api_key ツールパラメーター
2. x-api-key リクエストヘッダー
3. Authorization: Bearer <key> リクエストヘッダー
4. URL クエリパラメーター ?apiKey=...
5. CATCHALL_API_KEY 環境変数

check_health と get_version では API キー認証は不要です。

ホスト型デプロイ（FastMCP Gateway）

fastmcp.app 経由でデプロイすると、ステートレスゲートウェイがサーバーの前段に配置されます。ゲートウェイは HTTP ヘッダーをバックエンドに転送しますが、URL クエリパラメーターは転送しません。?apiKey= の代わりに x-api-key ヘッダーまたは CATCHALL_API_KEY 環境変数を使用してください。

Claude Code / Cursor：

{
  "mcpServers": {
    "catchall": {
      "type": "http",
      "url": "https://YOUR-DEPLOYMENT.fastmcp.app/mcp",
      "headers": { "x-api-key": "YOUR_API_KEY" }
    }
  }
}

または CLI 経由：

claude mcp add --transport http catchall "https://YOUR-DEPLOYMENT.fastmcp.app/mcp" \
  --header "x-api-key: YOUR_API_KEY"

サーバーへの直接アクセス（ゲートウェイなし）：URL 内の ?apiKey=YOUR_KEY は引き続き使用できます。

コアワークフロー（ジョブ）

1. 任意：initialize_query を呼び出して、バリデーター／エンリッチメント／日付範囲をプレビューします。
2. initialize_query はプレビュー専用（ジョブは作成されません）であり、提案内容は非決定的です。
3. submit_query で送信します（query は必須）。query のみを送信できます。省略された任意フィールドは自動的に選択／生成されます。
4. 任意フィールドはそれぞれ独立しています。任意の組み合わせで指定できます（例：カスタム validators のみ）。省略したフィールドは引き続き自動生成されます。
5. start_date／end_date は、抽出したコンテンツ内のイベント日付ではなく、ウェブページの発見日を絞り込みます。
6. イベント日時の精度を高めるには、イベントに特化したバリデーター／エンリッチメントを使用し、取得結果の event_date を確認してください。
7. get_job_status をポーリングします。最初は約1～2分後に確認し、その後は30～60秒ごとに確認して、completed または failed になったら停止します。
8. pull_results で取得します。enriching 中も部分データが表示されます。
9. すべての利用可能なレコードを取得するには、page < total_pages の間ページネーションを続けます。
10. 追加のレコードを処理する場合にのみ continue_job を使用します（コストに影響します）。これは、もともと limit を指定して送信されたジョブにのみ適用されます。
11. continue_job.new_limit は任意です。省略すると、API はプランの上限をデフォルトとして使用します。
12. page/page_size/total_pages はすでに利用可能なレコードを表します。さらに表示されるレコードがある可能性を検出するには、progress_validated < candidate_records を使用します。

limit と page_size

• limit（submit_query、continue_job）は処理するレコード数を制御し、コストに影響します。指定する場合は 10 以上である必要があります。プランの上限までのすべてのデータを取得するには省略してください。
• page_size（pull_results、list_user_jobs）はページネーションのみを制御し、処理コストには影響しません。
• pull_results.page_size のデフォルトは 100 です。
• page_size の範囲は 1..1000 です。
• pull_results のレスポンスには error（失敗したジョブ）と limit（適用されたジョブ上限）が含まれます。

API によって適用されるモニターの制約

• create_monitor.backfill=true：参照ジョブの end_date は直近7日以内である必要があります。
• create_monitor.backfill=false：参照ジョブの経過時間の制約は適用されません。
• モニターの最小スケジュール頻度はプランによって異なります。
• create_monitor は、任意の limit（最小 10）、backfill（デフォルト true）、timezone、webhook_ids、project_id をサポートします。
• Webhook は v1.5.3 で一元管理されます。create_webhook で登録し、create_monitor.webhook_ids／update_monitor.webhook_ids で ID を指定して紐付けてください（Webhook 設定をインラインで指定する方法はありません）。
• モニターは base ジョブのみをサポートします（lite は対象外です）。
• enable_monitor は任意の backfill をサポートします。
• update_monitor は webhook_ids、実行時の limit、schedule、timezone を更新します（割り当てを解除するには webhook_ids=[] を渡します。schedule も設定されていない場合、timezone は無視されます）。
• list_monitors は page と page_size によるページネーションに加えて、search、ownership、project_id の各フィルターをサポートします。total、page、page_size、total_pages、monitors を返します。

エンリッチメント出力に関する注意事項

• enrichment.enrichment_confidence は常に含まれます。
• 企業のエンリッチメントは、次の項目を持つ構造化オブジェクトです。
  • source_text
  • confidence
  • metadata.name
  • metadata.domain_url
  • metadata.domain_url_confidence

エラー処理

ツールは次の内容を返します。

• 成功時は整形済みの JSON 文字列。
• (v1.8.0) 上流からの 2xx 以外のレスポンス（不正な api_key、無効または別のプロジェクトの project_id、見つからない ID、検証エラーなど）、または未処理の例外が発生した場合、MCP ツールエラー（isError=True）。エラーメッセージには、上流のステータスコードとメッセージが含まれます。たとえば、API Error (401): Api key not found です。v1.8.0 より前は、ツールはこうしたエラーを握りつぶし、成功したツールの結果としてプレーンな "Error: ..." 文字列を返していました。そのため、isError だけを確認するクライアントには成功したように見えていました。この問題は修正され、すべてのツールがエラー文字列を返すのではなく ToolError を送出するようになったため、エラーは常に実際のツールエラーとして報告されます。

実行

依存関係をインストールします。

pip install -r requirements.txt

stdio 経由で実行します。

python server.py

HTTP 経由で実行します（fastmcp CLI が利用可能な場合）。

fastmcp run server.py:mcp --transport streamable-http --host 0.0.0.0 --port 8000