Live news, as story events.

00 — Quickstart

One call, no key.

Nothing to install and no signup. The fastest way to see real output is the REST surface — same data, no JSON-RPC envelope:

curl -s -X POST https://api.newsmcp.com/v0/search_news \
  -H 'Content-Type: application/json' \
  -d '{"q":"\"OpenAI\"","event_size":3}'

Or over MCP, which is what your assistant uses:

claude mcp add --transport http newsmcp https://mcp.newsmcp.com/mcp

Then just ask: “What are the top stories about Apple today?”

01 — The model

Events, not articles.

This is the one concept worth understanding before anything else. A search does not return a flat list of articles. It returns events — and every outlet covering the same story collapses into one of them.

So a busy story arrives as a single object with article_count: 125 rather than 125 near-identical rows. Your agent reads one result instead of thirty duplicates, and article_count doubles as a salience signal: how many newsrooms thought this was worth covering.

Each event carries up to 3 representative citations — headline, summary, link, date, theme, sentiment. Article body text is never returned. Follow the link to read the full piece at the publisher.

02 — Connect

Three ways in.

MCP server

The server URL is https://mcp.newsmcp.com/mcp — streamable HTTP, stateless, no session handshake.

Claude Code:

claude mcp add --transport http newsmcp https://mcp.newsmcp.com/mcp

Claude Desktop / Cursor — add to your MCP config, then restart:

{
  "mcpServers": {
    "newsmcp": {
      "url": "https://mcp.newsmcp.com/mcp"
    }
  }
}

REST

Same behaviour, plain HTTP. Useful for scripts and backends.

POST https://api.newsmcp.com/v0/search_news
GET  https://api.newsmcp.com/health

Full machine-readable spec: openapi.json.

Authentication

None required — keyless works. To use a token, send it as a header:

x-api-token: <your-token>

03 — Writing queries

Quote your phrases.

Only q is required. It is matched against whichever fields search_in selects.

• These characters are never valid in a query: [ ] / \ : ^
• Be specific with ambiguous names — Apple iPhone beats apple.
• Use * as the query when you only care about filters: “everything in the Weather theme from GB in the last day” needs no keywords at all.

04 — Parameters

One required, the rest optional.

Your assistant sets most of these from your wording — you rarely name them yourself. List-type parameters accept several values at once: multiple values inside one parameter mean OR, while different parameters combine with AND.

search_in

title_content matches headline and body — broader recall. title matches headlines only, which gives you stories that are about a subject rather than merely mentioning it in passing.

sort_by

Controls the order articles are collected in, before clustering — so it decides which articles make it into your results.

• relevancy — best text match first
• date — newest first
• -date — oldest first

The leading minus on -date means ascending, the opposite of the usual convention. date is the one that gives you the latest news.

event_size

Caps events, not the articles inside them. The default of 1 gives one focused story — ask for more when you want breadth. There is no pagination: to go wider, raise event_size or split the time range across several searches.

grouping

The cosine-similarity threshold for treating two articles as the same story: low = 0.7 (loosest, broader events), medium = 0.8, high = 0.9 (strictest, more single-article events). If results feel lumped together, raise it; if one story keeps appearing as several events, lower it.

source_groups

Search a ranked set of publishers without maintaining a domain list: Top <N> [languages] [topics] [countries].

Top 20                              the 20 highest-ranked publishers globally
Top 10 Finance GB                   top 10 UK finance publishers
Top 15 English Financial Crime US   "Financial Crime" reads as one topic

• Languages must be spelled out. A bare two-letter token is read as a country — FR means France, French means the language.
• It selects publishers, not articles. Top 10 English Politics US does not filter results to English, Politics, or the US — ask for those explicitly.
• One expression per search. Naming sources this way replaces the default trusted-publisher filter.

theme

A fixed list of 16; anything else is rejected. Business, Finance and Economics overlap in practice — pass all three for full business coverage. General is the catch-all, so filtering to it narrows rather than widens.

Always-on quality rules

Three filters apply to every search and cannot be switched off: a minimum length so stubs don't crowd out reporting, no paywalled content, and news publishers only. That last one has a deliberate exception — when you name publishers yourself via sources or source_groups, your list replaces the default.

05 — What comes back

Pick your output shape — over MCP.

Ask for it in words (“give me that as JSON”) or pass response_format: "json" directly. If you intend to parse the result, request JSON rather than pattern-matching the markdown.

{
  "status": "ok",
  "events_count": 41,
  "events": [
    {
      "event_id": "1847a4931a6c8002",
      "article_count": 125,
      "event_score": 5.85,
      "articles": [
        {
          "title": "White House summons AI giants after models go rogue",
          "summary": "Meta, Anthropic, OpenAI and Google have been invited…",
          "link": "https://www.independent.co.uk/tech/…",
          "published_date": "2026-08-04T08:21:26",
          "theme": ["Tech", "Politics"],
          "sentiment": "Negative"
        }
      ]
    }
  ]
}

06 — Access and limits

Start without a key.

Every plan, keyless included, comes with a full commercial licence — ship what you build from day one. For a token, a longer window or the Enterprise tools, go through sign in.

07 — Troubleshooting

When something goes wrong.

check_health confirms the service is reachable — no token, no parameters, no news returned. Use it when a search fails and you want to know whether the problem is the service or the request. Ask: “Check NewsMCP health.”

08 — Example asks

You never name parameters.

These are all valid things to say to your assistant:

Tips

• Be specific with names. Apple iPhone beats apple; "Tim Cook" in quotes beats it unquoted.
• Say which filters you care about. Mentioning a language, country, publisher, theme or sentiment is what makes your assistant apply it.
• Ask for breadth explicitly. The default is one focused story group; “give me the top 20 stories” gets you a sweep.
• Follow the links. Summaries are for triage; the full article always lives with the publisher.