MCP

The same index as the REST API, as a Model Context Protocol server, so an agent can decide for itself what to look up.

https://api.unzoi.com/mcp

Authenticated with the same key and the same header as REST, billed against the same allowance, and returning the same JSON. The tool arguments are the REST query parameters — the two surfaces are generated from one contract, so they cannot answer a question differently.

Connect a client Claude, ChatGPT, Cursor, VS Code, LangChain and a dozen more. Tool reference All 18 tools and every argument. Transport Streamable HTTP, negotiation, and why there is no session to keep alive. Errors Which failures close the connection, and which are a bill you can pay.

The tools

Tool	REST equivalent	What it does
`search_news`	`/search`	Search the news index.
`list_stories`	`/stories`	Search and collapse results into deduplicated stories (one real event across many outlets).
`top_headlines`	`/top-headlines`	Most-recent articles, optionally filtered by indexed article metadata and time range.
`get_article`	`/doc/{id}`	Fetch a single article's rich metadata by id, including names, structured locations and dates, quotations, amounts, related media, links, and alternate URLs.
`find_related`	`/similar/{id}`	Find articles semantically similar to a given article id (More-Like-This).
`get_story`	`/stories/{id}`	Expand one story by its story_id (from list_stories or any article): the article and outlet counts, every outlet, when it was first and last seen, the entities and topics it is about, and its newest articles as compact hits.
`resolve_entity`	`/entities`	Find the spellings the index holds for an organization, person, place, topic, author or source, before filtering on it.
`aggregate_news`	`/aggregate`	A time series over the match set: per calendar bucket (hour, day, week, month, or `all` for one bucket), the article count and optionally the distinct story count, the distinct outlet count and a signal's mean and percentiles.
`related_entities`	`/graph/related`	The entities most often mentioned alongside one entity (organizations, people, places, topics), strongest first, each with its co-mention count and share and, for the strongest, the newest articles mentioning both plus distinct sources, stories and first and last seen.
`connection_path`	`/graph/path`	How two entities connect in the reporting: the articles mentioning both, and up to five paths through one shared neighbour, each hop with its co-mentions and evidence.
`entity_network`	`/graph/network`	One entity's neighbours grouped by type for a window.
`shared_exposures`	`/graph/exposures`	What up to five entities have in common: the articles mentioning all of them, their distinct stories and sources, the facets you ask for (topics, countries, sources and so on), mean and percentile intensities of the signals you name, and the newest shared articles as evidence.
`create_watch`	`POST /watches`	Save a /stories query the index runs for you every interval_minutes, instead of polling.
`list_watches`	`/watches`	List this account's watches with their status (active, paused_key, paused_credits, failing), last and next run, and the plan's cap.
`get_watch`	`/watches/{id}`	Read one watch: the /stories query it runs, its interval and minimum_outlets, which events it records, its webhook_url, and its status (active, paused_key, paused_credits, failing) with the last and next run and the watermark.
`delete_watch`	`DELETE /watches/{id}`	Delete a watch with its state and its events.
`watch_events`	`/watches/{id}/events`	Read a watch's events, newest first: new_story and story_growth, each with the story's counts and, when a webhook is set, its delivery status.
`account_status`	`/account`	Report this session's account: plan, credits a minute, the monthly credit allocation and how much of it is used, whether the key stops at its allocation or bills overage, how far back the plan may query (history_days; null = the full archive), calls and credits this session, and whether metered billing is active.

Read the schemas straight from the server at https://api.unzoi.com/mcp/tools.json — no key needed. This site's tool reference is generated from that file.

When to use MCP instead of REST

Use MCP when a model is choosing what to look up. Use REST when your code is.

That is not a style preference. The tool descriptions are written for a model to read, and they carry the judgement a good integration needs: when clustering beats article search, why hybrid ranking suits a query a model wrote, which calls cost more credits. A model reading those picks well. Your own code does not need to be told, and REST is one less hop.

A pipeline with a fixed query wants REST. A research agent that will follow a thread it has not seen yet wants MCP. An application that does both should use both, on one key.

Two tools do most of the work

If an agent only ever calls one of these, make it list_stories. News is repetitive, and returning one row per event rather than forty near-identical articles is the biggest context-window saving available here. If it calls two, the second is get_story: one call turns a row into the whole event — every outlet, when it was first and last seen, what it is about, its newest articles — with no re-search. For a question about change over time, add aggregate_news: one call returns the series an agent would otherwise build from a search per day. For "who is connected to X", related_entities and connection_path answer from co-mentions in the reporting, with the articles as evidence: a reporting pattern, not a fact about the world. To follow a topic rather than answer a question once, create_watch hands the polling to the index, and watch_events reads what it found, in the same session or a later one. The guide explains when neither is the right call.

Two ways to run it

	Hosted	Local stdio
Endpoint	`https://api.unzoi.com/mcp`	A binary your client spawns
Setup	A URL and a header	Build it, point it at storage
Corpus	The whole live index	Whatever shard you have locally
Auth	Per request	Once, from the environment
Watches	Yes	No: the watch tools answer `unsupported`
For	Everyone	Air-gapped work, or hacking on the engine

 Almost everyone wants the hosted endpoint. Pick your client.