Overview
The Model Context Protocol (MCP) is how AI assistants such as Claude, ChatGPT, Cursor and VS Code reach outside data. The AO.news MCP server hands your assistant the whole AO.news database as tools it can call on its own: push notifications from hundreds of news apps and front-page robots in about 60 countries, translated to English, clustered into stories, with country toplists, first-mover timing and your own decks. You ask a question in plain language; the assistant decides which tools to call, reads the answers and writes back with links to the articles.
Three things to know before you start:
- Authentication is your tracker. The same identifier that owns your decks and is your Firehose API key. It goes in the server URL, so connecting is a matter of pasting one link.
- It reaches into the archive. Unlike the Firehose's 24-hour window, the MCP tools search back to 2021. One call covers at most 31 days; the assistant splits longer periods by itself. Story cards (headline, summary, topic) exist from October 2026.
- It is read-only. Nothing your assistant does through MCP can change a deck, a setting or a single row.
Connect your assistant
Your server URL is https://ao.news/mcp/YOUR_TRACKER. Every client below takes that URL; pick yours.
Claude (claude.ai and the desktop app)
- Open Settings → Connectors and choose Add custom connector.
- Name it
AO.newsand pastehttps://ao.news/mcp/YOUR_TRACKERas the URL. Leave the OAuth fields empty. - In a chat, enable AO.news from the tools menu and ask away. On Team and Enterprise plans an owner adds the connector once for the whole organisation.
Claude Code
claude mcp add --transport http aonews https://ao.news/mcp/YOUR_TRACKERAdd --scope user to have it in every project. Prefer to keep the tracker out of the URL? Use the header form: claude mcp add --transport http aonews https://ao.news/mcp/ --header "Authorization: Bearer YOUR_TRACKER".
ChatGPT
Turn on Developer mode under Settings → Apps & Connectors → Advanced, then Create a connector with the URL https://ao.news/mcp/YOUR_TRACKER and authentication set to No authentication.
Cursor, VS Code, Windsurf and other clients
// Cursor: ~/.cursor/mcp.json · Windsurf: ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"aonews": { "url": "https://ao.news/mcp/YOUR_TRACKER" }
}
}
// VS Code: .vscode/mcp.json
{
"servers": {
"aonews": { "type": "http", "url": "https://ao.news/mcp/YOUR_TRACKER" }
}
}Any client that speaks MCP's Streamable HTTP transport works. If yours only does local (stdio) servers, bridge it with npx mcp-remote https://ao.news/mcp/YOUR_TRACKER.
Your own code
# Python, with the official SDK (pip install mcp)
from mcp.client.client import Client
async with Client("https://ao.news/mcp/YOUR_TRACKER") as ao:
r = await ao.call_tool("top_stories", {"country": "DE", "since": "7d"})
print(r.content[0].text)What to ask
Write the way you would brief a colleague. The assistant chooses the tools; these are questions it answers well.
The morning brief
"What are the ten biggest stories in Germany since midnight, and which of them has no Swedish outlet pushed yet?"
What are we missing
"Which stories are four or more sources abroad pushing right now that nobody in Norway has picked up? Give me a line on each and the best article link."
Who was first
"Over the last month, how often did our app beat our two main competitors to a push, and what were the five stories where we were slowest?"
Follow a story
"Show me how the Patriot missile sale story spread: which country pushed it first, and how many minutes later did each country follow?"
Research the archive
"Find every push about earthquakes in Turkey in February 2023 and summarise how the coverage developed day by day."
Push habits
"How many pushes a day do the French news apps send, per app, over the last three weeks? Is anyone ramping up?"
Tools
All tools are read-only. Times are UTC and accept ISO 8601 (2026-10-30T08:00) or relative values (90m, 6h, 7d, 2w). Countries are ISO 3166-1 alpha-2 codes (SE,NO,DK); outlets are package ids from list_sources.
| Tool | Arguments | What it returns |
|---|---|---|
search_pushes | query, countries, apps, since, until, sources, min_score, min_sources, max_sources, one_per_story, absent_in, limit | Push notifications, newest first, with original text, English translation, article link and story. Same filters as a deck column; query uses the deck's word-filter syntax (AND, OR, NOT, "phrases"). Default the last 24 hours. Unless you ask for everything, the assistant is told to keep the noise down with min_sources=2 and one_per_story=true: one row per story that at least two sources carried. max_sources caps a story's source count, to hide runaway mega-stories or find stories still growing. |
get_push | push_id | One notification in full: original and English title and text, app, country, URL, story. |
get_story | story_id, limit | A story card (headline, summary, topic, countries, number of sources), who was first in every country with minutes after the first push, and the timeline of every push. |
search_stories | query, country, topic, since, until, min_sources, limit | Stories matching words in headline, summary or keywords, biggest first. Topics: politics, sports, business, crime, entertainment, society, accidents, conflict, environment, science_tech, health, lifestyle. |
top_stories | country, since, until, min_score, limit | The country's toplist: stories ranked by how many of its own sources pushed them, with who was first in that country. |
breaking_abroad | country, hours, min_sources, limit | The newsroom wall as data: stories several sources abroad are pushing that no source in your country has picked up yet. |
compare_speed | apps, since, until, examples | First-mover scoreboard for two or more outlets: races won, share first, median minutes behind, and the stories with the biggest gaps. |
push_volume | countries, apps, since, until, bucket, group_by | Push counts per hour, day or week, by country, by app or in total. |
list_sources | country, kind, name | Every outlet AO.news follows: package id, name, country, language, website, app or robot. |
list_countries | none | Covered countries with their number of apps and robots. |
my_decks | none | Your decks and their columns, with each column's filters as search_pushes arguments, so "what's new in my Nordic column?" just works. |
Pushes and stories
Two kinds of thing come back. A push is one notification (or one front-page headline, for robots). A story groups every push about the same event across outlets and countries; its number of distinct sources is the best single measure of how big it is.
// one row from search_pushes
{
"id": "fa72bcdd2252ae0dec14b186dac3ce6f",
"time_utc": "2026-10-30T20:12:21Z",
"app": "gp.se",
"package_id": "headline-robot.gp.se",
"country": "SE",
"source": "robot",
"score": 6,
"language": "sv",
"text": "USA godkänner Patriot-försäljning till Ukraina …",
"english": "USA approves Patriot missile sale to Ukraine …",
"url": "https://www.gp.se/nyheter/varlden/usa-godkanner-patriot-forsaljning-till-ukraina…",
"story_id": 43475048,
"story_sources": 23,
"story_url": "https://ao.news/cluster/43475048",
"story_headline": "US approves $2.1B sale of 500 Patriot missiles to Ukraine"
}
// the start of get_story(43475048)
{
"story_id": 43475048,
"headline": "US approves $2.1B sale of 500 Patriot missiles to Ukraine",
"summary": "The U.S. State Department has approved a potential $2.1 billion sale …",
"topic": "conflict",
"sources": 24,
"countries": ["BG", "DE", "SE", …],
"first_by_country": [{ "country": "US", "first_app": "…", "minutes_after_first": 0.0 }, …],
"timeline": [ /* every push, oldest first */ ]
}Real output, trimmed. english is left out when the push already is in English. url is the article when AO.news has resolved it, otherwise an AO.news redirect that finds it. story_url is a live page where you can follow the story as new pushes arrive; assistants put it next to the article link in their answers. Story ids are the same as the cluster ids in the Firehose.
Ready-made prompts
The server also ships two prompts, which clients such as Claude show in their prompt or slash-command menu:
what_did_we_miss(country): the big stories abroad no source in your country has pushed yet, biggest first, with a summary and a link each.who_was_first(apps,period): a first-mover scoreboard for the outlets you name, with the three biggest gaps explained.
Limits, safety, fair use
- Read-only, by construction. The server connects with a read-only database role in read-only transactions. No tool writes, and no prompt can talk it into writing.
- Per call: at most 31 days and 500 rows. Each query gets 15 seconds; a slower one is stopped and the assistant is told to narrow the question, which it normally does on its own.
- Per tracker: 120 tool calls a minute. A busy moment can return "AO.news is busy, try again in a few seconds"; assistants retry.
- Errors come back as tool errors with a plain-language reason (expired tracker, window too wide, unknown country code), which the assistant reads and acts on.
- Your tracker is a key. Anyone with your server URL can use your access. Put it in your organisation's connector settings rather than in shared documents, and ask us for a new one if it leaks.
- Fair use. The data is for your newsroom's own monitoring, research and products. Notification text belongs to the publishers who wrote it: link to the article (that is what
urlis for) rather than republishing it wholesale.
Troubleshooting
| You see | Why, and what to do |
|---|---|
401 unknown tracker | The tracker in the URL does not exist. Check for typos; it is the part after ao.news/ in your deck links. |
403 tracker is expired | Your subscription has ended. Write to us to renew. |
403 tracker is not on a plan with API access | MCP comes with the same plans as the Firehose API. Write to us to add it. |
| The client connects but lists no tools | Check that the URL ends in your tracker, not in /mcp: https://ao.news/mcp is this page. |
| "The window is N days; at most 31" | Ask for a shorter period, or let the assistant split it up; most do when they read the error. |
Getting access
MCP access comes with newsroom plans, the same ones that include the Firehose API. If you have one, your tracker already works: paste https://ao.news/mcp/YOUR_TRACKER into your assistant. Otherwise write to hello@ao.news with a sentence on what you want to ask your assistant; access is usually set up the same day.