> ## Documentation Index > Fetch the complete documentation index at: https://newscatcherinc-docs.mintlify.site/docs/llms.txt > Use this file to discover all available pages before exploring further. # News API MCP server > Connect News API to any MCP-compatible client for structured news search. 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](https://github.com/Newscatcher/news-mcp). ## Before you start * News API key from [platform.newscatcherapi.com](https://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, in this order (first match wins): 1. `?apiToken=YOUR_KEY` URL query parameter — used by Claude.ai because its connector UI does not support custom request headers 2. `x-api-token` HTTP request header — **recommended** for every client that supports custom headers 3. `Authorization: Bearer ` HTTP request header 4. `NEWS_API_KEY` environment variable on the server host Most client configurations use option 2 (the `x-api-token` header). Claude.ai uses option 1 (the `apiToken` query parameter) automatically. `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. ## Connect to Claude Go to [claude.ai/customize/connectors](https://claude.ai/customize/connectors). Click **+** and select **Add custom connector**. 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 ``` Click **Add**. Verify that News API appears under **Web** in your connectors list. 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: "Get the latest headlines about renewable energy, limit 10". 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. Run `node --version` to check if Node.js is installed. If the command fails, download and install it from [nodejs.org](https://nodejs.org) before continuing. Run this once to avoid permission errors when using `npx`: ```bash theme={null} sudo chown -R $(whoami) ~/.npm ``` ```bash theme={null} npm install -g mcp-remote ``` ```txt theme={null} ~/Library/Application Support/Claude/claude_desktop_config.json ``` ```txt theme={null} %APPDATA%\Claude\claude_desktop_config.json ``` Or open it from Claude Desktop: **Settings > Developer > Edit Config**. Paste the following into the file: ```json theme={null} { "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](#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. Save the file and quit Claude Desktop completely, then relaunch it. Claude Desktop loads MCP tools on startup. 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. Run in your terminal: ```bash theme={null} 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](#authentication)). Run `claude mcp list` and confirm `news` is listed, or type `/mcp` inside a Claude Code session to see it marked as connected. 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: "Get the latest headlines about renewable energy, limit 10". ## Connect to other clients [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=news\&config=eyJuYW1lIjoibmV3cyIsInR5cGUiOiJodHRwIiwidXJsIjoiaHR0cHM6Ly9uZXdzLW1jcC5uZXdzY2F0Y2hlcmFwaS5jb20vbWNwP2FwaVRva2VuPVlPVVJfTkVXU19BUElfS0VZIn0=) Or add to `~/.cursor/mcp.json` manually: ```json theme={null} { "mcpServers": { "news": { "type": "http", "url": "https://news-mcp.newscatcherapi.com/mcp?apiToken=YOUR_NEWS_API_KEY" } } } ``` Restart Cursor after saving. [![Install in VS Code](https://img.shields.io/badge/Install_in-VS_Code-0098FF?style=flat-square\&logo=visualstudiocode\&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=news\&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fnews-mcp.newscatcherapi.com%2Fmcp%22%7D) Or add to `.vscode/mcp.json` in your project root manually: ```json theme={null} { "servers": { "news": { "type": "http", "url": "https://news-mcp.newscatcherapi.com/mcp?apiToken=YOUR_NEWS_API_KEY" } } } ``` Restart VS Code after saving. Add to `~/.codeium/windsurf/mcp_config.json`: ```json theme={null} { "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`): ```json theme={null} { "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: ```json theme={null} { "news": { "url": "https://news-mcp.newscatcherapi.com/mcp", "headers": { "x-api-token": "YOUR_NEWS_API_KEY" } } } ``` Add to `~/.gemini/settings.json`: ```json theme={null} { "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: ```json theme={null} { "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: ```json theme={null} { "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: ```json theme={null} { "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](#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](/docs/news-api/api-reference/overview). | 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, and remaining calls | | `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. ## 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: ```text theme={null} 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. 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: ```text theme={null} 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: ```json theme={null} { "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. ## Troubleshooting Restart your MCP client after updating the configuration. Most clients load MCP tools on startup and do not detect changes until restarted. Verify your API key is valid by calling an authenticated endpoint: ```bash theme={null} 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 it at [newscatcherapi.com/news-api](https://www.newscatcherapi.com/news-api). 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: ...`. Check the returned string for the specific reason. 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](#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. Use `mcp-remote` to proxy the connection. Install Node.js, then use the `npx` configuration shown in the **Other clients** tab. ## See also Full endpoint documentation and schemas Make your first News API call in under five minutes Boolean operators, proximity search, and query syntax Get better results from News API searches Server source code, changelog, and issues