Skip to main content

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.

Overview

LangChain agents can connect to the GDELT Cloud MCP server through langchain-mcp-adapters. The MCP server exposes Progressive Discovery wrappers plus macro-finance, prediction-market, and web-research categories.

Installation

pip install langchain-mcp-adapters langchain-openai langchain

Complete Example

import os
import asyncio
from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain_openai import ChatOpenAI
from langchain.agents import create_agent

async def main():
    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_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 protests in India by day over the past month, then drill into the most significant recent Events."
        }]
    })
    print(result["messages"][-1].content)

asyncio.run(main())

Expected Tool Behavior

The agent should use:
  • gdelt_cloud_tool_list
  • gdelt_cloud_tool_get
  • gdelt_cloud_tool_call
Inside gdelt_cloud_tool_call, it should call v2 tools such as summarize_events, search_events, search_stories, get_story, get_story_articles, search_entities, get_entity, and list_admin1. It should also use:
  • macro_finance_* for market, commodity, FX, rates, and indicator context
  • prediction_market_* for market-implied probabilities
  • web_research_* for corroboration and official/source-page reading

Good Test Prompts

Show protests in India by day over the past month. Give a short analyst read and cite GDELT Cloud records.
Find new data center projects in Asia. Use Stories first, then structured infrastructure Events if available.
What are the fatal conflict Events in Lebanon this week? Keep it concise and cite evidence.
Assess sanctions and market implications from the latest Red Sea shipping signals. Start with GDELT, then use macro-finance and prediction markets if useful.

Best Practices

  • Always include gdelt_system_prompt.
  • Let the model inspect schemas before tool calls.
  • Ask for concise output when building chat UX.
  • Ask for a full brief only when the user wants a report.
  • Preserve IDs, normalized geo, metrics, GDELT Cloud URLs, and article URLs in final answers.

Progressive Discovery

How agents discover and call v2 GDELT tools.

External Tools

Macro finance, prediction markets, and web research.