diff --git a/news-api/integrations/mcp-agent-setup.mdx b/news-api/integrations/mcp-agent-setup.mdx
new file mode 100644
index 0000000..1fd138d
--- /dev/null
+++ b/news-api/integrations/mcp-agent-setup.mdx
@@ -0,0 +1,232 @@
+---
+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
+ 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..088928f 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,15 @@ 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 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
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 +131,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:
+
+ Click **Add**. The tools are available in the next new chat, with no restart.
- ```json
- {
- "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)).
+ 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 +754,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,7 +828,9 @@ 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