curl.
Walk through a real question
Connect, ask broadly, drill down, check the citations — one question end to end.
How the tools are organised
The current public server exposes named operations with direct typed arguments. Use connected tool descriptors for the current public release. Familiar operations can be called directly; client-native tool search or deferred loading controls schema access where supported. Start from the user’s intent and the smallest useful workflow. Use the core tools for Events, Stories, identities, countries, Situations and Monitors. Resolve a name withunified_entity_search; use search_entities to discover actors in reporting over date,
geography, taxonomy and co-occurrence filters. These operations share entity IDs but answer
different questions. Use facilities for physical sites, then specialists for native evidence.
Optional get_data_catalog orients to domains and relationships. For core sections, use
get_data_catalog(domain="gdelt_cloud", section="identity"); omit section for the whole core
catalog. get_parameter_options supplies unfamiliar categorical choices, while scoped
get_event_taxonomy explains Event categories and subcategories. Reuse a known schema rather
than requiring discovery before every call. Keep the default taxonomy page size and paginate only
when needed.
Authorized mutations use named tools such as create_monitor and update_monitor, with host
approval. Preview never saves or sends delivery. The explicit legacy wrapper compatibility
profile retains domain list/get/call tools and gdelt_cloud_tool_write; it is not the default
public surface.
Every category and every tool
The full surface, generated from the same declaration the docs and the API reference share.
Results in chat and in code
Data operations acceptresponse_mode="compact" (default) or "full". Compact keeps record
identifiers, returned links, selected imagery, evidence, filters and coverage. A compact list page
requests only the records it shows (8 Event, Story or entity cards, 60 other records), so
next_cursor continues after the last record shown; _mcp_projection reports requested_limit
and applied_limit when it asked for fewer. Full returns larger pages. Registry coverage keeps publication and completeness decisions, every
source identity and its limits, and exact served/missing dates. Repeated build and adjudication
audit reports are omitted with an omitted_registry_audit_reports count. Full preserves the
bounded API response, including those audit reports. Neither mode fetches extra pages.
Use returned GDELT Cloud Event, Story, Situation, entity and facility links for product records.
Original publisher links support underlying reporting; registry facts retain their dataset attribution.
A missing image or link is not a reason to invent one. Partial coverage is not a zero result.
Research results belong in native chat: linked titles, selected returned images, compact comparison tables and client-native charts where supported. Rank and compare Events by significance, which scores both families on one scale. Describe a CAMEO+ Event with its category/subcategory and the four core metrics (magnitude is category-relative; the other three scores are not forecast probabilities); a Conflict Event has no sub-factor metrics. Font, color, icons and image size are controlled by the client. Missing images leave a complete text answer. Maps, when supported by the client, must use returned coordinates and precision rather than place/business listings.
App blocks are reserved for account navigation and Monitor workflows. gdelt_cloud_monitor_form opens an editable setup form using the parameters discovered for preview_monitor. It previews the actual scope through the same authenticated API; it never saves or sends by itself. Ordinary preview_monitor calls remain native chat. Only account help and the editable Monitor form use app components; exact rendering depends on the client.
To propose a Monitor, preview the actual scope, review the matches and coverage, then confirm saving
paused or starting scheduled checks. Delivery can use email, webhook, or both, subject to the API’s
validation and plan access. Preview sends no notification and creates no Monitor. Website signup and sign-in happen during the OAuth/account journey. Account help provides sign-in and connection documentation; the MCP does not promote subscriptions or initiate purchases.
Connecting supplies a concise overview of every data group, record types, Event taxonomy and metrics. For deeper relationships and analytical guidance, read the free resource gdelt://guides/connection-orientation or request gdelt_research_system_prompt. Both return the same detailed guide. Exact schemas and specialist workflows remain available on demand; a simple lookup does not require loading the whole guide.
Guidance on demand
Initialization instructions establish intent, structured-data selection and evidence handling. The compatible research prompt points to shared skills and resources instead of repeating a long manual. Ask a concrete question; your agent should discover the relevant schema and workflow, then ask a focused follow-up only when it changes the scope or next action.Facilities and minerals
Find U.S. mineral facilities, inspect GEM overlap, read country reserves and follow participant identities through REST and MCP.
What is metered
Data operations use the same usage admission as the REST API. Localget_data_catalog,
get_parameter_options and get_event_taxonomy discovery is not metered. An endpoint your entitlement does not
include returns an error naming what it needs — never an empty result, which would be
indistinguishable from missing data.
Beyond GDELT Cloud data
Web research is optional support for a GDELT Cloud task: initial orientation, corroboration, or reading a relevant source page. It must not replace missing structured evidence or serve as a standalone web-search proxy. Prediction-market tools have been retired. See Supporting research for the supported web operations.Integrations
Claude, Claude Code, ChatGPT, Codex, LangChain.
Plugins
Claude Code, Codex and Cursor: both servers and eight skills, in one command.
Skills
Packaged workflows the server can load on demand.

