> ## 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.
# MCP Server Introduction
> Connect AI agents to GDELT Cloud v2 products and enrichment tools using the Model Context Protocol
## 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`
OAuth MCP authorization currently runs in your personal workspace. To attribute MCP usage to a company organization, switch to that organization in GDELT Cloud, create an organization-scoped API key, and configure your MCP client with that key.
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:
| Tool | Purpose |
| ----------------------- | ------------------------------------------------------------------------- |
| `gdelt_cloud_tool_list` | Discover the public v2 GDELT Cloud catalog. |
| `gdelt_cloud_tool_get` | Inspect exact schemas, descriptions, enum values, and parameter guidance. |
| `gdelt_cloud_tool_call` | Execute one v2 GDELT Cloud tool using nested `tool_arguments`. |
External categories use the same pattern:
| Category | Wrapper Tools Agents See |
| ------------------ | ------------------------------------------------------------------------------------------ |
| 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` |
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 Tool | Purpose |
| ------------------------- | -------------------------------------------------------------------------------------- |
| `search_events` | Structured Conflict and CAMEO+ Event cards. |
| `summarize_events` | Event rollups and trends for dashboards. |
| `get_event` | Fetch a known Event by ID. |
| `search_stories` | Clustered Stories with narrative and article evidence. |
| `summarize_stories` | Story rollups and coverage trends. |
| `get_story` | Fetch a known Story by ID. |
| `get_story_articles` | Paginated source articles for a Story. |
| `search_entities` | Discover linked people and organizations. |
| `get_entity` | Fetch an Entity profile with linked Stories and Events. |
| `list_admin1` | Discover valid admin1 values for one country. |
| `energy_search_assets` | Search GEM energy assets by tracker, status, geography, capacity, owner, or proximity. |
| `energy_summarize_assets` | Roll up GEM asset counts and capacity by tracker, country, status, fuel, or decade. |
| `energy_get_asset` | Fetch one GEM asset detail record. |
| `energy_search_owners` | Resolve GEM owner names to canonical GEM Entity IDs. |
| `energy_get_owner` | Fetch one GEM owner with parent/external IDs and portfolio summary. |
| `energy_assets_by_owner` | Pivot from a GEM Entity ID to all matching assets. |
## 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. Use Energy tools when the question is about static infrastructure facts such as capacity, owner, status, location, or asset portfolio.
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
| Category | Use |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `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. GDELT Cloud validates the selected Brief input, loads the selected MCP skill, and 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 5 QU. Tool calls made by the hosted Brief agent, including scheduled Brief runs, are tracked as `brief` usage, cost 0 QU, and are metered in Brief Units.
## Getting Started
Connect and make your first Progressive Discovery call.
Learn the public v2 GDELT Cloud MCP catalog.
Learn when to use macro finance, prediction markets, and web research.
Learn how agent task skills guide analyst workflows.
Learn how structured Brief products are generated and scheduled.