News API MCP: agent setup page

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).