> ## 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

> Connect Claude, ChatGPT or your own agent to GDELT Cloud in about two minutes.

The MCP server exposes GDELT Cloud to any model that speaks the Model Context Protocol. It is the
same data and the same entitlements as the REST API — the server routes to the same serve functions,
so an answer you get through MCP is one you could have got with `curl`.

```
https://gdelt-cloud-mcp.fastmcp.app/mcp
```

Authenticate with your GDELT Cloud API key. Per-client setup is in
[Integrations](/mcp/integrations).

<Card title="Walk through a real question" icon="compass" href="/guides/for-analysts">
  Connect, ask broadly, drill down, check the citations — one question end to end.
</Card>

## How the tools are organised

**There is no single `tool_list`.** Tools are grouped into categories, and each category exposes its
own three-tool trio:

```
<category>_tool_list                          what is in this category
<category>_tool_get(tool_name=…)              that tool's parameters, types and value lists
<category>_tool_call(tool_name=…, …)          run it
```

So the events tools are reached through `gdelt_cloud_tool_list` / `_tool_get` / `_tool_call`, the
vessel tools through `maritime_tool_*`, and so on.

**Picking the category is the model's first decision**, and it is the one most worth getting right —
`gdelt_cloud` is the anchor for anything about events, actors or dynamics, while the other categories
are registries you consult once you know what you are looking for.

<Info>
  This is progressive discovery, and it exists for a specific reason: there are far more underlying
  tools than any model should carry in its context, and their value lists alone run past a thousand
  entries. Advertising three tools per category instead means a model fetches one schema, on demand,
  for the one tool it is about to use.
</Info>

The rule that follows: **call `_tool_get` before the first `_tool_call` to a tool you have not used
in this conversation.** Guessing a parameter name is the most common failure mode, and the server
rejects unknown filters rather than silently ignoring them — which is the right behaviour, but only
helps if you read the error.

<Card title="Every category and every tool" icon="wrench" href="/mcp/tools">
  The full surface, generated from the same declaration the docs and the API reference share.
</Card>

## What is metered

A `_tool_call` costs the same as the REST call it makes and appears in the same usage reporting.
`_tool_list` and `_tool_get` are discovery and are 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

The server also carries enrichment tools that call third-party providers — macro series, prediction
markets and web research. Those are vendor contracts rather than our data, and they are described in
[External tools](/mcp/external-tools).

<CardGroup cols={2}>
  <Card title="Integrations" icon="puzzle-piece" href="/mcp/integrations">
    Claude, Claude Code, ChatGPT, Codex, LangChain.
  </Card>

  <Card title="Skills" icon="graduation-cap" href="/mcp/skills">
    Packaged workflows the server can load on demand.
  </Card>
</CardGroup>