> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# News API MCP agent setup

> Written for the AI agent doing the setup. Hand it this page and it connects the News API MCP server to whatever client it is running in, then verifies the key with one call.

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](/docs/news-api/integrations/mcp.md) instead.

```text theme={null}
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](https://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:

1. `api_token` argument on a tool call
2. `?apiToken=YOUR_NEWS_API_KEY` on the URL, for clients with no headers field
3. `x-api-token: YOUR_NEWS_API_KEY` request header, preferred where headers are possible
4. `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:

```bash theme={null}
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:

1. Open **Settings > Connectors** (on the web:
   [claude.ai/customize/connectors](https://claude.ai/customize/connectors)) and
   click **Add custom connector**.
2. Name it `News API`. Remote MCP server URL:
   `https://news-mcp.newscatcherapi.com/mcp?apiToken=YOUR_NEWS_API_KEY`
3. 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

```bash theme={null}
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](/docs/news-api/integrations/mcp.md#connect-to-other-clients)):

```json theme={null}
{
  "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](/docs/news-api/integrations/mcp.md#connect-to-other-clients) 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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

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

```json theme={null}
{"name":"get_aggregation_count","arguments":{"q":"\"EU AI Act\"","from_":"30 days ago","aggregation_by":"day"}}
```

```json theme={null}
{"name":"get_breaking_news","arguments":{"page_size":10,"fields":["title","link","domain_url"]}}
```

```json theme={null}
{"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](/docs/news-api/integrations/mcp.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.