--- name: newsmcp description: | NewsMCP gives agents live news as clustered story events instead of a flat article list: outlets covering the same story collapse into one event with an article_count, so you read one result instead of thirty near-duplicates. Keyless to start, no signup, full commercial licence. Connect over MCP at https://mcp.newsmcp.com/mcp. Read Path D before writing a query — bare multi-word terms get an implicit AND and will return 422. --- # NewsMCP Live news search built for context windows. One tool does the work today: `search_news`. Results are **story events**, not articles — every outlet that covered a story is grouped into a single event, so a busy story arrives as one object with `article_count: 125` rather than 125 rows. - **Endpoint:** `https://mcp.newsmcp.com/mcp` - **Transport:** streamable HTTP, **stateless** — no `initialize` handshake and no session id needed; you can POST `tools/call` directly. - **Auth:** none required. A key raises the limits (Path E). - **Licence:** full commercial use on every tier, keyless included. ## Pick your path | You want to | Go to | |---|---| | Search news right now, without a key | **Path A** | | Add NewsMCP to an MCP client or an app | **Path B** | | Know exactly what comes back | **Path C** | | Write a query that doesn't fail | **Path D** | | Higher limits, longer archive, more tools | **Path E** | --- ## Path A — Search now, keyless Use this when you need news during your work and have no credentials. Nothing to install. POST JSON-RPC to the endpoint: ```bash curl -s -X POST https://mcp.newsmcp.com/mcp \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{ "name":"search_news", "arguments":{"q":"\"OpenAI\"","event_size":3}}}' ``` The response is `text/event-stream`; the payload is on the `data:` line. It is a markdown digest by default — add `"response_format":"json"` to the arguments if you intend to parse it. **`response_format` is an MCP-only parameter** (see Path C). **Prefer plain REST?** There is a public REST surface with the same data and no JSON-RPC envelope — simpler for scripts, and it always returns JSON: ```bash curl -s -X POST https://api.newsmcp.com/v0/search_news \ -H 'Content-Type: application/json' \ -d '{"q":"\"OpenAI\"","event_size":3}' ``` Do **not** send `response_format` here — REST rejects unknown fields with `499 unexpected_field`. It has no output-shape option because JSON is the only shape it returns. `GET https://api.newsmcp.com/health` for liveness. Full spec: `https://api.newsmcp.com/docs/openapi.json` Keyless envelope: **~20 calls/hour**, lookback **~24 hours**, **≤8 events** per call, **English only**. Over-asking is **not** an error — the search runs narrowed and the response carries `keyless_notices` telling you what was adjusted. If you get rate-limited, back off rather than retrying; the quota is per client IP. **Datacenter and cloud IPs are blocked when keyless.** If you're calling from CI, a serverless function, or a VPS and the connection is refused, that's why — you need a token, not a retry. ## Path B — Connect a client or an app **Claude Code** ```bash claude mcp add --transport http newsmcp https://mcp.newsmcp.com/mcp ``` **Claude Desktop / Cursor** — add to the MCP config, then restart: ```json { "mcpServers": { "newsmcp": { "url": "https://mcp.newsmcp.com/mcp" } } } ``` **Any other MCP client** — point it at `https://mcp.newsmcp.com/mcp` with transport `http` (streamable HTTP). No auth header needed to start. To use a key, send it as: ``` x-api-token: ``` Note: `Authorization: Bearer` and `x-api-key` are **silently ignored** — they return 200 with keyless results, so a misconfigured header looks like it works while quietly giving you the free tier. Use `x-api-token`. ## Path C — What comes back **Over MCP** you pick the output shape with `response_format`: | Value | You get | |---|---| | `markdown` *(default)* | a readable digest — cheapest to reason over, best for chat | | `text` | plain `title / link / date / summary` lines | | `json` | the structured payload below — use this when you're parsing | If you are going to parse the result, **pass `response_format: "json"`**. Don't regex the markdown. **Over REST** there is no such parameter — the response is always the JSON below. Sending `response_format` to `/v0/search_news` fails with `499 unexpected_field`, because the schema rejects unknown fields. ```json { "status": "ok", "events_count": 41, "events": [ { "event_id": "1847a4931a6c8002", "article_count": 125, "event_score": 5.85, "articles": [ { "title": "White House summons AI giants after ChatGPT-style models go rogue", "summary": "Meta, Anthropic, OpenAI and Google have been invited to the White House…", "link": "https://www.independent.co.uk/tech/white-house-ai-safety-testing-openai-b3026999.html", "published_date": "2026-08-04T08:21:26", "theme": ["Tech", "Politics"], "sentiment": "Negative" } ] } ] } ``` - `events_count` is how many clusters were found **before** the `event_size` cap. - `article_count` is how many articles were grouped into this story — a useful salience signal. It is usually **larger than the number of `articles` returned**, which is capped at **3 citations per event**. - `event_score` is a mean match score. Comparable between events **in the same response only** — never across searches, and not a strict global ranking. - **`event_id` is not durable.** It is derived from cluster membership, so the same story gets a different id on a later search. Don't store it or use it as a key. - `summary` is NewsMCP's own summary, and can be `null`. Article body text is **never** returned — follow `link` for the full piece. - `keyless_notices` appears when your request was narrowed for lack of a token (see Path E). Read it rather than guessing why results look thin. - There is **no pagination** — one page of events per search. Go wider by raising `event_size` or splitting the time range across calls. ## Path D — Writing a query (read before your first call) `q` is required. **The API inserts an implicit `AND` between bare, space-separated words.** This is the single most common failure: ``` q=AI OR artificial intelligence → parsed as "AI OR artificial AND intelligence" → 422 q=AI OR "artificial intelligence" → correct ``` Rules: - **Always quote multi-word phrases** when any boolean operator is present. - Exact phrase: `q="Tim Cook"`. Unquoted `Tim Cook` means `Tim AND Cook`. - Booleans: `AND`, `OR`, `NOT`, with parentheses — `(bitcoin OR cryptocurrency) AND (investment OR trading)`. - Require/exclude shorthand: `+term`, `-term`. - Wildcards `*` and `?` may not lead a term. `technolog*` is fine, `*intelligence` is not. `q="*"` alone matches everything — use it for filter-only searches. - Proximity: `NEAR("phrase one", "phrase two", distance, in_order)` — max 4 words per phrase, max 100 distance. - **Never valid anywhere in `q`:** `[ ] / \ : ^` - On a 422, fix the quoting or parentheses and retry. Don't retry unchanged. Put filters in their own parameters, not in `q`: `lang` (ISO 639-1), `countries` (ISO 3166-1 alpha-2), `sources` (domains, e.g. `["reuters.com"]`), `source_groups` (e.g. `"Top 10 English Finance US"`), `theme`, `sentiment`, `from_`/`to_` (ISO 8601 or natural language like `7 days ago`), `sort_by` (`relevancy` | `date` | `-date`), `search_in` (`title` | `title_content`), `event_size`, `grouping`. Worked examples: ``` q="OpenAI" company coverage q="*" source_groups="Top 10 English" sort_by="-date" what broke in the last hours q=fraud OR bribery OR "money laundering" theme=["Finance"] sentiment=["negative"] q=AI OR "artificial intelligence" theme=["Tech"] topic tracking ``` ## Path E — Limits, keys, and the rest of the toolset | | Keyless | With an API key | |---|---|---| | Lookback | ~24 hours | ~30 days | | Events per call | ≤ 8 | ≤ 100 | | Rate limit | ~20 calls/hour | higher | | Commercial use | yes | yes | Tools: - `search_news` — **live** - `check_health` — live; only for confirming the API is up - `get_company_news`, `get_breaking` — **not yet shipped** - `search_local_news`, `monitors` — Enterprise Self-serve accounts and keys are not open yet (soft launch). Higher limits and the Enterprise tools go through the sign-in flow: https://newsmcp.com/signin ## If something fails - **422** — a `q` syntax problem. Re-read Path D; quote your phrases. - **429** — keyless rate limit, shared per IP. Back off; get a key for headroom. - **Empty `events`** — the keyless 24-hour window is short. Broaden with `OR`, drop restrictive filters, or widen `from_` with a key. - **Results look like press-release spam** — some clusters are built from PR-wire syndication. Constrain with `sources` or `source_groups` for editorial outlets. NewsMCP is the light, read-only surface for ad-hoc agent runs. When news drives a production workflow — full archive, more filters and fields, SLAs — that is NewsCatcher: https://www.newscatcherapi.com