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

# Plugins

> One command wires both MCP servers and eight skills into Claude Code, Codex or Cursor.

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.

<Tabs>
  <Tab title="Claude Code">
    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:

    ```bash theme={null}
    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.
  </Tab>

  <Tab title="Codex">
    From a shell:

    ```bash theme={null}
    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`.
  </Tab>

  <Tab title="Cursor">
    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.
  </Tab>
</Tabs>

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

<Warning>
  **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.
</Warning>

## 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](/mcp/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:

<CodeGroup>
  ```text Claude Code theme={null}
  /plugin marketplace add gdelt-cloud/plugins
  /plugin install gdelt-cloud-docs@gdelt-cloud
  ```

  ```bash Codex theme={null}
  codex plugin marketplace add gdelt-cloud/plugins
  codex plugin add gdelt-cloud-docs@gdelt-cloud
  ```
</CodeGroup>

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`:

```bash theme={null}
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:

<CodeGroup>
  ```json Claude Code — .mcp.json theme={null}
  {
    "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"
      }
    }
  }
  ```

  ```toml Codex — ~/.codex/config.toml theme={null}
  [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"
  ```
</CodeGroup>

<Warning>
  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.
</Warning>

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

<AccordionGroup>
  <Accordion title="The plugin lists but no tools show up" icon="triangle-exclamation">
    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.
  </Accordion>

  <Accordion title="The tools appear but every call is rejected" icon="lock">
    The client connected and authentication did not. Confirm the key is live and unrevoked at
    [gdeltcloud.com/api-keys](https://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.
  </Accordion>

  <Accordion title="A call returns a plan error" icon="circle-info">
    Working as intended: that endpoint is not in your plan. The error names the flag it needs — see the
    [error reference](/reference/errors). It is deliberately not an empty result, which would be
    indistinguishable from missing data.
  </Accordion>

  <Accordion title="Only documentation tools appear" icon="book">
    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](/mcp/overview).
  </Accordion>
</AccordionGroup>

<CardGroup cols={2}>
  <Card title="Any other MCP client" icon="puzzle-piece" href="/mcp/integrations">
    Claude, ChatGPT, LangChain and the raw URL, with no plugin involved.
  </Card>

  <Card title="Turn a standing question into a Monitor" icon="radar" href="/guides/monitors">
    What the `hosted-monitors` skill teaches, written out: scheduled checks instead of polling.
  </Card>
</CardGroup>