Skip to main content
You do not need to write code to use GDELT Cloud. Connect the MCP server to Claude, ChatGPT or your own agent, and ask in plain language — the model picks the endpoints, and every claim comes back with the articles behind it. This page walks one real question end to end.
1

Connect (about two minutes)

Add the server URL to your client and authenticate with your API key. Setup is three lines of config per client and is written out in Integrations.
You are connected when the model can list the GDELT Cloud tools.
2

Start wide, not narrow

“What’s been happening with energy infrastructure in Nigeria over the past two weeks?”
Ask the broad version first. The model will call a summary endpoint, which returns counts grouped by date, geography and category — the shape of the period rather than a list of rows.This is the step people skip, and skipping it is the single biggest source of wrong answers. Go straight to a narrow filtered query and an empty result looks like “nothing happened” when it actually means “that combination of filters matched nothing.” The summary tells you where the volume actually is before you commit to a filter.
3

Drill into what the summary surfaced

“Show me the most significant ones, with sources.”
Now the narrowing is grounded in something you have seen. The model filters to the categories and places that actually carried volume, and ranks by significance — the blended score the product sorts by, which is designed to compare events across domains rather than within one.
4

Check the evidence

“What are the underlying articles for the third one?”
Every event traces back to the story it was coded from, and every story to its source articles with URLs and publication dates. Ask for this every time. An event is our reading of a cluster of coverage; the articles are what that reading was based on, and they are how you tell a well-supported event from a thin one.Two signals worth checking: how many articles back the story, and whether they are independent outlets or one wire story republished.
5

Widen to the entity

“Does this company have US federal contracts or sanctions exposure?”
Once an entity is named, the same resolved identity reaches government awards, corporate filings, ownership-chain exposure and physical assets. This is the part that is hard to do by hand: the model resolves the name once and reuses that identity everywhere, so the answer does not silently cover only the surfaces where the name happened to be spelled the same way.

​
What to trust, and how far

When coverage was not found, the API returns null rather than 0. If a model reports “no negative coverage,” check whether that means measured and none or not measured. The distinction is preserved in the data specifically so it can be preserved in the answer.
It is scored across news articles. A country with little coverage has little tone data — that is a statement about the press, not about the country.
Coverage starts partway through 2026 and is being backfilled; before that it is thin enough to be misleading. A query reaching further back returns a near-empty result that looks like a bug. The window is in Coverage, and the exact span and cadence per dataset are in the data catalog.
Each event metric has a published list of what it explicitly does not measure — the most common misreading is treating market sensitivity as a severity score. See worked examples for two real events scored by hand.

​
The same question through the API

If you would rather script it, the identical flow is four HTTP calls — summarize, drill, fetch articles, fan out — in Build a monitoring feed.

​
Next

Connect your client

Claude, Claude Code, ChatGPT, Codex, LangChain.

Data catalog

What is ours, what we ingest, and what each source does not cover.