Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.gdeltcloud.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The GDELT Cloud MCP server gives AI agents access to generated GDELT Cloud products through a Progressive Discovery interface:
  • structured Events: Conflict and CAMEO+
  • clustered Stories with top article evidence
  • Entities linked to Events and Stories
  • admin1 geography discovery
  • dashboard-ready summaries
  • macro-finance, prediction-market, and web-research enrichment tools
  • task skills and Brief skills for standardized analyst workflows
MCP Server URL: https://gdelt-cloud-mcp.fastmcp.app/mcp
GDELT Cloud structured Events and Stories are the anchor. The non-GDELT Cloud tools are encouraged as complements: use macro finance for prices and indicators, prediction markets for market-implied probabilities, and web research for corroboration or reading source articles.

​
Progressive Discovery

Agents see wrapper tools first. They discover a category, inspect schemas, then execute a nested tool through *_tool_call. For GDELT Cloud, agents use three wrapper tools:
ToolPurpose
gdelt_cloud_tool_listDiscover the public v2 GDELT Cloud catalog.
gdelt_cloud_tool_getInspect exact schemas, descriptions, enum values, and parameter guidance.
gdelt_cloud_tool_callExecute one v2 GDELT Cloud tool using nested tool_arguments.
External categories use the same pattern:
CategoryWrapper Tools Agents See
Macro financemacro_finance_tool_list, macro_finance_tool_get, macro_finance_tool_call
Prediction marketsprediction_market_tool_list, prediction_market_tool_get, prediction_market_tool_call
Web researchweb_research_tool_list, web_research_tool_get, web_research_tool_call
Legacy v1 MCP tools such as get_media_events, get_conflict_events, and get_cameoplus_events are no longer exposed. v1 REST remains available for direct API users only.

​
GDELT Cloud v2 Tool Catalog

v2 ToolPurpose
search_eventsStructured Conflict and CAMEO+ Event cards.
summarize_eventsEvent rollups and trends for dashboards.
get_eventFetch a known Event by ID.
search_storiesClustered Stories with narrative and article evidence.
summarize_storiesStory rollups and coverage trends.
get_storyFetch a known Story by ID.
get_story_articlesPaginated source articles for a Story.
search_entitiesDiscover linked people and organizations.
get_entityFetch an Entity profile with linked Stories and Events.
list_admin1Discover valid admin1 values for one country.

​
Tool Selection

Use summaries for dashboards and trend detection. Use Events when the user needs structured incidents, actors, geo, fatalities, Goldstein scale, or CAMEO+ metrics. Use Stories when the user needs narrative evidence, article clusters, and source URLs. Use Entities when actors are the analytical object or when an Event/Story points to important people or organizations. Geography is documented as plain English country names. ISO-3 and legacy FIPS codes are accepted as aliases, but examples should lead with names such as United States, Lebanon, or South Korea.

​
External Categories

CategoryUse
macro_finance_*macro-finance provider-backed quotes, historical series, FX, commodities, rates, and economic indicators.
prediction_market_*Kalshi-backed market and event search, contract records, probabilities, status, and public URLs when available.
web_research_*Tavily-backed SEARCH_WEB and EXTRACT_WEB_PAGES for corroboration, official statements, specialist sources, and source-article reading.

​
Skills And Prompt

The MCP server includes:
  • gdelt_research_system_prompt: the always-on system prompt for the research agent.
  • gdelt_brief_system_prompt: the hosted Brief agent prompt.
  • Task skills oriented around workflow patterns: gdelt-discover-and-drill, macro-finance, prediction-markets, multi-surface-synthesis, brief-output.
  • Brief skills for Daily Operational Risk, Crisis SITREP, Indications & Warning, and Exposure Monitor products.
Skills teach the agent to summarize, search, drill, then synthesize: start with GDELT Cloud aggregate metrics, search for citable Stories, drill into article evidence and the entity graph, then enrich with macro-finance or prediction-market data when the question spans surfaces. Hosted Briefs use MCP as the source of truth for prompts and skills. The Next.js app validates the selected Brief input, the LangGraph Brief agent preloads the selected MCP skill, and the model returns structured Brief content for Web Brief rendering.

​
Query Unit Metering

Direct MCP tool calls from a user’s own MCP client cost 1 QU each. Tool calls made by the hosted GDELT Cloud Agent UI cost 3 QU. Tool calls made by the hosted Brief agent, including scheduled Brief runs, are tracked as brief usage and cost 5 QU each.

​
Getting Started

Quickstart

Connect and make your first Progressive Discovery call.

GDELT Cloud v2 Tools

Learn the public v2 GDELT Cloud MCP catalog.

External Tools

Learn when to use macro finance, prediction markets, and web research.

Skills

Learn how agent task skills guide analyst workflows.

Brief Skills

Learn how structured Brief products are generated and scheduled.