Integrations - GDELT Cloud

Every client below connects to the same endpoint using OAuth or an API key:

https://mcp.gdeltcloud.com/mcp

Claude and ChatGPT sign in through OAuth. For clients using bearer authentication, create a key at gdeltcloud.com/api-keys. Your plan governs which endpoints respond, identically to REST.

Using a coding agent? Claude Code, Codex and Cursor can install the GDELT Cloud plugin instead, which wires this server, the documentation server and eight skills in one command.

Claude
Claude Code
ChatGPT
Codex
LangChain / LangGraph

Claude web and desktop. Settings → Connectors → Add custom connector, paste the server URL, and sign in with your GDELT Cloud account through OAuth, and approve the connection. No API key is needed.Once connected, ask normally — the model discovers the tools itself. Start broad (“what’s happening with…”) rather than naming an endpoint.

claude mcp add --transport http gdelt-cloud https://mcp.gdeltcloud.com/mcp

Then open /mcp inside a session and follow the OAuth sign-in flow. The server should list as connected after authorization.Or install the plugin, which adds the documentation server and eight skills beside it.

export GDELT_API_KEY=gdelt_sk_...
codex mcp add gdelt-cloud \
  --url https://mcp.gdeltcloud.com/mcp \
  --bearer-token-env-var GDELT_API_KEY

That writes ~/.codex/config.toml, where the entry looks like this — edit it there directly if you prefer:

[mcp_servers.gdelt_cloud]
url = "https://mcp.gdeltcloud.com/mcp"
bearer_token_env_var = "GDELT_API_KEY"

bearer_token_env_var takes the name of an environment variable, not the key itself. A gdelt_sk_… pasted there is looked up as a variable name, matches nothing, and the request goes out unauthenticated — a 401 with nothing pointing at the cause. Codex has no ${...} interpolation, so naming the variable is the only way to hand it a secret.

Restart Codex, then verify with codex mcp list.Or install the plugin instead: it wires this server, adds the documentation server beside it, and brings eight skills.

import os
from langchain_mcp_adapters.client import MultiServerMCPClient

client = MultiServerMCPClient({
    "gdelt_cloud": {
        "url": "https://mcp.gdeltcloud.com/mcp",
        "transport": "streamable_http",
        "headers": {"Authorization": f"Bearer {os.environ['GDELT_API_KEY']}"},
    }
})
tools = await client.get_tools()

Bind the named tools to your agent as usual. Use optional catalog, taxonomy and parameter guidance when needed — see Named tools and optional discovery.

If it does not connect

Tools do not appear

The client connected but authentication failed. Check the key is a live GDELT Cloud key (gdelt_sk_…) and has not been revoked at gdeltcloud.com/api-keys.

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.

The model invents a parameter

Ask it to fetch the endpoint description first. The parameter it wants is either in the parameter reference or does not exist — the server rejects unknown filters rather than ignoring them.

Existing connections and rich results

For a new connection, use https://mcp.gdeltcloud.com/mcp. If a client still stores the old endpoint, update its server configuration or add a replacement connection and complete OAuth again. Refresh its tool catalog after a server update; begin a new chat if the client caches an older component. Do not share API keys in chat messages. Custom connection support and MCP Apps rendering are separate client capabilities. A connected client presents research using native text, links, images and tables; chart/map support varies. App blocks are limited to account navigation and Monitor workflows. These components are in client preview; do not assume identical rendering across ChatGPT, Claude and coding clients. A custom connection is not a published directory listing. Signup and subscription recovery happen on GDELT Cloud during the website/OAuth journey. An account card shown after connection only links to signup, plans or account management; it cannot create an account before authentication. A new Free account’s 200 starter calls cover MCP as well as REST; after those, MCP needs a paid plan (Pricing). Read entitlement errors rather than retrying.

​If it does not connect

​Existing connections and rich results

If it does not connect

Existing connections and rich results