CatchAll MCP server

The MCP server exposes CatchAll API tools to any MCP-compatible client. It handles authentication, tool routing, and response formatting so the client can submit jobs, poll status, retrieve results, manage monitors, configure webhooks, build company watchlists with datasets and entities, and organize work into projects.

Before you start

CatchAll API key from platform.newscatcherapi.com
MCP-compatible client (Claude, Cursor, VS Code, Windsurf, Zed, Warp, Gemini CLI, Roo Code, or any client that supports remote MCP)

Authentication

The MCP server resolves your API key from multiple sources:

x-api-key HTTP request header — recommended for all client configurations
?apiKey=YOUR_KEY URL query parameter — used by Claude.ai because its connector UI does not support custom request headers
Authorization: Bearer <key> HTTP request header
CATCHALL_API_KEY environment variable on the server host

Most client configurations use option 1 (the x-api-key header). Claude.ai uses option 2 (the apiKey query parameter) automatically. The tools check_health and get_version do not require authentication. To rotate your key, update your client configuration with the new key and restart the client.

When you pass the key through a --header flag (Claude Code, mcp-remote), use the header-name:value format with no space after the colon — for example x-api-key:YOUR_CATCHALL_API_KEY. A space or a missing colon is the most common reason a connection silently fails to authenticate.

Your configuration file contains your API key in plain text. Treat it as a secret and do not share it or commit it to version control.

Connect to Claude

Claude.ai
Claude Desktop
Claude Code

Open connectors

Go to claude.ai/customize/connectors. Click + and select Add custom connector.

Configure connection

Fill in the Add custom connector dialog:

Name: CatchAll
Remote MCP server URL:

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

Add and verify

Click Add. Verify that CatchAll appears under Web in your connectors list.

Test connection

Open a new chat and ask Claude to run check_health. This tool needs no API key, so a successful response confirms the connection itself works — isolating connection problems from key problems. Then try a real query, for example: “Find AI company acquisitions in the last 7 days, limit 10”. Claude should call the CatchAll tools and return structured results.

For Claude-specific features like the SKILL file and Python agents, see Claude integration.

Claude Desktop supports remote MCP servers through the Connectors UI (Settings > Customize > Connectors) — the same flow as Claude.ai.Alternatively, you can configure it via a JSON config file. This approach does not support native remote MCP, so it requires mcp-remote as a proxy.

Install Node.js

Run node --version to check if Node.js is installed. If the command fails, download and install it from nodejs.org before continuing.

Fix npm permissions (once)

Run this once to avoid permission errors when using npx:

sudo chown -R $(whoami) ~/.npm

Install mcp-remote

npm install -g mcp-remote

Open configuration file

macOS
Windows

~/Library/Application Support/Claude/claude_desktop_config.json

%APPDATA%\Claude\claude_desktop_config.json

Or open it from Claude Desktop: Settings > Developer > Edit Config.

Add CatchAll entry

Paste the following into the file:

{
  "mcpServers": {
    "catchall": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://catchall-mcp.newscatcherapi.com/mcp",
        "--header",
        "x-api-key:YOUR_CATCHALL_API_KEY"
      ]
    }
  }
}

Write the header value as x-api-key:YOUR_CATCHALL_API_KEY with no space after the colon (see Authentication).

On Windows, npx often cannot be launched directly from this config. If the server fails to start, wrap it with cmd: set "command": "cmd" and prepend "/c", "npx" to the args array.

Restart Claude Desktop

Save the file and quit Claude Desktop completely, then relaunch it. Claude Desktop loads MCP tools on startup.

Verify connection

Go to Settings > Developer. Next to catchall, the status should show running. To confirm end to end, open a new chat and ask Claude to run check_health — it needs no API key, so a clean response proves the connection works.

For Claude-specific features like the SKILL file and Python agents, see Claude integration.

Add the server

Run in your terminal:

claude mcp add --transport http catchall \
  "https://catchall-mcp.newscatcherapi.com/mcp" \
  --header "x-api-key:YOUR_CATCHALL_API_KEY"

Keep the colon tight: x-api-key:YOUR_CATCHALL_API_KEY with no space after the colon, or the header is sent malformed (see Authentication).

Verify connection

Run claude mcp list and confirm catchall is listed, or type /mcp inside a Claude Code session to see it marked as connected.

Test connection

In a session, ask Claude to run check_health. This tool needs no API key, so a successful response confirms the connection works before you spend credits on a real query. Then try: “Find AI company acquisitions in the last 7 days, limit 10”.

For Claude-specific features like the SKILL file and Python agents, see Claude integration.

Connect to other clients

Or add to ~/.cursor/mcp.json manually:

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

Restart Cursor after saving.

Or add to .vscode/mcp.json in your project root manually:

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

Restart VS Code after saving.

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "catchall": {
      "serverUrl": "https://catchall-mcp.newscatcherapi.com/mcp",
      "headers": {
        "x-api-key": "YOUR_CATCHALL_API_KEY"
      }
    }
  }
}

Restart Windsurf after saving.

Add to your Zed settings (~/.config/zed/settings.json):

{
  "context_servers": {
    "catchall": {
      "url": "https://catchall-mcp.newscatcherapi.com/mcp",
      "headers": {
        "x-api-key": "YOUR_CATCHALL_API_KEY"
      }
    }
  }
}

Restart Zed after saving.

Go to Settings > MCP Servers > Add MCP Server and add:

{
  "catchall": {
    "url": "https://catchall-mcp.newscatcherapi.com/mcp",
    "headers": {
      "x-api-key": "YOUR_CATCHALL_API_KEY"
    }
  }
}

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "catchall": {
      "httpUrl": "https://catchall-mcp.newscatcherapi.com/mcp",
      "headers": {
        "x-api-key": "YOUR_CATCHALL_API_KEY"
      }
    }
  }
}

Restart Gemini CLI after saving.

Add to your Roo Code MCP config:

{
  "mcpServers": {
    "catchall": {
      "type": "streamable-http",
      "url": "https://catchall-mcp.newscatcherapi.com/mcp",
      "headers": {
        "x-api-key": "YOUR_CATCHALL_API_KEY"
      }
    }
  }
}

Restart Roo Code after saving.

For clients that support native HTTP MCP with headers:

{
  "mcpServers": {
    "catchall": {
      "url": "https://catchall-mcp.newscatcherapi.com/mcp",
      "headers": {
        "x-api-key": "YOUR_CATCHALL_API_KEY"
      }
    }
  }
}

If your client does not support remote MCP servers natively, use mcp-remote as a proxy:

{
  "mcpServers": {
    "catchall": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://catchall-mcp.newscatcherapi.com/mcp",
        "--header",
        "x-api-key:YOUR_CATCHALL_API_KEY"
      ]
    }
  }
}

Write the header value as x-api-key:YOUR_CATCHALL_API_KEY with no space after the colon (see Authentication).Restart your client after saving the configuration.

Replace YOUR_CATCHALL_API_KEY with your key. Do not share it or commit it to version control.

Available tools

Each tool maps to a CatchAll API endpoint. For request and response schemas, see the API reference. The server ships usage guidance to the client automatically, so Claude already knows the job lifecycle — submit_query creates a job, get_job_status polls it, and pull_results retrieves records once it completes. You do not need to explain this flow yourself.

Jobs consume API credits in proportion to how many records they process. When testing a new query, pass a small limit (for example, “limit 10”) to keep cost low, then raise it or use continue_job once the results look right.

Tool	Description
`validate_query`	Check query quality before submission — returns `good`, `needs_work`, or `critical` with suggestions
`initialize_query`	Preview suggested validators, enrichments, and date ranges before submitting a job.
`submit_query`	Submit a natural language query and create a job.
`get_job_status`	Check job progress through the processing pipeline
`pull_results`	Retrieve validated, enriched records from a completed or in-progress job
`pull_job_csv`	Download completed job results as a CSV file — prefer over `pull_results` when a spreadsheet format is needed
`continue_job`	Expand a job to process additional records beyond the initial limit
`list_user_jobs`	List all jobs submitted by the authenticated user
`delete_job`	Delete a job and its results

Tool	Description
`create_monitor`	Create a recurring monitor from a completed reference job
`update_monitor`	Update settings (webhook IDs, per-run limit) for an existing monitor
`list_monitors`	List all monitors for the authenticated user
`list_monitor_jobs`	List all jobs produced by a specific monitor
`pull_monitor_results`	Retrieve latest aggregated results from a monitor
`pull_monitor_csv`	Download the most recent monitor run results as a CSV file
`get_monitor_status`	Get the full execution history and state changes for a monitor
`enable_monitor`	Re-enable a previously disabled monitor
`disable_monitor`	Pause a monitor without deleting it
`delete_monitor`	Permanently delete a monitor

Tool	Description
`create_webhook`	Register a named webhook endpoint with delivery mode and auth configuration
`list_webhooks`	List all webhook endpoints for the authenticated user
`get_webhook`	Get full configuration details for a webhook
`update_webhook`	Update webhook URL, delivery mode, or auth settings
`test_webhook`	Send a test payload to verify endpoint reachability before attaching to a resource
`assign_webhook_resource`	Attach a webhook to a job or monitor
`list_webhook_resources`	List all resources (jobs and monitors) assigned to a webhook
`remove_webhook_resource`	Detach a webhook from a specific resource
`list_resource_webhooks`	List all webhooks attached to a specific job or monitor
`get_webhook_history`	Retrieve per-dispatch delivery outcomes and HTTP status codes
`trigger_webhook`	Manually trigger webhook delivery for a job, monitor, or monitor_group — dispatch is asynchronous; use `get_webhook_history` to see the outcome
`delete_webhook`	Delete a webhook endpoint

Datasets are named collections of entities (companies or people) used to scope job results to a predefined watchlist. Pass connected_dataset_ids in submit_query to activate company search mode.Datasets

Tool	Description
`create_dataset`	Create a new dataset from a list of entity IDs
`list_datasets`	List all datasets for the authenticated user
`get_dataset`	Get dataset details and metadata
`update_dataset`	Update dataset name or description
`add_dataset_entities`	Add entities to an existing dataset
`remove_dataset_entities`	Remove entities from a dataset
`list_dataset_entities`	List all entities in a dataset
`get_dataset_status`	Check dataset enrichment progress and health score
`create_dataset_from_csv`	Create a new dataset by uploading CSV content — pass raw CSV text or base64 in the `file` parameter (inline content only, 10 MB cap; server-side file paths are not accepted)
`append_csv_to_dataset`	Append entities to an existing dataset from CSV content — same `file` format as `create_dataset_from_csv`
`delete_dataset`	Delete a dataset (entities are preserved)

Entities

Tool	Description
`create_entity`	Create a single company or person entity.
`create_entities_batch`	Bulk-create multiple entities in one call
`list_entities`	List all entities for the authenticated user
`get_entity`	Get details for a specific entity
`update_entity`	Update entity name, domain, or metadata.
`delete_entity`	Delete an entity

Projects group related jobs, monitors, and datasets into named containers that can be shared with teammates and filtered across all list endpoints.

Tool	Description
`create_project`	Create a new project container
`list_projects`	List all projects for the authenticated user
`get_project`	Get project details and metadata
`update_project`	Update project name or description
`get_project_overview`	Get a resource count breakdown by type and status
`add_project_resources`	Add jobs, monitors, or datasets to a project
`list_project_resources`	List all resources inside a project
`remove_project_resource`	Remove a resource from a project without deleting it
`delete_project`	Delete a project (resources are preserved by default)

Tool	Description
`check_health`	Check API health status (no authentication required)
`get_version`	Get the current API version (no authentication required)
`get_user_limits`	Retrieve plan features and current usage against plan limits

Troubleshooting

Tools not appearing

Restart your MCP client after updating the configuration. Most clients load MCP tools on startup and do not detect changes until restarted.

Connection refused or timeout

Verify your API key is valid by calling an authenticated endpoint:

curl -X POST "https://catchall.newscatcherapi.com/catchAll/initialize" \
  -H "x-api-key: YOUR_CATCHALL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "test"}'

If this returns a 403 error, your key is invalid. Check it at platform.newscatcherapi.com.

Client does not support remote MCP

Use mcp-remote to proxy the connection. Install Node.js, then use the npx configuration shown in the Other clients tab.

Claude integration

Full Claude setup with MCP and Skills

CatchAll Skills

Specialized agent skills for competitive intelligence, funding, M&A, and more

API reference

Full endpoint documentation and schemas

Write effective queries

Get better results from CatchAll jobs

Get started

Concepts

How to

API Reference

Libraries

Integrations

Before you start

Authentication

Connect to Claude

Connect to other clients

Available tools

Troubleshooting

See also

Claude integration

CatchAll Skills

API reference

Write effective queries

​Before you start

​Authentication

​Connect to Claude

​Connect to other clients

​Available tools

​Troubleshooting

​See also

Claude integration

CatchAll Skills

API reference

Write effective queries

Before you start

Authentication

Connect to Claude

Connect to other clients

Available tools

Troubleshooting

See also