Newscatcher CatchAll MCP Server

MCP server for the NewsCatcher CatchAll Web Search API.

Quick Start — Use Our Hosted Server

You don't need to clone or run this repo to use the MCP — NewsCatcher runs a hosted instance:

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

Get a CatchAll API key at platform.newscatcherapi.com, then connect:

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

Or via Claude Code CLI:

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

Full integration docs: https://www.newscatcherapi.com/docs/web-search-api/integrations/mcp

Prefer to run the server yourself (locally or self-hosted)? See Running below.

Tool To Endpoint Mapping

Jobs

Job listing filters: list_user_jobs supports search, ownership, project_id, and mode (base or lite) filters in addition to page/page_size.

Monitors

Webhooks

Webhook notes: create_webhook accepts an optional project_id to attach the webhook to a project on creation. list_webhooks also accepts an optional project_id to filter to webhooks belonging to a specific project. get_webhook_history queries in one of two modes — pass resource_type + resource_id for a job/monitor/monitor_group's deliveries, or pass webhook_id for everything delivered through one webhook (exactly one mode per call). Manual test deliveries (test_webhook) only appear in webhook mode and are recorded with resource_type: "test".

Projects

Project resources: resource_type is one of job, monitor, dataset, monitor_group, or webhook. A webhook can belong to several projects at once. delete_project with delete_resources=true deletes the contained jobs, monitors, datasets, and monitor groups, but webhooks are only detached — never deleted — and the response's deleted_resources reports them under a webhook_unlinked count.

Datasets

CSV uploads (v1.6.1): create_dataset_from_csv and append_csv_to_dataset take the CSV content in the file parameter — raw CSV text or standard base64. They never read a path from the server's filesystem, so they stay safe on a remote/hosted MCP. Inline CSV content is capped at a hard 10 MB (after base64 decoding). create_dataset_from_csv also accepts the new optional project_id field.

Entities

external_entity_id (v1.6.3): create_entity and update_entity accept an optional external_entity_id string — a customer-supplied identifier that links the entity to a record in an external system. project_id (v1.8.0): list_entities accepts an optional project_id to filter to entities belonging to a specific project.

Source Groups

Source groups (v1.8.0): named, reusable domain allowlists (public groups plus any organization-visibility groups your organization can access). list_source_groups returns each group's slug, name, and description. The direct API's POST /catchAll/submit now accepts a source_groups field of slugs to scope fetching to a domain allowlist; submit_query does not yet expose this parameter — use the direct API for that until a future release adds it here.

User & Meta

Authentication

API key precedence (highest to lowest):

1. api_key tool parameter
2. x-api-key request header
3. Authorization: Bearer <key> request header
4. URL query parameter ?apiKey=...
5. CATCHALL_API_KEY environment variable

check_health and get_version do not require API key auth.

Hosted deployment (FastMCP Gateway)

When deployed via fastmcp.app, a stateless gateway sits in front of the server. The gateway forwards HTTP headers to the backend but not URL query parameters. Use the x-api-key header or CATCHALL_API_KEY environment variable instead of ?apiKey=.

Claude Code / Cursor:

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

Or via CLI:

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

Direct server access (no gateway): ?apiKey=YOUR_KEY in the URL still works.

Core Workflow (Jobs)