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

> Connect to GDELT Cloud MCP and call the v2 Progressive Discovery catalog

<Info>
  **MCP Server URL:** `https://gdelt-cloud-mcp.fastmcp.app/mcp`
</Info>

## Quick Setup

<Steps>
  <Step title="Generate an API key">
    Go to **Settings → API Keys** and create a key on a plan with API/MCP access.

    <Warning>Copy your API key immediately. It is shown only once.</Warning>
  </Step>

  <Step title="Connect your MCP client">
    Use bearer authentication with your `gdelt_sk_...` key.
  </Step>

  <Step title="Use Progressive Discovery">
    Call `gdelt_cloud_tool_list`, inspect with `gdelt_cloud_tool_get`, then execute with `gdelt_cloud_tool_call`.
  </Step>
</Steps>

## FastMCP Example

```python theme={null}
from fastmcp import Client
from fastmcp.client.auth import BearerAuth
import os

async with Client(
    "https://gdelt-cloud-mcp.fastmcp.app/mcp",
    auth=BearerAuth(token=os.environ["GDELT_API_KEY"]),
) as client:
    catalog = await client.call_tool("gdelt_cloud_tool_list", {})
    print([tool["name"] for tool in catalog["tools"]])

    schema = await client.call_tool(
        "gdelt_cloud_tool_get",
        {"tool_name": "search_events"},
    )
    print(schema["tool"]["description"])

    result = await client.call_tool(
        "gdelt_cloud_tool_call",
        {
            "tool_name": "search_events",
            "tool_arguments": {
                "category": "Battles",
                "subcategory": "Armed clash",
                "country": "Lebanon",
                "has_fatalities": True,
                "start_date": "2026-04-11",
                "end_date": "2026-04-17",
                "sort": "significance",
                "limit": 5,
            },
        },
    )
    print(result)
```

## LangChain / LangGraph Pattern

```python theme={null}
from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain_openai import ChatOpenAI
from langchain.agents import create_agent
import os

mcp_client = MultiServerMCPClient({
    "gdelt-cloud": {
        "transport": "streamable_http",
        "url": "https://gdelt-cloud-mcp.fastmcp.app/mcp",
        "headers": {
            "Authorization": f"Bearer {os.environ['GDELT_API_KEY']}"
        },
    }
})

tools = await mcp_client.get_tools(server_name="gdelt-cloud")
messages = await mcp_client.get_prompt("gdelt-cloud", "gdelt_research_system_prompt")
gdelt_prompt = "\n\n".join(str(msg.content) for msg in messages)

agent = create_agent(
    model=ChatOpenAI(model="gpt-5.4-mini", temperature=0),
    tools=tools,
    system_prompt=gdelt_prompt,
)

result = await agent.ainvoke({
    "messages": [{
        "role": "user",
        "content": "Show fatal conflict Events in Lebanon this week with citations."
    }]
})
```

## First Calls To Try

Event, Story, and Entity search tools default to the exact past 24 hours. Narrow with geography, category, subcategory, `civilian_targeting`, date windows, and semantic search rather than public confidence modes.

### Protests By Day

```json theme={null}
{
  "tool_name": "summarize_events",
  "tool_arguments": {
    "category": "Protests",
    "subcategory": "Peaceful protest",
    "country": "India",
    "group_by": "date",
    "start_date": "2026-03-19",
    "end_date": "2026-04-17"
  }
}
```

### New Data Center Projects In Asia

```json theme={null}
{
  "tool_name": "search_stories",
  "tool_arguments": {
    "continent": "Asia",
    "search": "new data center projects",
    "article_count_min": 1,
    "start_date": "2026-04-04",
    "end_date": "2026-04-17",
    "sort": "significance"
  }
}
```

### Infrastructure Events

```json theme={null}
{
  "tool_name": "search_events",
  "tool_arguments": {
    "category": "INFRASTRUCTURE",
    "country": "United States",
    "start_date": "2026-04-04",
    "end_date": "2026-04-17",
    "sort": "significance"
  }
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Progressive Discovery" icon="list" href="/mcp/tools/progressive-discovery">
    Learn the wrapper flow and public catalog.
  </Card>

  <Card title="GDELT Cloud v2 Tools" icon="wrench" href="/mcp/tools/gdelt-cloud">
    See Events, Stories, Entities, and geo discovery.
  </Card>

  <Card title="External Tools" icon="sparkles" href="/mcp/tools/external-tools">
    Use macro finance, prediction markets, and web research as enrichment.
  </Card>

  <Card title="LangChain Integration" icon="link" href="/mcp/integrations/langchain">
    Build custom agents with GDELT Cloud MCP.
  </Card>
</CardGroup>