newsmcp.com

Everything here returns **synthesized story events** — one entry per real-world story, each with a generated headline, one-liner, abstract, key actors, industry / event-type labels, corroboration counts, and source links. It is not a flat article list, and there is no per-article search. ## Pick the tool by what is being asked | The request | The tool | |---|---| | a topic, a filter, or "what's happening" | `news` | | a named company, person, place, or organisation | `news` with `subject=` | | more detail on a story already seen | `get_story` | | "is this true?" / "how widely reported?" | `check_coverage` | | how much budget is left | `check_limits` | For a name, use `subject=` rather than putting it in `q`. It quotes the name so it matches as a phrase and widens the window to 30 days, which is the difference between finding a company and finding nothing: `q="Bank of America"` unquoted ANDs three common words and returns "India Now Asia's Least Preferred Stock Market" first, and `q="Monzo"` over the default 24 hours returns nothing at all. `subject` and `q` combine, so `subject="Tesla", q="recall OR lawsuit"` reads as expected. Leave `sort` alone unless the user asked for an ordering. The API then picks `relevance` when there is a query and `newsrooms` when there is not — forcing `newsrooms` on a keyword search ranks by story size instead of match quality. `check_coverage` answers a different question from all of them: it reports how many INDEPENDENT newsrooms carried a claim, separately from how many domains reprinted it. Reach for it whenever the user is asking whether something is real rather than what happened. Nothing is required. A bare `news()` call returns the most-corroborated stories of the last 24 hours, so never refuse for lack of parameters — call it and refine after. Pass a token via the `api_key` tool argument, an inbound `x-api-key` or `Authorization: Bearer` header, the MCP URL (`?apiKey=…`), or env `NEWSMCP_API_KEY`. Use `check_health` only to verify the API is up — it returns no news. Some tools rewrite a query before sending it, because the index removes function words when it is built but the query still requires every word given — so `q="what is happening with Disney"` matches nothing. Any `Note:` line in a result explains what was adjusted or narrowed. **Relay those notes**; never present a narrowed result as complete. ## Limits — know these before you plan a sequence of calls | | Keyless | With a key | |----------------------------|------------|-----------------------| | `from_` lookback | 7 days | per plan (14 days free_tier)| | Calls per hour | 20 | per plan (50 free_tier) | | `limit` (stories per call) | 20 | per plan (50 free_tier) | | Requests in flight at once | 1 | 1 | **Call `check_limits` rather than trusting that table.** Every keyed number is per-plan config that changes without a release.`check_limits` reports the live ceilings *and* how much of the hourly budget is left, and costs nothing: it is exempt from metering, so checking never consumes a call, a slot or a credit. Use it before planning a batch of calls, and after any limit error instead of guessing what was hit. **Call one at a time.** A keyed caller gets exactly ONE request in flight; a second before the first returns is refused with a 429. So never fan out: "compare banking, energy and semiconductors" is three calls in sequence, or better, one call with `sector="banking,energy_utilities,semiconductors"`. **Budget your calls.** The hourly count is the scarce resource, and every page is one call. Set the filters you need on the first attempt instead of probing one at a time. Keyless callers share the 20/hour budget per network address, so it may already be partly spent by someone else. **Over-limit behaves differently per tier.** Keyless: the call still succeeds, narrowed to the allowance, with a note in the response saying what was adjusted — relay that note rather than presenting a narrowed result as complete. With a key: the call is rejected with a validation error naming the parameter and its maximum. ## CRITICAL: `response_format` (default `markdown` — looks good out of the box) Hosts only see `content[0].text`. Default is **`markdown`** (readable digest of every story returned). Omit the param when the user does not ask for a format. When the user *does* ask, you MUST pass the matching value: | User says | Pass | |---|---| | no format / "find news" / "what happened" | omit or `response_format="markdown"` | | "text", "plain text", "as text" | `response_format="text"` | | "markdown", "as markdown", "md", "formatted digest" | `response_format="markdown"` | | "json", "as json", "raw json", "full payload", "full response" | `response_format="json"` | Never answer that you cannot produce text/markdown/JSON without first calling with the matching `response_format`. Do not post-process one format into another when the tool can return it. ## Query syntax (`q` parameter) `q` is **optional** — omit it entirely for a filter-only digest (e.g. "top banking stories today" is `sector="banking"` with no `q`). When you do pass one: - `q` is matched against the story's headline, one-liner, abstract, and actor names — not against full article bodies. Keep it to the words that would appear in a headline. - **Always quote multi-word phrases.** The API auto-inserts `AND` between bare, unquoted, space-separated words, so `q="AI OR artificial intelligence"` is parsed as `AI OR artificial AND intelligence` and is rejected with a `422`. Write `q='AI OR "artificial intelligence"'`, or parenthesize each side. - Exact phrase: wrap it in literal double-quote characters, e.g. `q='"Tim Cook"'`. Without quotes, `q='Tim Cook'` means `Tim AND Cook`. - Boolean: `AND`, `OR`, `NOT`, with parentheses to control evaluation order, e.g. `(bitcoin OR cryptocurrency) AND (investment OR trading)`. - Prefix shorthand: `+term` to require, `-term` to exclude. - Wildcards: `*` (any length) and `?` (single character); neither may lead a term (`*intelligence` is invalid, `technolog*` is fine). - `NEAR()` and `MULTIPLE()` are **not** supported here. - Forbidden characters, never valid anywhere in `q`: `[ ] / \ : ^`. - On a `422`, fix the quoting/parentheses and retry. If results look wrong: too broad → add `AND` terms or `NOT` exclusions; too few → widen `from_`, drop a filter, or use `OR`. Good: `"renewable energy" OR solar` · `AI OR "artificial intelligence"` · `(OpenAI OR Anthropic) AND model` · `"Tim Cook"` · `Tesla NOT "Elon Musk"` Bad (422): `renewable energy OR solar` · `AI OR artificial intelligence` ## How to set each news field Map the user's request into these parameters (omit optional ones you do not need): - **q**: query built with the rules above, or omitted for a filter-only digest. - **event_id**: fetch ONE story by an id from an earlier result. Every other filter is ignored. A story folded into a more complete one answers `404` naming its replacement id — fetch that id instead. - **event_type**: what KIND of event it is, as an exact `family.leaf` value, comma-separated for OR (`deals.merger_acquisition,funding.venture_funding_round`). A bare family (`deals`) is invalid and unknown values are rejected by name — the tool's own parameter description carries all 59 leaves across 21 families, so read it rather than guessing. `unclassifiable` is itself a valid value. - **content_type**: article form — `news_report`, `press_release`, `explainer`, `commentary`, `analysis`, `opinion`, `interview`, `human_interest`, `service_info`, `obituary`. Comma-separated for OR. - **sector**: industry, comma-separated for OR, e.g. `banking,semiconductors`. - **min_articles** / **min_sources** / **min_newsrooms**: three coverage floors, loosest to strictest. `min_articles` counts every article including duplicates (a rough size floor); `min_sources` counts distinct publisher domains with mirrors included (breadth of pickup); `min_newsrooms` counts outlets that reported *independently* — the strongest "is this real" filter, and the one to use when the user wants to exclude a story one outlet ran and everyone else reprinted. `min_newsrooms=3` for "well-corroborated only". - **min_confidence**: labeling-confidence floor 0–1; unscored stories are excluded. - **from_** / **to_**: window over when the story BEGAN, not article publish dates. ISO 8601 (`2026-07-01T00:00:00`) or natural language (`3 days ago`). Default: last 24 hours — widen `from_` first when a story that should exist comes back empty. - **enriched_only**: `true` (default) hides brand-new stories with no headline/summary yet. - **sort**: `newsrooms` (default, most corroborated), `trending` (corroboration weighted by recency — use for "what's big right now"), `relevance` (best match, REQUIRES `q`), `last_seen`, `first_seen`, `size`, `source_count`, `confidence`. **order**: `desc` (default) or `asc`. - **limit**: how many stories to return, capped per tier. A flat ceiling, not a page size — there is no paging past it, so this is the most a single call can surface. - **verbosity**: affects ONLY the source-link list — headline, summary, actors, and labels are always present. `compact` (none), `standard` (default, up to 3), `full` (all, uncapped). Prefer `standard`; `full` on a large `limit` returns a very long digest. - **response_format**: see the table above. Filters combine with **AND** — `sector=banking` plus `min_newsrooms=3` means banking stories with at least 3 independent outlets. `event_type`, `content_type`, and `sector` each take several comma-separated values combined with **OR**. ## Worked examples | The user says | The call | |---|---| | "what's trending in funding rounds right now" | `event_type="funding.venture_funding_round", sort="trending"` | | "quick summary of what's happening with Acme Corp" | `q='"Acme Corp"'` | | "well-corroborated cybersecurity stories, 3+ independent outlets" | `event_type="security.cyberattack", min_newsrooms=3` | | "banking news, only confidently-labeled" | `sector="banking", min_confidence=0.7` | | "just the analysis pieces on the merger, not straight news" | `q="merger", content_type="analysis"` | | "top 20 stories today" | `limit=20` | | "show me every source link" | `verbosity="full"` | | "pull that story up again" | `event_id="evt_…"` from the earlier result | | "what happened last week in semiconductors" | `sector="semiconductors", from_="7 days ago"` | ## When a call comes back empty or wrong Loosen one thing at a time, in this order: 1. **Widen `from_`.** The default window is only 24 hours and it bounds when the story *started*, so an ongoing story that began earlier is invisible. This is the single most common cause of "but I know that story exists". 2. **Lower a floor** — `min_newsrooms`, `min_sources`, `min_articles`, `min_confidence`. 3. **Pass `enriched_only=False`** if the story broke minutes ago. 4. **Drop a label filter.** `event_type` / `content_type` / `sector` are exact-match; a story can be labeled differently than expected. 5. Only then simplify `q` — or drop it and rely on filters. ## What each error means and what to do - **429 with `retry_after_seconds` — the hourly budget is spent.** Further calls are blocked until the window resets. **Do not retry in a loop and do not keep calling with different parameters** — every attempt is refused and, keyless, counts against the same shared budget. `check_limits` will confirm the wait without spending anything. Tell the user how long it is and that a key (or a higher plan) raises the ceiling; only retry if the wait is short and they ask. - **429 without it ("Max API Requests Concurrency Reached") — you called in parallel.** The cap is one request in flight, and nothing was spent from the hourly budget. Wait for the previous call to finish and retry this one; do not treat it as a quota problem. - **499 plan_limit.** A value is beyond this caller's plan and the message names the field and its maximum. Re-issue once with that value clamped. If the message does not name a number, `check_limits` will. - **400 invalid_filter_value.** An `event_type`/`content_type`/`sector` value is not in the taxonomy. The message lists every accepted value — pick the closest one from that list and retry once. Never retry unchanged. - **422 validation error.** It names the parameter and the allowed maximum — usually `limit` or a `from_` beyond the plan's history. Re-issue the call ONCE with that value clamped to the stated maximum; never retry unchanged. `from_` later than `to_` lands here too. - **404 on `event_id`.** If it names a replacement id, the story was folded into a larger one — fetch that id. Otherwise the id never existed: search again for a current one. - **408 timeout.** Retry once, then narrow the window or lower `limit`. - **503 service_overloaded.** The backing search index is overloaded, not a bad request. Retry once after a few seconds; if it repeats, stop and report the outage rather than looping. - **A notice in a successful response.** Keyless narrowing happened. Say so. Do not invent unsupported operators, and do not put filters inside `q` that belong in a dedicated field (put the industry in `sector`, not in `q`).