News API MCP agent setup

This page is instructions for an agent. If you are a person, paste the line below into Claude, Cursor, or any agent with web access and let it do the rest. If you would rather set things up by hand, use the MCP server page instead.

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

What this is

NewsCatcher News API as MCP tools. Full text and boolean search over 140,000+ news sources with years of history, latest headlines, breaking news, author search, article lookup by URL, source browsing, article counts over time, and plan and quota info. Nine tools, one remote server, one API key.

Endpoint: https://news-mcp.newscatcherapi.com/mcp
Transport: streamable HTTP, stateless. No initialize handshake is needed; a client can POST tools/call directly.
Auth: a News API key. Every tool except check_health needs one.
Tools: search_articles, get_latest_headlines, get_breaking_news, search_by_author, search_by_link, list_sources, get_aggregation_count, get_subscription, check_health.

Step 0: the key

A News API key is a 32 character string. The person gets one at platform.newscatcherapi.com/newsapi; the trial key works. If a key was pasted into the conversation, use it. If it was not, ask for it before doing anything else. Without a key there is nothing to set up. The server reads the key from any of these, highest precedence first:

api_token argument on a tool call
?apiToken=YOUR_NEWS_API_KEY on the URL, for clients with no headers field
x-api-token: YOUR_NEWS_API_KEY request header, preferred where headers are possible
Authorization: Bearer YOUR_NEWS_API_KEY header

All four authenticate on the hosted server. Never send both a URL token and a header: the URL token wins for the whole session, so a rotated key in the header will silently not take effect. The header is x-api-token. Not x-api-key, which belongs to a different NewsCatcher product and is ignored here. About the key in this message. The platform’s copy button puts the key in the setup line on purpose; that is the supported way to hand it to you, and putting it in a connector URL or a config file is the documented method for every client below. Keys are not something the person can rotate: a trial key expires on its own when the trial ends, and replacing any key goes through NewsCatcher support. The useful thing to do with it is put it in the client config and nowhere else.

Step 1: verify the key before touching any config

One request, one API call spent:

curl -s -X POST https://news-mcp.newscatcherapi.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'x-api-token: YOUR_NEWS_API_KEY' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_subscription","arguments":{}}}'

The reply is text/event-stream; the JSON sits on the data: line. A valid key returns the plan, remaining calls, concurrency limit and how far back it can search. API Error (401): Invalid api key means the key is wrong or truncated. API token is required means the header did not arrive. No shell access? Skip this step and verify in Step 3 instead.

Step 2: connect. Pick exactly one path.

Which client am I in? If you are a chat assistant with no file system and no shell, you are in Claude.ai or Claude Desktop. Take path A and hand the person the URL. Do not try to edit config files, and do not suggest mcp-remote, npx, Node.js or an app restart. None of that is needed there.

A. Claude.ai and Claude Desktop

Both use the same Connectors screen. No files, no restart, about 30 seconds. Give the person these three lines:

Open Settings > Connectors (on the web: claude.ai/customize/connectors) and click Add custom connector.
Name it News API. Remote MCP server URL: https://news-mcp.newscatcherapi.com/mcp?apiToken=YOUR_NEWS_API_KEY
Click Add. The tools are live in the next new chat.

If a News API or NewsCatcher News connector is already in that list, it is already set up. Go to Step 3.

B. Claude Code

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

claude mcp list should show news as connected.

C. Cursor

Add to ~/.cursor/mcp.json (or use the one-click install link on the MCP server page):

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

D. VS Code, Windsurf, Zed, Warp, Gemini CLI, Roo Code, anything else

Same shape as C: type: http, the URL, and a headers object with x-api-token. VS Code can prompt for the key instead of storing it (a promptString input; the MCP server page has the block). Restart the client if the tools do not appear.

E. Last resort: a client with no remote MCP support

Use mcp-remote as a stdio proxy:

{
  "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 on the first colon, so keep it as x-api-token:YOUR_NEWS_API_KEY with no space. This path needs Node.js and a client restart. Claude Desktop does not need it; use path A.

Step 3: confirm from inside the client

Ask for check_health (free, proves the connection), then get_subscription (proves the key, shows quota). Then one real query that names a time window, a result count and the fields wanted, so the response stays small: “Most recent articles about renewable energy, last 2 days, 10 results, title, link, date and source only.” A topic means a keyword, and only search_articles takes one (q). get_latest_headlines has no q and rejects it with a validation error; it filters by lang, countries, theme and sources over a when window. The query above as a call:

{
  "name": "search_articles",
  "arguments": {
    "q": "\"renewable energy\"",
    "from_": "2 days ago",
    "sort_by": "date",
    "page_size": 10,
    "fields": ["title", "link", "published_date", "domain_url"]
  }
}

Defaults that decide what comes back

Time window: the last 7 days. Anything older needs explicit from_ and to_ (ISO dates or phrases like "30 days ago"). get_subscription says how far back the plan allows.
Sort: relevancy. “Latest” or “most recent” needs sort_by: "date".
Clustering: on for search_articles and get_latest_headlines. One row per story with cluster_size; pass clustering_enabled: false for every article.
Fields: a lean nine (title, link, published_date, domain_url, author, language, nlp.summary, nlp.translation_summary, nlp.theme). Pass fields: [...] to pick, fields: [] for everything. Full article content is left out of the default set on purpose.
Page size 50, hard cap 10,000 articles per query, 250 KB per response. An oversized reply comes back trimmed with response_capped metadata saying how many articles were dropped.
Language codes are two letters (en, de; Chinese is cn or tw). Country codes are ISO alpha-2 (US, GB, never UK).

Query rules

q is boolean full text: AND, OR, NOT, quotes for phrases, parentheses, * wildcard, NEAR. Quote multi word names ("Tim Cook"). Filters are separate parameters, not query syntax: lang, countries, search_in (title, summary, content), theme, is_headline, sort_by, page_size. lang, countries, search_in, theme and fields are lists, even for one value: "lang": ["en"], not "lang": "en". A bare string is rejected with a validation error before the call reaches the API. Before pulling many pages, call get_aggregation_count first. It returns daily or hourly article counts for the query and no articles, so you can see the volume and narrow the window before spending calls.

When something fails

API token is required: the key never reached the server. In Claude.ai or Claude Desktop the URL is missing ?apiToken=; elsewhere the header name is wrong (it is x-api-token, not x-api-key).
401 Invalid api key: wrong or truncated key, or an old ?apiToken= still in the URL overriding a new header.
Empty results: the 7 day default window. Widen from_ first, then loosen q.
429: plan concurrency limit; get_subscription shows concurrent_calls. Back off and retry.
Tools missing in the client: path A is live in a new chat with no restart; every other path needs a client restart.
response_capped in metadata: lower page_size, pass a fields list, or drop NLP fields.

Recipes

{"name":"search_articles","arguments":{"q":"\"Siemens Energy\"","lang":["en"],"from_":"3 days ago","page_size":20,"fields":["title","link","published_date","domain_url"]}}

{"name":"get_aggregation_count","arguments":{"q":"\"EU AI Act\"","from_":"30 days ago","aggregation_by":"day"}}

{"name":"get_breaking_news","arguments":{"page_size":10,"fields":["title","link","domain_url"]}}

{"name":"search_by_author","arguments":{"author_name":"Kara Swisher","from_":"90 days ago"}}

Full reference, every client config and every parameter: News API MCP server.

Get started

Guides and concepts

How to

Troubleshooting

API Reference

Integrations

Libraries

News API MCP agent setup

What this is

Step 0: the key

Step 1: verify the key before touching any config

Step 2: connect. Pick exactly one path.

A. Claude.ai and Claude Desktop

B. Claude Code

C. Cursor

D. VS Code, Windsurf, Zed, Warp, Gemini CLI, Roo Code, anything else

E. Last resort: a client with no remote MCP support

Step 3: confirm from inside the client

Defaults that decide what comes back

Query rules

When something fails

Recipes

​What this is

​Step 0: the key

​Step 1: verify the key before touching any config

​Step 2: connect. Pick exactly one path.

​A. Claude.ai and Claude Desktop

​B. Claude Code

​C. Cursor

​D. VS Code, Windsurf, Zed, Warp, Gemini CLI, Roo Code, anything else

​E. Last resort: a client with no remote MCP support

​Step 3: confirm from inside the client

​Defaults that decide what comes back

​Query rules

​When something fails

​Recipes

What this is

Step 0: the key

Step 1: verify the key before touching any config

Step 2: connect. Pick exactly one path.

A. Claude.ai and Claude Desktop

B. Claude Code

C. Cursor

D. VS Code, Windsurf, Zed, Warp, Gemini CLI, Roo Code, anything else

E. Last resort: a client with no remote MCP support

Step 3: confirm from inside the client

Defaults that decide what comes back

Query rules

When something fails

Recipes