Overview
GDELT Cloud MCP uses a Progressive Discovery interface. Agents do not call GDELT Cloud product tools directly. They first discover the catalog, inspect exact schemas, then execute a named tool through a single wrapper.
This keeps the public MCP surface small while still giving agents rich tool descriptions and typed parameter guidance.
What The Agent Actually Sees
The public MCP surface is intentionally small. Agents see wrapper tools, not every nested product operation as a separate top-level tool.
| Category | Top-Level Wrapper Tools Agents See |
|---|
| GDELT Cloud | gdelt_cloud_tool_list, gdelt_cloud_tool_get, gdelt_cloud_tool_call |
| Macro finance | macro_finance_tool_list, macro_finance_tool_get, macro_finance_tool_call |
| Prediction markets | prediction_market_tool_list, prediction_market_tool_get, prediction_market_tool_call |
| Web research | web_research_tool_list, web_research_tool_get, web_research_tool_call |
*_tool_call, the agent passes a nested tool_name and tool_arguments.
Public GDELT Cloud MCP Tools
The MCP server exposes these three GDELT Cloud wrapper tools:
| Tool | Purpose |
|---|
gdelt_cloud_tool_list | List the public v2 GDELT Cloud tools and when to use them. |
gdelt_cloud_tool_get | Fetch exact schema, descriptions, enums, and parameter guidance for one or more tools. |
gdelt_cloud_tool_call | Execute a named v2 GDELT Cloud tool with nested tool_arguments. |
The legacy v1 MCP tool names are no longer exposed. v1 REST endpoints remain supported for direct API users, but agents should use the v2 MCP catalog documented here.
Workflow
Discover
Call gdelt_cloud_tool_list to see the available v2 GDELT Cloud product tools.
Inspect
Call gdelt_cloud_tool_get before first use of a tool. The schema contains practical descriptions, enum values, default behavior, and guidance on how analysts should use each parameter.
Execute
Call gdelt_cloud_tool_call with tool_name and nested tool_arguments.
Event, Story, and Entity search tools default to the exact past 24 hours. Agents should narrow with developer-facing filters such as category, subcategory, civilian_targeting, country/region/continent filters, date windows, sort, and pagination.
Example
{
"tool_name": "search_events",
"tool_arguments": {
"category": "Battles",
"subcategory": "Armed clash",
"country": "Lebanon",
"has_fatalities": true,
"days": 7,
"sort": "significance",
"limit": 10
}
}
v2 Catalog
| v2 Tool | Use When |
|---|
search_events | You need structured Conflict or CAMEO+ Event cards. |
summarize_events | You need dashboard-ready Event counts or trends. |
get_event | You know an Event ID and need the full card. |
search_stories | You need clustered narrative Stories and article evidence. |
summarize_stories | You need Story rollups by date, geography, category, or subcategory. |
get_story | You know a Story ID and need details plus top articles. |
get_story_articles | You need the full paginated article list for a Story. |
search_entities | You need to discover linked people or organizations. |
get_entity | You know an Entity ID and need its linked Stories and Events. |
list_admin1 | You need valid state/province/admin1 names for one country. |
External Enrichment Categories
GDELT Cloud structured Events and Stories should anchor the analysis. External MCP categories are encouraged as complements:
| Category | Use For |
|---|
macro_finance_* | Quotes, FX, commodities, rates, historical series, and macro indicators. |
prediction_market_* | Kalshi-backed event and market search, contract details, probabilities, status, and public market URLs when available. |
web_research_* | Corroboration, official statements, specialist sources, and reading source-article pages. |
External Nested Tools
| Category | Nested Tools |
|---|
| Prediction markets | SEARCH_RELEVANT_MARKETS, SEARCH_EVENTS, SEARCH_MARKETS, GET_MARKET |
| Web research | SEARCH_WEB, EXTRACT_WEB_PAGES |
| Macro finance | Discover current macro-finance provider-backed quote, historical series, FX, commodities, rates, and economic-indicator tools with macro_finance_tool_list. |
SEARCH_WEB and EXTRACT_WEB_PAGES; crawl and map operations are intentionally not public.
