GDELT Cloud Docs — Global Event Data API & MCP

The MCP server gives your agent the data. The plugin gives it the data and the procedures for using it correctly, from one marketplace, for three coding agents:

github.com/gdelt-cloud/plugins

It is a normal public repository. One skills directory serves all three clients — only the manifests and the MCP config differ.

Install

Two steps everywhere: register the marketplace, then install the plugin from it. Registering alone leaves the plugin listed and not installed, which looks identical to a broken install.

Claude Code
Codex
Cursor

Inside a session:

/plugin marketplace add gdelt-cloud/plugins
/plugin install gdelt-cloud@gdelt-cloud

You are asked for an API key on enable. Or non-interactively, from a shell:

claude plugin marketplace add gdelt-cloud/plugins
claude plugin install gdelt-cloud@gdelt-cloud --config gdelt_api_key=gdelt_sk_...

Verify with /mcp inside a session: gdelt-cloud and gdelt-cloud-docs should both list as connected.

From a shell:

codex plugin marketplace add gdelt-cloud/plugins
codex plugin add gdelt-cloud@gdelt-cloud
export GDELT_API_KEY=gdelt_sk_...

codex plugin add is not optional. marketplace add only registers the source — run codex plugin list after it and the plugin reads not installed until the second command runs.Codex has no ${...} interpolation in its config, so the plugin declares the name of an environment variable and reads the key from there rather than prompting. Export GDELT_API_KEY before starting Codex, in whatever shell profile Codex inherits.Verify with codex plugin list — the row should read installed, enabled.

Cursor installs from its dashboard under Plugins rather than from a CLI, pointed at the same repository. It declares user-supplied values as a JSON Schema and interpolates them as ${GDELT_API_KEY}.The skills are the same five files the other two clients get.

Create a key first at gdeltcloud.com/api-keys, and see API keys for what a key is scoped to and how calls are metered.

Restart the session after installing. MCP servers are connected at startup. Until you restart, the tools are simply absent — which reads as a failed install rather than a pending one.

What comes with it

Two MCP servers, wired together:

Server	Auth	What it answers
`gdelt-cloud`	your API key	events, stories, entities, tone, assets — the world
`gdelt-cloud-docs`	none	this site and the OpenAPI spec — how to ask

Plus eight skills. The first four are the general ones, read in this order; the last four are worked workflows you can lift from.

Skill	For
`getting-started`	The rules that decide whether a call is correct, plus bulk downloads. Every other skill assumes it.
`core-api`	Maps a plain-English ask onto the right endpoint and the minimal correct call.
`building-with-the-api`	Writing code against it: paging to the end, truncated versus empty, caching, cadence, stability.
`hosted-monitors`	Standing queries: subjects, preview before save, paging a run, signed webhooks, cost.
`war-risk-underwriting`	Chokepoint and route monitors, political-violence exposure, marine war-risk briefs.
`counterparty-exposure`	Company → hierarchy → assets → news → filings → government exposure.
`supplier-disruption`	N suppliers × M sites, daily digest with an escalation threshold.
`country-risk-series`	Atlas GPR and Posture as a frame you can join to returns.

They exist because most ways of getting this API wrong return 200 with a plausible result rather than an error — a swapped bbox axis order, a summary endpoint quietly ignoring a filter its list sibling honours, an identifier from the wrong id space answering with an empty page. Each skill front-loads the ones that matter for its job.

Two different things are called skills

They are not the same mechanism and they install in different places.

	Where it lives	How it loads
Plugin skills (this page)	in your agent, from the marketplace	your agent matches them against what you asked
MCP server skills	on the MCP server	the server offers one when a question matches

You can have either, or both. Neither is invoked by name.

Documentation only

If you only want your agent to read the API reference while it writes your code, install the documentation plugin instead. No key, no signup:

/plugin marketplace add gdelt-cloud/plugins
/plugin install gdelt-cloud-docs@gdelt-cloud

codex plugin marketplace add gdelt-cloud/plugins
codex plugin add gdelt-cloud-docs@gdelt-cloud

It wires the documentation server alone and ships no skills.

Wire it by hand

If the marketplace is unavailable, or you want the skills in one project without installing a plugin, the pieces are ordinary files. Skills are plain directories, each holding a SKILL.md:

git clone https://github.com/gdelt-cloud/plugins /tmp/gdelt-cloud-plugins
mkdir -p .claude/skills
cp -R /tmp/gdelt-cloud-plugins/plugins/gdelt-cloud/skills/* .claude/skills/
export GDELT_API_KEY=gdelt_sk_...

Then declare the servers where your client reads them. The two schemas are not interchangeable:

{
  "mcpServers": {
    "gdelt-cloud": {
      "type": "http",
      "url": "https://gdelt-cloud-mcp.fastmcp.app/mcp",
      "headers": { "Authorization": "Bearer ${GDELT_API_KEY}" }
    },
    "gdelt-cloud-docs": {
      "type": "http",
      "url": "https://docs.gdeltcloud.com/mcp"
    }
  }
}

[mcp_servers.gdelt_cloud]
url = "https://gdelt-cloud-mcp.fastmcp.app/mcp"
bearer_token_env_var = "GDELT_API_KEY"

[mcp_servers.gdelt_cloud_docs]
url = "https://docs.gdeltcloud.com/mcp"

Three ways a hand-written config fails silently, all of them answering with an authentication error that says nothing about the real cause:

Omitting "type": "http" on a remote server. Claude Code reads it as a stdio server, finds no command to run, and skips it. No error, no tools.
Writing ${user_config.gdelt_api_key} in a file you wrote yourself. That form is resolved by the plugin system and by nothing else; here it is sent as a literal string. Use ${GDELT_API_KEY}.
Putting the key itself in bearer_token_env_var. It takes the name of an environment variable, not its value — a key pasted there is looked up as a variable name, matches nothing, and the request goes out unauthenticated.

Do not name the file .mcp.json inside a plugin you are publishing: Claude Code and Codex both auto-discover that filename with incompatible schemas. That is why the repository ships .mcp.claude.json, .mcp.codex.json and .mcp.cursor.json side by side.

If the tools do not appear

The plugin lists but no tools show up

Almost always the session was not restarted, or codex plugin add was never run after codex plugin marketplace add. Check the plugin’s status first (/mcp in Claude Code, codex plugin list in Codex) — a plugin reading not installed is a marketplace that was registered and never installed from.

The tools appear but every call is rejected

The client connected and authentication did not. Confirm the key is live and unrevoked at gdeltcloud.com/api-keys, and that the environment variable is visible to the process that starts your agent rather than only to your interactive shell.

A call returns a plan error

Working as intended: that endpoint is not in your plan. The error names the flag it needs — see the error reference. It is deliberately not an empty result, which would be indistinguishable from missing data.

Only documentation tools appear

You installed gdelt-cloud-docs rather than gdelt-cloud, or only the docs server connected. They are different servers with different jobs — see the MCP overview.

Any other MCP client

Claude, ChatGPT, LangChain and the raw URL, with no plugin involved.

Turn a standing question into a Monitor

What the hosted-monitors skill teaches, written out: scheduled checks instead of polling.

​Install

​What comes with it

​Two different things are called skills

​Documentation only

​Wire it by hand

​If the tools do not appear

Any other MCP client

Turn a standing question into a Monitor

Install

What comes with it

Two different things are called skills

Documentation only

Wire it by hand

If the tools do not appear