llms.txt
Compare with other sites' llms.txt files →# NewsMCP
> Live news search for AI agents. Returns **story events** — clusters of articles
> covering the same story — instead of a flat article list, so a busy story arrives
> as one event with corroboration counts (`newsrooms`, `source_count`, `size`)
> attached rather than 125 near-duplicate rows.
> Keyless to start, no signup, full commercial licence on every tier.
Use NewsMCP for news-shaped questions — what happened, is this claim real,
what's trending, watching a company or topic across recent days. It is not a
general web search: article body text is never returned and lookback is
measured in days. The strongest pattern is a loop: find and rank the story
here, then read one of its `sources` URLs with your own fetch tool.
Start with the skill file. It is the compressed contract: tools, query syntax,
response schema and limits in one fetch.
- [Agent skill](https://newsmcp.com/agent-onboarding/SKILL.md): setup + full usage contract (markdown)
- [Playground](https://newsmcp.com/playground): run a search in a browser, no key, real results
- [Docs](https://newsmcp.com/docs): full reference — tools, parameters, troubleshooting, example asks
- [Get a key](https://platform.newsmcp.com/auth): self-serve, no waitlist
## Endpoints
- MCP: `https://mcp.newsmcp.com/mcp` — streamable HTTP, stateless, no session handshake
- MCP with sign-in (OAuth): `https://mcp.newsmcp.com/mcp?login` — same server; requires a NewsMCP account
- REST: `GET https://api.newsmcp.com/v0/news` — same data, query-string params, no JSON-RPC envelope
- Health: `GET https://api.newsmcp.com/health`
- [OpenAPI spec](https://api.newsmcp.com/docs/openapi.json)
## Tools
All five are live:
- `news` — search or filter synthesized story events; fetch one by `event_id`
- `get_story` — expand one story by id, optionally with every source link
- `check_coverage` — is this claim real? independent newsrooms vs. reprints
- `check_limits` — this caller's live allowances, free to call
- `check_health` — liveness only, returns no news
## Before your first call
- **`q` inserts an implicit `AND` between bare words — silently.** `AI OR artificial
intelligence` runs as `AI OR (artificial AND intelligence)` with no error; write
`AI OR "artificial intelligence"`. Always quote multi-word phrases, and check
`applied_filters.search_text` in the response for what actually ran — over MCP
the tool also strips conversational filler from `q` before searching (so a
natural-language question works, and a `Note:` line says what changed), while
REST searches the string you sent verbatim.
- **`NEAR()` and `MULTIPLE()` are not supported in `q`.** They're silently read as
ordinary words rather than erroring — never use them.
- **The default time window is 24 hours**, and `from_` bounds when the story
*began* (`first_seen`), not when any article was published. Together these are
the top cause of empty results — widen `from_` first. For a single company,
person, or place, prefer `subject` over `q` (MCP-only): it quotes the name for
you and widens the window to 30 days, clamped to the plan.
- **Parameter names differ between MCP and REST.** MCP: `from_`, `subject`,
`response_format`. REST: `from` (plus `to`, `fields`, `order`,
`min_confidence`), no `subject`, always JSON — and it rejects unknown
parameters with a 400 naming them. The mapping table is in
[SKILL.md](https://newsmcp.com/agent-onboarding/SKILL.md).
- **Output shape is your choice over MCP.** `response_format` is `markdown`
(default), `text`, or `json`. If you are parsing, read `structuredContent` —
`news`, `get_story` and `check_coverage` return it on every call regardless of
format, matching each tool's `outputSchema` — or ask for `json`. Don't
pattern-match the markdown. REST has no such parameter and always returns JSON;
it rejects fields it doesn't define.
- **Keyless envelope:** 7-day lookback, 20 calls/hour, up to 20 stories per call,
1 request in flight at a time. Keyless over-asking is not an error — the search
runs narrowed and a `notices` array explains what was changed. With a key,
over-asking is rejected with an error naming the plan's allowance. Datacenter
and cloud IPs are blocked when keyless — from CI, serverless, or a VPS you
need a key, not a retry. `check_limits` reports any caller's live ceilings
and costs nothing.
- **`event_id` is not durable** — derived from cluster membership, so it changes
between searches. Don't store it.
## Auth
Installing NewsMCP into a client for repeated use? Get the free key *before*
writing the config — client configs persist, so a keyless install stays at the
keyless ceilings in every future session. Verify with `check_limits` after
connecting. Header `x-api-key: <key>` works everywhere and is the primary method. Over
**MCP**, `Authorization: Bearer <token>` and a `?apiKey=...` URL parameter
(for clients without a headers field) also work; no tool takes the key as an
argument — it goes on the connection.
Over **REST**, the `x-api-key` header is the *only* transport — a key in a
REST URL is silently ignored and the call runs keyless. When in doubt, call
`check_limits`: it reports which plan the server sees. Three ways to connect:
**OAuth sign-in** via `https://mcp.newsmcp.com/mcp?login` (needs a NewsMCP
account and a client that supports MCP sign-in; runs on the account's plan),
**API key**, or **keyless**. The bare `/mcp` URL never asks for a sign-in. Full precedence order in
[SKILL.md](https://newsmcp.com/agent-onboarding/SKILL.md) and
[/docs#adding-a-key](https://newsmcp.com/docs#adding-a-key). Get a key at
[platform.newsmcp.com/auth](https://platform.newsmcp.com/auth).