News API MCP server

The MCP server exposes News API tools to any MCP-compatible client. It handles authentication, request formatting, and response formatting so the client can search articles, pull latest headlines and breaking news, look up an author’s work, resolve articles by URL or ID, browse sources, get aggregation counts, and check subscription/quota status.

MCP tool	News API endpoint
`search_articles`	`POST /api/search`
`get_latest_headlines`	`POST /api/latest_headlines`
`get_breaking_news`	`POST /api/breaking_news`
`search_by_author`	`POST /api/authors`
`search_by_link`	`POST /api/search_by_link`
`list_sources`	`POST /api/sources`
`get_aggregation_count`	`POST /api/aggregation_count`
`get_subscription`	`POST /api/subscription`
`check_health`	(local liveness ping — no upstream call)

Every tool uses POST under the hood even though News API also exposes a GET variant of each endpoint — POST keeps API keys and queries out of access logs, avoids URL-length limits, and lets multi-value filters be sent as native JSON arrays. The server is open source. Source code, changelog, and issue tracker: Newscatcher/news-mcp.

Setting up with an AI agent? Paste this into Claude, Cursor, or any agent with web access, with your key filled in. The agent setup page is written for the agent: it picks the right path for the client it is running in and verifies the key with one call.

Read and follow https://www.newscatcherapi.com/docs/news-api/integrations/mcp-agent-setup.md and set up the News API MCP server for me. My News API key: YOUR_NEWS_API_KEY

Before you start

News API key from platform.newscatcherapi.com/newsapi or you can use your existing API Key
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, in this order (first match wins):

api_token parameter set on the tool call itself
?apiToken=YOUR_KEY URL query parameter — used by some Agents which have no field for custom request headers
x-api-token HTTP request header — recommended for every client that supports custom headers
Authorization: Bearer <key> HTTP request header
NEWS_API_KEY environment variable on the server host (self-hosted only)

Most client configurations use option 3 (the x-api-token header). Claude.ai and Claude Desktop use option 2 (the apiToken query parameter) through their connector URL. check_health is the only tool that does not require authentication — it’s a local liveness ping and never calls News API. 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-token:YOUR_NEWS_API_KEY. A space or a missing colon is the most common reason a connection silently fails to authenticate.

Configure only one authentication method per client. If a request carries ?apiToken=, it wins over an x-api-token or Authorization header sent alongside it — and the key seen on the session’s first request is reused for the rest of that session. A stale key in the URL keeps returning 401 even when the header holds a valid one.

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.

If you are rolling the MCP out to a team, issue a separate API key for it rather than reusing a production key. MCP traffic stays attributable in the dashboard, and you can rotate or revoke that key without touching anything in production. Ask our support@newscatcherapi.com to help you out.

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: News API
Remote MCP server URL:

https://news-mcp.newscatcherapi.com/mcp?apiToken=YOUR_NEWS_API_KEY

Add and verify

Click Add. Verify that News API 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 ask for get_subscription. That is the first call that actually uses your key, and it returns your plan, remaining calls, concurrency limit, and how far back you can search.Finally, try a real query. Name a time window, a result count, and the fields you want, so the response stays a readable size: “Get the latest headlines about renewable energy from the last 2 days, 10 results, just title, link, date and source.”

Claude Desktop connects to remote MCP servers through the same Connectors screen as Claude.ai. No config file, no Node.js, no restart.

Open connectors

In Claude Desktop, open Settings > Connectors (under Customize on some versions) and click Add custom connector.

Configure connection

Fill in the Add custom connector dialog:

Name: News API
Remote MCP server URL:

https://news-mcp.newscatcherapi.com/mcp?apiToken=YOUR_NEWS_API_KEY

Add and test

Click Add. The tools are available in the next new chat, with no restart.Ask Claude to run check_health. It needs no API key, so a clean response proves the connection itself works. Then ask for get_subscription, the first call that uses your key: it returns your plan, remaining calls, concurrency limit, and how far back you can search.For a real query, name a time window, a result count, and the fields you want: “Get the latest headlines about renewable energy from the last 2 days, 10 results, just title, link, date and source.”

Alternative: JSON config file with mcp-remote

Use this only if the Connectors screen is not available to you. Claude Desktop’s JSON config does not speak remote MCP directly, so this path needs Node.js, the mcp-remote proxy, and a full restart of the app.

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 News API entry

Paste the following into the file:

{
  "mcpServers": {
    "news": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://news-mcp.newscatcherapi.com/mcp",
        "--header",
        "x-api-token:YOUR_NEWS_API_KEY"
      ]
    }
  }
}

mcp-remote splits the --header value on the first colon, so write it as x-api-token:YOUR_NEWS_API_KEY with no space after the colon.

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 news, 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. Then ask for get_subscription to confirm the key itself is valid and see your remaining quota.

Add the server

Run in your terminal:

claude mcp add --transport http news \
  "https://news-mcp.newscatcherapi.com/mcp" \
  --header "x-api-token:YOUR_NEWS_API_KEY"

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

Verify connection

Run claude mcp list and confirm news 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 ask for get_subscription to validate the key and see your quota.For a real query, name a time window, a result count, and the fields you want: “Get the latest headlines about renewable energy from the last 2 days, 10 results, just title, link, date and source.”

Connect to other clients

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

{
  "mcpServers": {
    "news": {
      "type": "http",
      "url": "https://news-mcp.newscatcherapi.com/mcp?apiToken=YOUR_NEWS_API_KEY"
    }
  }
}

The one-click button installs the URL with the literal YOUR_NEWS_API_KEY placeholder in it. Open ~/.cursor/mcp.json afterwards and replace it with your key, then restart Cursor.

A deeplink cannot carry a prompted secret, so the button installs the header with the literal YOUR_NEWS_API_KEY placeholder. Open .vscode/mcp.json and replace it before your first call, or every call fails with 401: Invalid api key.Or add it to .vscode/mcp.json in your project root manually. This way VS Code prompts for the key and stores it, so it never lands in a file you might commit:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "news-api-key",
      "description": "News API key",
      "password": true
    }
  ],
  "servers": {
    "news": {
      "type": "http",
      "url": "https://news-mcp.newscatcherapi.com/mcp",
      "headers": {
        "x-api-token": "${input:news-api-key}"
      }
    }
  }
}

VS Code asks for the key the first time the server starts and reuses it afterwards.Restart VS Code after saving.

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

{
  "mcpServers": {
    "news": {
      "serverUrl": "https://news-mcp.newscatcherapi.com/mcp",
      "headers": {
        "x-api-token": "YOUR_NEWS_API_KEY"
      }
    }
  }
}

Restart Windsurf after saving.

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

{
  "context_servers": {
    "news": {
      "url": "https://news-mcp.newscatcherapi.com/mcp",
      "headers": {
        "x-api-token": "YOUR_NEWS_API_KEY"
      }
    }
  }
}

Restart Zed after saving.

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

{
  "news": {
    "url": "https://news-mcp.newscatcherapi.com/mcp",
    "headers": {
      "x-api-token": "YOUR_NEWS_API_KEY"
    }
  }
}

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "news": {
      "httpUrl": "https://news-mcp.newscatcherapi.com/mcp",
      "headers": {
        "x-api-token": "YOUR_NEWS_API_KEY"
      }
    }
  }
}

Restart Gemini CLI after saving.

Add to your Roo Code MCP config:

{
  "mcpServers": {
    "news": {
      "type": "streamable-http",
      "url": "https://news-mcp.newscatcherapi.com/mcp",
      "headers": {
        "x-api-token": "YOUR_NEWS_API_KEY"
      }
    }
  }
}

Restart Roo Code after saving.

For clients that support native HTTP MCP with headers:

{
  "mcpServers": {
    "news": {
      "url": "https://news-mcp.newscatcherapi.com/mcp",
      "headers": {
        "x-api-token": "YOUR_NEWS_API_KEY"
      }
    }
  }
}

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

{
  "mcpServers": {
    "news": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://news-mcp.newscatcherapi.com/mcp",
        "--header",
        "x-api-token:YOUR_NEWS_API_KEY"
      ]
    }
  }
}

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

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

Available tools

Each tool maps to a News API endpoint. For request and response schemas, see the API reference.

Tool	Description
`search_articles`	Full-text/boolean search over articles, with date, language, source, entity, and NLP filters — clustered by default
`get_latest_headlines`	Recent headlines over a rolling time window, no keyword required — clustered by default
`get_breaking_news`	Actively trending, most-corroborated stories over a fixed window
`search_by_author`	All articles by one exact byline
`search_by_link`	Look up specific already-known articles by NewsCatcher `id` or URL
`list_sources`	Browse and verify publishers — requires at least one filter parameter
`get_aggregation_count`	Time-bucketed article-volume counts for a query, no articles returned
`get_subscription`	Plan tier, monthly quota, remaining calls, concurrency limit, and history window
`check_health`	Local liveness ping — no authentication required

“Latest”/“most recent” needs sort_by="date" explicitly — every tool that takes sort_by defaults to "relevancy", not "date". There is a hard cap of 10,000 articles per query regardless of pagination; call get_aggregation_count on a broad or undated query first and time-chunk the date range if the count is high.

What you get by default

The MCP ships instructions that steer the assistant toward sensible parameters for whatever you asked, so in practice you rarely see the bare defaults. This table is the floor rather than the typical experience: it’s what you get when neither you nor the assistant sets the parameter, whether the value comes from the MCP or from News API itself. That’s what you need when a result comes back empty or in a shape you didn’t expect.

Parameter	Value when unset	How to change it
Date range	Last 7 days	Set `from_` and `to_`, e.g. `from_="2026-03-01"`
Sort order	`relevancy`	`sort_by="date"` for “latest” or “most recent”
Results per call	`page_size=50` on `search_articles` and `get_latest_headlines`, `100` elsewhere (max `1000`)	Lower it for chat-sized answers
Clustering	On for `search_articles` and `get_latest_headlines`	`clustering_enabled=false`
NLP payload	On	`include_nlp_data=false`
Near-duplicate removal	On for `search_articles`	`exclude_duplicates=false`
Fields per article	A lean nine-key set	Pass your own `fields` list

The default date range is the last 7 days. An undated query about something that happened three months ago comes back empty — that is the date window, not a coverage gap. Set from_ and to_ for anything historical, or say the range in your prompt. See Working with historical data.

Two more limits worth knowing:

There is a hard cap of 10,000 articles per query, regardless of pagination. If total_hits reads exactly 10000, the real count is likely higher — narrow the query or split the date range. See Retrieve more than 10k articles.
The upstream request timeout is 30 seconds. A 408 means: narrow the query, shorten the date range, or reduce page_size.

Clustered results by default

search_articles and get_latest_headlines return grouped results unless you ask for a flat list. Their defaults:

Parameter	Default	Effect
`clustering_enabled`	`true`	Response has `clusters_count` and `clusters` (each `{cluster_id, cluster_size, articles}`) instead of a flat `articles` list
`page_size`	`50`	Sized for the grouped view rather than a flat article dump
`cluster_top_n_articles`	`3`	Shows at most three articles per cluster; `cluster_size` still reports the real total

Clustering regroups results, it does not shrink them: every matched article lands in a cluster and none are dropped, so one heavily syndicated story can otherwise fill a whole page with near-identical coverage. cluster_top_n_articles trims each cluster’s articles list while leaving cluster_size intact, so you always see how wide a story’s coverage actually is. Pass null for no cap. Turn clustering off when you want the articles themselves rather than grouped topic coverage — tracking a single outlet, checking whether a specific source covered a story, or paginating through a flat list:

Search for articles about AI regulation from reuters.com,
with clustering_enabled false and page_size 20

With clustering on, the exact article or source you are after may fall outside the top three of its cluster and never reach the response. See Clustering news articles for how the grouping itself works.

Other tools are unaffected. get_breaking_news returns story clusters with its own API-native top_n_articles parameter, and search_by_author, search_by_link, and get_aggregation_count remain unclustered with a default page_size of 100.

Response fields

search_articles, get_latest_headlines, get_breaking_news, search_by_author, and search_by_link accept a fields parameter that trims each article to the keys you name. News API returns around 40 fields per article and the content body alone can push a 30-article call past 300 KB, so these tools default to a lean set instead:

title, link, published_date, domain_url, author, language,
nlp.summary, nlp.translation_summary, nlp.theme

To get the full article object, pass fields explicitly as an empty list ([]) or as null. Leaving fields out of the call does not do this — an omitted fields applies the lean default like any other call. Only an explicit [] or null opts out. Field names are validated against the real article schema before the request goes out, so a typo returns a corrective error instead of silently disappearing from the response. NLP subfields need a dotted path — nlp.theme, nlp.sentiment, nlp.ner_ORG — or pass nlp alone for the whole block. There is no top-level summary field: use description for the short lede or nlp.summary for the AI-generated summary.

For the boolean toggles — clustering_enabled, exclude_duplicates, include_nlp_data, include_translation_fields — an explicit null means the same as omitting the parameter: the tool’s own default applies. fields and cluster_top_n_articles are the two exceptions, where null carries its own meaning (all fields, and no per-cluster cap).

Response size cap

Article-returning tools (search_articles, get_latest_headlines, get_breaking_news, search_by_author) cap each response at 250,000 bytes. A broad request — fields=[] with a large page_size and no filters — would otherwise return a payload big enough to swamp the client’s context window. The cap drops trailing articles until the response fits; it never touches the content of the articles it keeps, and it does not fire on responses that already fit, which is nearly all of them. When it does trim, the response carries a response_capped block:

{
  "response_capped": {
    "reason": "response exceeded the 250000-byte cap",
    "kept": 42,
    "dropped": 958,
    "hint": "narrow the query (add filters, pass fields=[...] instead of fields=[], or reduce page_size) to get more back in one call, or paginate with `page`"
  }
}

If you see it, narrow the query, name the fields you actually need instead of requesting the full object, lower page_size, or page through the results.

Keeping responses small

The cap is a backstop, not a budget. Every tool result lands in your client’s context window, and a response that fits comfortably under 250,000 bytes can still crowd out the conversation around it. The MCP already trims each article to the lean field set above, so the full content body and the large link arrays never cross the wire. What it does not trim is how many articles come back. Three levers, in order of impact:

page_size — the big one. 10 to 25 is usually right for an answer you are going to read, against a default of 50.
clustering_enabled=false — a flat list with no cluster wrapper, when you want the articles rather than the grouping.
include_nlp_data=false — drops the per-article nlp block when you are not using summaries, themes, sentiment, or entities.

You can also pass your own fields list to narrow the default set further, or widen it when you need something it leaves out — description, content, rank, or the sentiment and entity fields under nlp. None of this has to be named explicitly. Say what you want in the prompt and the client sets the parameters for you: “20 results, just title, link, date and source, skip the NLP data.”

Language and country codes

lang and countries take two-letter codes, never full names. This is the single most common cause of rejected requests. The MCP checks both before the call reaches News API and tells you what went wrong:

lang — NewsCatcher two-letter language codes: en, es, de. Chinese is cn (China) or tw (Taiwan); the ISO code zh is not accepted.
countries — ISO 3166-1 alpha-2: US, GB, DE. The United Kingdom is GB, not UK, and three-letter codes are not accepted.

Quota and rate limits

Every tool call except check_health is one billed News API call against your plan quota. An assistant working through an open-ended question can easily fire ten or twenty calls in a minute — one to gauge volume, several to page through results, more to follow up — so the meter moves faster here than it does with hand-written API calls. Ask for get_subscription at any point to see where you stand:

{
  "active": true,
  "plan": "v3_nlp",
  "plan_calls": 250000,
  "remaining_calls": 249436,
  "concurrent_calls": 5,
  "historical_days": 3000
}

remaining_calls — calls left in the current billing period.
concurrent_calls — how many requests you can have in flight at once. Going over returns 429; back off and retry rather than repeating the request immediately.
historical_days — how far back your plan can search, which also tells the assistant which date ranges are worth trying at all.

Example prompts

Prompts work best when they name three things: a time window, a result count, and the fields you want back. These are written for Claude but work in any client. Track coverage of a company or brand

What’s been published about Siemens Energy in the last 3 days? English only, 20 results, just title, link, date and source.

See which stories got the widest pickup

Find coverage of the EU AI Act between 2026-08-20 and 2026-08-27, cluster it, and show me the five biggest clusters with their size and one representative headline each.

Read the tone of recent coverage

Search for articles about Ryanair from the last 7 days with NLP data on, 50 results, then list the 10 with the most negative content sentiment and link each one.

News API sorts by relevancy, date, or rank — not by sentiment — so the assistant fetches a page and ranks it itself. Keep the result count modest for this one, or filter server-side with content_sentiment_max. Follow a person or organization as an entity

Find articles from the last 14 days that name Christine Lagarde as a person entity, not just ones that mention the words. 25 results, title, link, date and source.

See Search by entity for what entity matching does differently. Measure how a topic trends over time

Give me daily article counts for “electric vehicle tariffs” from 2026-06-01 to 2026-08-31, then tell me which week spiked and what was behind it.

Catch what is breaking right now

What are the biggest breaking stories right now? Headlines and links only.

Check whether a publisher is indexed

Do you index reuters.com, ft.com and nikkei.com? Show me what coverage you have for each.

Pull details for an article you already have

Here’s a URL: https://example.com/some-article. Pull it and tell me the byline, publish date and word count.

If a result comes back enormous, or your client truncates it, add “10 results, just title, link, date and source” to the prompt. See Keeping responses small.

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. A connector added through the Claude.ai or Claude Desktop Connectors screen needs no restart: open a new chat.

Connection refused or timeout

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

curl -X POST "https://v3-api.newscatcherapi.com/api/search" \
  -H "x-api-token: YOUR_NEWS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "test"}'

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

Tool calls returning errors

Tools return a JSON string on success — compact for the article and source tools, pretty-printed for get_subscription and check_health. A validation or upstream API error comes back as a string starting with Error: ...; an unhandled exception comes back as Unexpected error: .... The string names the specific reason.Both are returned as a successful tool result — the MCP isError flag stays false — so your client shows an ordinary, completed tool call and the assistant may describe the failure as though it were data. When an answer looks wrong, open the raw tool output and read the returned string.

401 even though the key is correct

Check whether the configured server URL still carries ?apiToken=.... The query parameter takes priority over the x-api-token header, so an old parameter silently wins over a newly added header. See Authentication.

No results, or only very recent results

Queries default to the last 7 days. If you asked about something older and got nothing back, add an explicit range — “from 2026-03-01 to 2026-03-31” — and check historical_days from get_subscription to confirm your plan reaches that far. See What you get by default.

429 errors or stalled requests

You are over your plan’s concurrency limit. Call get_subscription and read concurrent_calls for the ceiling, then back off and retry rather than repeating the request immediately. See Quota and rate limits.

Fewer results than expected

Three separate limits can shorten a response. Clustered results show at most cluster_top_n_articles articles per cluster (default 3) — cluster_size reports the true total. The response size cap drops trailing articles from oversized payloads and adds a response_capped block when it does. And News API returns a maximum of 10,000 articles per query regardless of pagination.

Response too large, or the client truncated the result

search_articles and get_latest_headlines default to 50 articles per call, wrapped in clusters, with the NLP block populated. Ask for fewer — “10 results, just title, link, date and source” — or set page_size, fields, clustering_enabled=false and include_nlp_data=false directly. See Keeping responses small.

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 Desktop is not one of these clients: its Connectors screen takes the remote URL directly (see Connect to Claude).

API reference

Full endpoint documentation and schemas

Quickstart

Make your first News API call in under five minutes

Advanced querying

Boolean operators, proximity search, and query syntax

Build search queries

Get better results from News API searches

GitHub repository

Server source code, changelog, and issues

Get started

Guides and concepts

How to

Troubleshooting

API Reference

Integrations

Libraries

Before you start

Authentication

Connect to Claude

Connect to other clients

Available tools

What you get by default

Clustered results by default

Response fields

Response size cap

Keeping responses small

Language and country codes

Quota and rate limits

Example prompts

Troubleshooting

See also

API reference

Quickstart

Advanced querying

Build search queries

GitHub repository

​Before you start

​Authentication

​Connect to Claude

​Connect to other clients

​Available tools

​What you get by default

​Clustered results by default

​Response fields

​Response size cap

​Keeping responses small

​Language and country codes

​Quota and rate limits

​Example prompts

​Troubleshooting

​See also

API reference

Quickstart

Advanced querying

Build search queries

GitHub repository

Before you start

Authentication

Connect to Claude

Connect to other clients

Available tools

What you get by default

Clustered results by default

Response fields

Response size cap

Keeping responses small

Language and country codes

Quota and rate limits

Example prompts

Troubleshooting

See also