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

# Answer a question with MCP

> The analyst path: connect once, then work in plain language with citations you can check.

You do not need to write code to use GDELT Cloud. Connect the MCP server to Claude, ChatGPT or your
own agent, and ask in plain language — the model picks the endpoints, and every claim comes back with
the articles behind it.

This page walks one real question end to end.

<Steps>
  <Step title="Connect (about two minutes)">
    Add the server URL to your client and authenticate with your API key. Setup is three lines of config
    per client and is written out in [Integrations](/mcp/integrations).

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

    You are connected when the model can list the GDELT Cloud tools.
  </Step>

  <Step title="Start wide, not narrow">
    > *"What's been happening with energy infrastructure in Nigeria over the past two weeks?"*

    Ask the broad version first. The model will call a summary endpoint, which returns counts grouped by
    date, geography and category — the shape of the period rather than a list of rows.

    **This is the step people skip, and skipping it is the single biggest source of wrong answers.** Go
    straight to a narrow filtered query and an empty result looks like "nothing happened" when it
    actually means "that combination of filters matched nothing." The summary tells you where the volume
    actually is before you commit to a filter.
  </Step>

  <Step title="Drill into what the summary surfaced">
    > *"Show me the most significant ones, with sources."*

    Now the narrowing is grounded in something you have seen. The model filters to the categories and
    places that actually carried volume, and ranks by significance — the blended score the product sorts
    by, which is designed to compare events across domains rather than within one.
  </Step>

  <Step title="Check the evidence">
    > *"What are the underlying articles for the third one?"*

    Every event traces back to the story it was coded from, and every story to its source articles with
    URLs and publication dates. **Ask for this every time.** An event is our reading of a cluster of
    coverage; the articles are what that reading was based on, and they are how you tell a well-supported
    event from a thin one.

    Two signals worth checking: how many articles back the story, and whether they are independent
    outlets or one wire story republished.
  </Step>

  <Step title="Widen to the entity">
    > *"Does this company have US federal contracts or sanctions exposure?"*

    Once an entity is named, the same resolved identity reaches government awards, corporate filings,
    ownership-chain exposure and physical assets. This is the part that is hard to do by hand: the model
    resolves the name once and reuses that identity everywhere, so the answer does not silently cover
    only the surfaces where the name happened to be spelled the same way.
  </Step>
</Steps>

## What to trust, and how far

<AccordionGroup>
  <Accordion title="An absent number is not a zero" icon="circle-half-stroke">
    When coverage was not found, the API returns `null` rather than `0`. If a model reports "no negative
    coverage," check whether that means *measured and none* or *not measured*. The distinction is
    preserved in the data specifically so it can be preserved in the answer.
  </Accordion>

  <Accordion title="Tone measures press coverage, not public opinion" icon="newspaper">
    It is scored across news articles. A country with little coverage has little tone data — that is a
    statement about the press, not about the country.
  </Accordion>

  <Accordion title="History does not run all the way back" icon="calendar">
    Coverage starts partway through 2026 and is being backfilled; before that it is thin enough to be
    misleading. A query reaching further back returns a near-empty result that looks like a bug. The
    window is in [Coverage](/concepts#coverage), and the exact span and cadence per dataset are in the
    [data catalog](/data/catalog).
  </Accordion>

  <Accordion title="Ask what the metric does not claim" icon="ruler">
    Each event metric has a published list of what it explicitly does not measure — the most common
    misreading is treating market sensitivity as a severity score. See
    [worked examples](/metrics/worked-examples) for two real events scored by hand.
  </Accordion>
</AccordionGroup>

## The same question through the API

If you would rather script it, the identical flow is four HTTP calls — summarize, drill, fetch
articles, fan out — in [Build a monitoring feed](/guides/for-developers).

## Next

<CardGroup cols={2}>
  <Card title="Connect your client" icon="plug" href="/mcp/integrations">
    Claude, Claude Code, ChatGPT, Codex, LangChain.
  </Card>

  <Card title="Data catalog" icon="database" href="/data/catalog">
    What is ours, what we ingest, and what each source does not cover.
  </Card>
</CardGroup>