Named tools and optional discovery
The current public MCP exposes 117 named domain operations with direct typed arguments, plus local discovery, resources and account/Monitor helpers. Availability follows the connected account. Use connected tool descriptors for the current public release. Call familiar operations directly; client-native tool search or deferred loading controls which schemas enter context where supported. There is no required wrapper preflight. Optionalget_data_catalog explains domains and relationships. get_data_catalog(domain="gdelt_cloud", section="identity") scopes core discovery; omitting section retains the complete core catalog. get_parameter_options returns bounded categorical choices and parent dependencies. get_event_taxonomy explains category/subcategory meanings; keep its default page size and scope to a known category when useful.
unified_entity_search resolves an identity: which entity does this name mean? search_entities discovers actors in reporting within date, geography, taxonomy and co-occurrence filters: who appears in this reporting? Both return compatible entity IDs; a quiet reporting window does not establish that an identity is absent.
Core sections and response modes
- news: Events, Stories and summaries. Related: media_intel for tone and share of voice.
- identity: Unified identities and dossiers. Related: filings, energy and GLEIF for native source records; facilities for sites.
- countries: Country context and geography. Related: macro for native economic series.
- situations: Persistent topic research and linked evidence; creation changes state.
- monitors: Preview or manage saved monitoring; creation, updates and delivery actions require authorization.
response_mode="compact" is the default chat projection: identifiers, evidence, returned URLs/images, coverage and filters remain explicit. A compact list page requests only the records it shows, so next_cursor continues after the last record shown; _mcp_projection reports requested_limit and applied_limit when it asked for fewer. response_mode="full" preserves the bounded API response at the requested limit. Neither mode retrieves other pages. A sample does not establish totals or complete coverage.
Cite returned GDELT Cloud record links, original publisher evidence and dataset attribution. Missing links/images remain missing. Research uses native chat text, tables and client-supported charts; account navigation and the editable Monitor form are the dedicated app components.
Categories
GDELT Cloud
gdelt_cloud · Core
Structured GDELT Cloud events and real-world dynamics — what happened, who did it, where, how often. Clustered stories, Situations, country context, publication activity and Monitors. For any named person, organization, place or facility, resolve first with unified_entity_search (with country_match=strict when you know the country), inspect the candidates, then call the destination tool with the selected id. Cite public GDELT Cloud Story/Entity URLs when returned; never fabricate URLs.
Use the advertised operation schema for exact inputs and output shapes. Discover unfamiliar choices with
get_parameter_options.
Media Intelligence
media_intel · Core
How an entity is covered by the press — tone over time and share of voice against a peer set. Plan-gated; preserve the denominator and unavailable coverage. Related: gdelt_cloud for reported Events and Stories.
Use the advertised operation schema for exact inputs and output shapes. Discover unfamiliar choices with
get_parameter_options.
Facilities
facilities · Core
The unified physical-asset directory — power plants, mines, mineral processing, factories, ports and data centers, with contributing source observations and resolved participant roles. Read published coverage and geographic evidence; ownership alone does not identify a site. Plan-gated (can_use_facilities). Related: energy and Epoch for native details.
Use the advertised operation schema for exact inputs and output shapes. Discover unfamiliar choices with
get_parameter_options.
Government
gov · Open Feeds
US federal awards and foreign-influence registrations, resolved onto the entity spine.
Use the advertised operation schema for exact inputs and output shapes. Discover unfamiliar choices with
get_parameter_options.
Political Offices
offices · Open Feeds
Public political offices and who held them, with the office start/end dates the publisher states (valid time), resolved onto the entity spine. Actor context for geopolitical analysis, not a PEP or sanctions screen. Reach the holders of an office through office= on the gdelt_cloud event and story tools.
Use the advertised operation schema for exact inputs and output shapes. Discover unfamiliar choices with
get_parameter_options.
Filings
filings · Open Feeds
SEC EDGAR — the filing index, XBRL financials, and relations extracted from filing text.
Use the advertised operation schema for exact inputs and output shapes. Discover unfamiliar choices with
get_parameter_options.
Legal Entities
gleif · Open Feeds
The GLEIF Global LEI Index — legal-entity reference data, consolidation relationships and LEI↔ISIN mappings.
Use the advertised operation schema for exact inputs and output shapes. Discover unfamiliar choices with
get_parameter_options.
Energy
energy · Open Feeds
Global Energy Monitor assets and the ownership registry over them.
Use the advertised operation schema for exact inputs and output shapes. Discover unfamiliar choices with
get_parameter_options.
AI Compute
epoch · Open Feeds
Epoch AI — models, hardware, data centers, companies, chip sales and selected GPU-cluster and chip ownership/use/component observations. Preserve participant roles, native units and uncertainty. CC-BY 4.0; plan-gated. Related: facilities for unified sites; gdelt_cloud for linked entity context.
Use the advertised operation schema for exact inputs and output shapes. Discover unfamiliar choices with
get_parameter_options.
Natural Resources
resources · Open Feeds
USGS mineral production, reserves and qualified observations by commodity, source, reference year and shared country/region/continent filters. Request full-filter count facets with include_summary; individual values keep their native units and qualifiers.
Use the advertised operation schema for exact inputs and output shapes. Discover unfamiliar choices with
get_parameter_options.
Macro Finance
macro · Open Feeds
FRED economic series, with true point-in-time vintages rather than the latest revision.
Use the advertised operation schema for exact inputs and output shapes. Discover unfamiliar choices with
get_parameter_options.
Risk and Screening
risk · Open Feeds
Restricted-party lists, name screening, ownership-chain exposure and China development finance. Discover currently ingested original-publisher sources, including our OpenSanctions-derived crawler lane, with lists_catalog before selecting a source_key. List categories distinguish sanctions from debarment and other screening signals. Analytical coverage, not an audit-grade compliance control.
Use the advertised operation schema for exact inputs and output shapes. Discover unfamiliar choices with
get_parameter_options.
Maritime
maritime · Open Feeds
AIS-derived vessel flow — chokepoint transits, port dwell, dark gaps and last-known offices. Terrestrial AIS only, so coverage thins in open ocean.
Use the advertised operation schema for exact inputs and output shapes. Discover unfamiliar choices with
get_parameter_options.
Web Research
web_research · Supporting research
Supporting web research only: orientation for GDELT Cloud tasks, corroboration or source extraction. Requires purpose and task_context. Basic depth; five results or three URLs maximum. At most two searches and one extraction batch per task. Standalone web research is unsupported.
Use the advertised operation schema for exact inputs and output shapes. Discover unfamiliar choices with
get_parameter_options.
Monitor workflow
- Resolve a named subject with
unified_entity_search; clarify consequential ambiguity. - For an editable review, call
gdelt_cloud_monitor_formwith validatedpreview_monitorparameters. Preview saves nothing and sends no delivery. - Review matches, applied filters and coverage. Mention/link evidence is not material involvement or actor attribution.
- After explicit confirmation, call
create_monitor; paused and running are separate choices. update_monitorchanges settings;set_monitor_enabledpauses/resumes;batch_monitorsperforms the requested batch action. These are mutations with host approval.configure_monitor_deliveryconfigures email/webhook delivery;test_monitor_deliverysends a test. Signing secrets belong in secure integration storage, not chat.run_monitor_nowpersists a manual test run, sends no notification, and does not advance the scheduled checkpoint. Inspectlist_monitor_runs,get_monitor_runandget_monitor_run_matches.
total_matches_is_lower_bound, count_truncated and candidate_limit. Result rows are bounded samples; returned counts are execution counts. Incomplete coverage cannot establish a quiet interval or completed checkpoint.
For exact replay, retain each returned replay_request and its documented scope, filters and time basis. A widened day-bounded request alone is not the exact scheduler window. Honor exact_window_filter and pagination.next_cursor; do not invent unsupported recorded-time parameters. See Monitors and Monitor webhooks.
Supporting web research
supporting_web_search and extract_source_pages require purpose and task_context for a GDELT Cloud task. Basic depth only, at most five search results or three extraction URLs. Agent guidance limits a task to two searches and one extraction batch; stop earlier when sufficient. Standalone web research is unsupported.
Usage and access
Data operations use the same account access and usage admission as the underlying API.get_data_catalog, get_parameter_options and get_event_taxonomy are free local metadata. Access failures explain unavailability rather than returning misleading empty data. Monitor and saved-query tools cost what their REST call costs: setup, reads, edits and deletes are free, scheduled checks cost no Query Units, and a Preview or a manual run costs 1 QU when it executes.
Wrapper compatibility profile
Clients explicitly using the legacy wrapper profile discover each domain through these tools. They are not the current public named-tool surface.
Authorized mutations use
gdelt_cloud_tool_write in that profile. A read wrapper cannot execute mutations. Retired integrations are absent from both profiles.
