catchall-mcp

catchall-mcp is an MCP server released by NewsCatcher, used to interface with the NewsCatcher CatchAll Web Search API. It is positioned as a "recall-first" open web search capability, with the goal of finding relevant events on the open web, not just limited to conventional top search results.

Purpose and Positioning This server exposes the capabilities of the CatchAll Web Search API to AI clients through the Model Context Protocol (MCP). An official hosted instance is provided: users do not need to clone or run this repository themselves; they first obtain a CatchAll API key at platform.newscatcherapi.com and then connect; it can also be integrated through the Claude Code CLI. Its full integration documentation is available at https://www.newscatcherapi.com/docs/web-search-api/integrations/mcp。若希望自行运行，可选择本地或自托管方式，仓库中也给出了相关运行说明。

Main Capabilities and Tool Mapping The server maps multiple MCP tools to API endpoints.

1. Jobs and queries: initialize_query is used to preview validators, enhancements, and date windows. It is preview-only, does not create a job, and the suggested results are non-deterministic. submit_query is used to submit a query, with query being required; optional fields may be provided only in part, and fields not provided will be automatically selected or generated. start_date and end_date filter the web page discovery date, not the event date in the extracted content; if event time accuracy is needed, event-oriented validators or enhancements should be used, and the event_date in the results should be checked. Job status is polled with get_job_status; it is recommended to check the first time after about 1-2 minutes, and then every 30-60 seconds until the status is completed or failed. pull_results is used to pull results; partial data also appears during the enriching stage; pagination should be done via page < total_pages to retrieve all available records. continue_job is used to process more records (which affects cost) and applies only to jobs originally submitted with limit; its new_limit is optional, and when omitted the API defaults to the plan limit.
2. List filtering: list_user_jobs supports search, ownership, project_id, and mode (base or lite) filters in addition to page / page_size.
3. Webhook: create_webhook can accept an optional project_id at creation time to bind the Webhook to a project; list_webhooks likewise accepts an optional project_id, used to filter Webhooks for a specific project. get_webhook_history has two query modes: pass resource_type and resource_id to query deliveries for a certain job/monitor/monitor_group, or pass webhook_id to query all content delivered through that Webhook; only one of these modes can be used in a single call. Manual test delivery (test_webhook) appears only in webhook mode,and record it with resource_type: "test".
4. Project resources: resource_type can be job, monitor, dataset, monitor_group, or webhook. A Webhook can belong to multiple projects at the same time. delete_project with delete_resources=true deletes the job, monitor, dataset, and monitor_group it contains, but Webhooks are only unlinked, not deleted, and the response's deleted_resources reports them with a webhook_unlinked count.
5. CSV upload (v1.6.1): create_dataset_from_csv and append_csv_to_dataset receive CSV content through the file parameter—raw CSV text or standard base64. They do not read paths from the server file system, so they are safer on remote or hosted MCP. Inline CSV content has a hard cap of 10 MB (after base64 decoding). create_dataset_from_csv also accepts the newly added optional project_id field.
6. Entities: external_entity_id (v1.6.3): create_entity and update_entity accept an optional external_entity_id string, which is a customer-provided identifier used to link the entity to a record in an external system. project_id (v1.8.0): list_entities accepts an optional project_id, used to filter entities belonging to a specific project.
7. Source groups (v1.8.0): named and reusable domain allowlists (public groups, plus organization-visibility groups accessible to the organization). list_source_groups returns each group's slug, name, and description. The direct API's POST /catchAll/submit now accepts a source_groups field (a list of slugs), used to limit the crawl scope to the domain allowlist; submit_query does not yet expose this parameter, so use the direct API until it is added in a later version.

Usage and authentication The API key priority, from highest to lowest, is: the api_key tool parameter, the x-api-key request header, the Authorization: Bearer <key> request header, the URL query parameter ?apiKey=..., the environment variable CATCHALL_API_KEY. check_health and get_version do not require API key authentication. Hosted deployment (FastMCP Gateway) notes: when deployed via fastmcp.app, a stateless gateway sits in front of the server. The gateway forwards HTTP headers to the backend, but does not forward URL query parameters. Therefore, use the x-api-key request header or the CATCHALL_API_KEY environment variable instead of ?apiKey=. The same applies in Claude Code / Cursor. If you access the server directly (without going through the gateway), ?apiKey=YOUR_KEY in the URL still works. Regarding how to run it, the repository instructions include: installing dependencies, running via stdio, and (if there is a fastmcp CLI) running via HTTP.

Core workflow (jobs) Optional: call initialize_query to preview validators, enhancements, and the date window (preview only, does not create a job; recommended for non-determinism). Then submit with submit_query (query is required); you can send only query, and the remaining optional fields will be automatically selected or generated; the optional fields are independent of each other, and you can provide only any subset (for example, only a custom validator), while the ones not provided will still be automatically generated. start_date / end_date filter the web page discovery date, not the event date. Poll get_job_status at the above cadence until completed or failed. Pull with pull_results; there will be partial data during enriching; paginate through everything with page < total_pages. Use continue_job only when you need to process more records (affects cost), and it only applies to jobs originally submitted with a limit.

The difference between limit and page_size limit (submit_query, continue_job) controls how many records are processed, and therefore affects cost; if provided, it must be >= 10; if omittedThen take all up to the plan limit. page_size (pull_results, list_user_jobs) only controls pagination and does not affect processing cost; pull_results.page_size defaults to 100, with a range of 1..1000. The pull_results response includes error (failed jobs) and limit (the job limit that was applied). page/page_size/total_pages represent records that are already available; you can use progress_validated < candidate_records to determine whether more records may still appear.

Monitor constraints When create_monitor.backfill=true, the end_date of the reference job must be within the last 7 days; when backfill=false, this reference job time constraint does not apply. The minimum monitor scheduling frequency depends on the plan. create_monitor supports optional limit (minimum 10), backfill (default true), timezone, webhook_ids, and project_id. Webhooks are centrally managed in v1.5.3: first register with create_webhook, then associate by ID via create_monitor.webhook_ids / update_monitor.webhook_ids (no more inline Webhook configuration). Monitors only support base jobs (lite is not supported). enable_monitor supports optional backfill. update_monitor can update webhook_ids, run limit, schedule, and/or timezone (passing webhook_ids=[] clears associations; unless schedule is also set, timezone is ignored). list_monitors supports pagination via page and page_size, and supports filtering by search, ownership, and project_id; it returns total, page, page_size, total_pages, monitors.

Enriched output description enrichment.enrichment_confidence always exists. Company enrichment results are structured objects containing source_text, confidence, metadata.name, metadata.domain_url, metadata.domain_url_confidence. On success, it returns a pretty JSON string.

Error behavior (v1.8.0) For any upstream non-2xx response (wrong api_key, invalid or foreign project_id, ID not found, validation failure, etc.) or unhandled exception, the MCP tool reports an error (isError=True). Error messages include the upstream status code and message, for example API Error (401): Api key not found. Before v1.8.0, tools swallowed these failures and returned "Error: ..." as a successful result, so clients that only checked isError saw false success; this has now been fixed, and every tool raises ToolError, so failures are always reported as real tool errors.

Applicable scenarios and limitations It is suitable for scenarios where you want to connect AI clients via MCP, perform event discovery and lead search on the open web, set up queries and pull or continuously monitor results, and use enrichments and source groups to narrow the crawl scope. Limitations include: a valid CatchAll API key is required; job processing volume, monitor frequency, pagination range, and more are subject to plan and API constraints; submit_query does not yet support source_groups; monitors are limited to base jobs; under a hosted gateway, request headers or environment variables must be used instead of URL query parameters.