From 7672344bbff6907607de7e207d4a7f4e06bca6bb Mon Sep 17 00:00:00 2001 From: Bohdan Denysiuk Date: Mon, 5 Oct 2026 14:25:31 +0300 Subject: [PATCH 1/3] News API MCP: agent setup page, Connectors first for Claude Desktop New page news-api/integrations/mcp-agent-setup, written for the agent doing the setup rather than the person: which path to take for the client it is running in, how to verify the key with one call before touching any config, the defaults that bite, and what each failure means. Mintlify serves it as plain markdown under the .md suffix, so "Read and follow " is the whole onboarding line. On the MCP page itself: the Claude Desktop tab now leads with the Connectors screen (one URL, no Node, no restart) and moves the mcp-remote JSON config into a fallback accordion; the "no space after the colon" rule is scoped to mcp-remote, which is where it comes from; a tip at the top carries the paste-into-your-agent line; troubleshooting and See also point at the new page. llms.txt and sitemap regenerated. Why: an agent in Claude Desktop followed the old page into the JSON config route, could not reach the protected config folder, and handed the person a Terminal script. The Connectors route needs none of that and the hosted server accepts the key in the URL. Co-Authored-By: Claude Fable 5.1 --- docs.json | 2 +- llms.txt | 1 + news-api/integrations/mcp-agent-setup.mdx | 229 ++++++++++++++++++++++ news-api/integrations/mcp.mdx | 178 +++++++++++------ sitemap.xml | 3 + 5 files changed, 348 insertions(+), 65 deletions(-) create mode 100644 news-api/integrations/mcp-agent-setup.mdx diff --git a/docs.json b/docs.json index ed8d5a7..e0d2840 100644 --- a/docs.json +++ b/docs.json @@ -313,7 +313,7 @@ }, { "group": "Integrations", - "pages": ["news-api/integrations/mcp"] + "pages": ["news-api/integrations/mcp", "news-api/integrations/mcp-agent-setup"] }, { "group": "Libraries", diff --git a/llms.txt b/llms.txt index 2cb27fb..e549d1c 100644 --- a/llms.txt +++ b/llms.txt @@ -350,6 +350,7 @@ deleted — it becomes unassigned and continues to exist. ### Integrations - [News API MCP server](https://www.newscatcherapi.com/docs/news-api/integrations/mcp): Connect News API to any MCP-compatible client for structured news search. +- [News API MCP agent setup](https://www.newscatcherapi.com/docs/news-api/integrations/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. ### Libraries diff --git a/news-api/integrations/mcp-agent-setup.mdx b/news-api/integrations/mcp-agent-setup.mdx new file mode 100644 index 0000000..e991383 --- /dev/null +++ b/news-api/integrations/mcp-agent-setup.mdx @@ -0,0 +1,229 @@ +--- +title: News API MCP agent setup +sidebarTitle: Agent setup +description: + 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](/news-api/integrations/mcp) instead. + +```text +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. + +## Step 1: verify the key before touching any config + +One request, one API call spent: + +```bash +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 +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](/news-api/integrations/mcp#connect-to-other-clients)): + +```json +{ + "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](/news-api/integrations/mcp#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 +{ + "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: "Latest +headlines about renewable energy, last 2 days, 10 results, title, link, date +and source only." + +## 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`. + +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 +{"name":"search_articles","arguments":{"q":"\"Siemens Energy\"","lang":"en","from_":"3 days ago","page_size":20,"fields":["title","link","published_date","domain_url"]}} +``` + +```json +{"name":"get_aggregation_count","arguments":{"q":"\"EU AI Act\"","from_":"30 days ago","aggregation_by":"day"}} +``` + +```json +{"name":"get_breaking_news","arguments":{"page_size":10,"fields":["title","link","domain_url"]}} +``` + +```json +{"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](/news-api/integrations/mcp). diff --git a/news-api/integrations/mcp.mdx b/news-api/integrations/mcp.mdx index 499e68f..21afef1 100644 --- a/news-api/integrations/mcp.mdx +++ b/news-api/integrations/mcp.mdx @@ -31,6 +31,18 @@ JSON arrays. The server is open source. Source code, changelog, and issue tracker: [Newscatcher/news-mcp](https://github.com/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](/news-api/integrations/mcp-agent-setup) is written for the + agent: it picks the right path for the client it is running in and verifies + the key with one call. + + ```text + 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 @@ -44,15 +56,16 @@ The MCP server resolves your API key from multiple sources, in this order (first match wins): 1. `api_token` parameter set on the tool call itself -2. `?apiToken=YOUR_KEY` URL query parameter — used by Claude.ai because its - connector UI does not support custom request headers +2. `?apiToken=YOUR_KEY` URL query parameter — used by the Claude.ai and Claude + Desktop connector UIs, which have no field for custom request headers 3. `x-api-token` HTTP request header — **recommended** for every client that supports custom headers 4. `Authorization: Bearer ` HTTP request header 5. `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 -uses option 2 (the `apiToken` query parameter) automatically. `check_health` +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. @@ -119,77 +132,103 @@ restart the client. - 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. + Claude Desktop connects to remote MCP servers through the same Connectors + screen as Claude.ai. No config file, no Node.js, no restart. - - 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. + + In Claude Desktop, open **Settings > Connectors** (under **Customize** on some versions) and click **Add custom connector**. - - Run this once to avoid permission errors when using `npx`: + + Fill in the **Add custom connector** dialog: + + * **Name**: `News API` + * **Remote MCP server URL**: - ```bash - sudo chown -R $(whoami) ~/.npm ``` - - - ```bash - npm install -g mcp-remote + https://news-mcp.newscatcherapi.com/mcp?apiToken=YOUR_NEWS_API_KEY ``` - - - - ```txt - ~/Library/Application Support/Claude/claude_desktop_config.json - ``` - - - ```txt - %APPDATA%\Claude\claude_desktop_config.json - ``` - - - - Or open it from Claude Desktop: **Settings > Developer > Edit Config**. - - - Paste the following into the file: - - ```json - { - "mcpServers": { - "news": { - "command": "npx", - "args": [ - "mcp-remote", - "https://news-mcp.newscatcherapi.com/mcp", - "--header", - "x-api-token:YOUR_NEWS_API_KEY" - ] - } - } - } - ``` + + Click **Add**. The tools are available in the next new chat, with no restart. - Write the header value as `x-api-token:YOUR_NEWS_API_KEY` with no space after the colon (see [Authentication](#authentication)). + 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. - - 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. Then ask for `get_subscription` to confirm the key itself is valid and see your remaining 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." + + 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. + + + + 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 + sudo chown -R $(whoami) ~/.npm + ``` + + + ```bash + npm install -g mcp-remote + ``` + + + + + ```txt + ~/Library/Application Support/Claude/claude_desktop_config.json + ``` + + + ```txt + %APPDATA%\Claude\claude_desktop_config.json + ``` + + + + Or open it from Claude Desktop: **Settings > Developer > Edit Config**. + + + Paste the following into the file: + + ```json + { + "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. + + + + 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. Then ask for `get_subscription` to confirm the key itself is valid and see your remaining quota. + + + + @@ -716,7 +755,9 @@ matching does differently. Restart your MCP client after updating the configuration. Most clients load - MCP tools on startup and do not detect changes until restarted. + 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. @@ -788,12 +829,21 @@ matching does differently. Use `mcp-remote` to proxy the connection. Install Node.js, then use the - `npx` configuration shown in the **Other clients** tab. + `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](#connect-to-claude)). ## See also + + One line to paste into your agent; it connects itself + https://www.newscatcherapi.com/docs/news-api/integrations/mcp + + https://www.newscatcherapi.com/docs/news-api/integrations/mcp-agent-setup + https://www.newscatcherapi.com/docs/news-api/libraries/python From 2da846ce4fb2b81afc99eac64934ca03ab7a0dd2 Mon Sep 17 00:00:00 2001 From: Bohdan Denysiuk Date: Mon, 5 Oct 2026 15:16:09 +0300 Subject: [PATCH 2/3] Make the agent setup page reachable by URL only hidden: true in the frontmatter and no docs.json entry: the page stays built and served (including its .md twin, which is what the paste line fetches) but leaves the sidebar, site search, sitemap and search engines. The See also tile on the MCP page goes too; the tip at the top with the paste line stays, since that is how a person reaches it. Co-Authored-By: Claude Fable 5.1 --- docs.json | 2 +- llms.txt | 1 - news-api/integrations/mcp-agent-setup.mdx | 3 +++ news-api/integrations/mcp.mdx | 7 ------- sitemap.xml | 3 --- 5 files changed, 4 insertions(+), 12 deletions(-) diff --git a/docs.json b/docs.json index e0d2840..ed8d5a7 100644 --- a/docs.json +++ b/docs.json @@ -313,7 +313,7 @@ }, { "group": "Integrations", - "pages": ["news-api/integrations/mcp", "news-api/integrations/mcp-agent-setup"] + "pages": ["news-api/integrations/mcp"] }, { "group": "Libraries", diff --git a/llms.txt b/llms.txt index e549d1c..2cb27fb 100644 --- a/llms.txt +++ b/llms.txt @@ -350,7 +350,6 @@ deleted — it becomes unassigned and continues to exist. ### Integrations - [News API MCP server](https://www.newscatcherapi.com/docs/news-api/integrations/mcp): Connect News API to any MCP-compatible client for structured news search. -- [News API MCP agent setup](https://www.newscatcherapi.com/docs/news-api/integrations/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. ### Libraries diff --git a/news-api/integrations/mcp-agent-setup.mdx b/news-api/integrations/mcp-agent-setup.mdx index e991383..1fd138d 100644 --- a/news-api/integrations/mcp-agent-setup.mdx +++ b/news-api/integrations/mcp-agent-setup.mdx @@ -1,6 +1,9 @@ --- title: News API MCP agent setup sidebarTitle: Agent setup +# Reachable by URL only: not in the sidebar, search, sitemap or search engines. +# It is the target of the paste-into-your-agent line, not a page to browse to. +hidden: true description: 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 diff --git a/news-api/integrations/mcp.mdx b/news-api/integrations/mcp.mdx index 21afef1..a6351fe 100644 --- a/news-api/integrations/mcp.mdx +++ b/news-api/integrations/mcp.mdx @@ -837,13 +837,6 @@ matching does differently. ## See also - - One line to paste into your agent; it connects itself - https://www.newscatcherapi.com/docs/news-api/integrations/mcp - - https://www.newscatcherapi.com/docs/news-api/integrations/mcp-agent-setup - https://www.newscatcherapi.com/docs/news-api/libraries/python From 200c3c6984368cfb2d77beababdd08c2d05992c6 Mon Sep 17 00:00:00 2001 From: Maksym Sugonyaka <44269402+Kizy625@users.noreply.github.com> Date: Mon, 5 Oct 2026 14:26:44 +0200 Subject: [PATCH 3/3] Update mcp.mdx --- news-api/integrations/mcp.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/news-api/integrations/mcp.mdx b/news-api/integrations/mcp.mdx index a6351fe..088928f 100644 --- a/news-api/integrations/mcp.mdx +++ b/news-api/integrations/mcp.mdx @@ -56,8 +56,7 @@ The MCP server resolves your API key from multiple sources, in this order (first match wins): 1. `api_token` parameter set on the tool call itself -2. `?apiToken=YOUR_KEY` URL query parameter — used by the Claude.ai and Claude - Desktop connector UIs, which have no field for custom request headers +2. `?apiToken=YOUR_KEY` URL query parameter — used by some Agents which have no field for custom request headers 3. `x-api-token` HTTP request header — **recommended** for every client that supports custom headers 4. `Authorization: Bearer ` HTTP request header