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

# Authentication

> Authenticate with GDELT Cloud MCP server using API keys

The GDELT Cloud MCP server uses bearer token authentication with API keys. This provides secure, programmatic access for AI agents, development tools, and automated workflows.

<Info>
  All MCP connections use bearer authentication with API keys. Generate your key from the [GDELT Cloud Dashboard](https://gdeltcloud.com/dashboard).
</Info>

## Generate API Key

<Steps>
  <Step title="Access dashboard">
    Navigate to [GDELT Cloud Dashboard](https://gdeltcloud.com/dashboard) and sign in.
  </Step>

  <Step title="Navigate to API Keys">
    Click **API Keys** in the sidebar navigation.
  </Step>

  <Step title="Create new key">
    Click **"Create New Key"** and provide:

    * **Name**: Descriptive label (e.g., "Claude Desktop", "LangChain Agent")
    * **Expiration** (optional): Set expiration for enhanced security
  </Step>

  <Step title="Save your key">
    Your API key is displayed only once. Copy and store it securely.

    ```
    gdelt_sk_a1b2c3d4e5f6...
    ```

    <Warning>
      You cannot retrieve the key again. If lost, you must revoke and create a new one.
    </Warning>
  </Step>
</Steps>

## API Key Format

GDELT Cloud API keys follow this format:

```
gdelt_sk_<64-hexadecimal-characters>
```

## Using with MCP Clients

### Claude Desktop

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "gdelt-cloud": {
      "url": "https://gdelt-cloud-mcp.fastmcp.app/mcp",
      "auth": {
        "type": "bearer",
        "token": "${GDELT_API_KEY}"
      }
    }
  }
}
```

Set environment variable:

```bash theme={null}
export GDELT_API_KEY=gdelt_sk_your_key_here
```

### Cursor IDE

Add to `mcp-config.json`:

```json theme={null}
{
  "mcpServers": {
    "gdelt-cloud": {
      "url": "https://gdelt-cloud-mcp.fastmcp.app/mcp",
      "auth": {
        "type": "bearer",
        "token": "${GDELT_API_KEY}"
      }
    }
  }
}
```

### Python with FastMCP

```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:
    tools = await client.get_tools()
```

### LangChain

```python theme={null}
from langchain_mcp_adapters.client import MultiServerMCPClient
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']}"
        }
    }
})
```

## Environment Variables

<Tabs>
  <Tab title=".env file">
    ```bash .env theme={null}
    GDELT_API_KEY=gdelt_sk_your_key_here
    ```

    Load in your application:

    ```python theme={null}
    from dotenv import load_dotenv
    load_dotenv()
    ```
  </Tab>

  <Tab title="Shell profile">
    Add to `~/.zshrc` or `~/.bashrc`:

    ```bash theme={null}
    export GDELT_API_KEY=gdelt_sk_your_key_here
    ```
  </Tab>

  <Tab title="Docker">
    ```dockerfile theme={null}
    ENV GDELT_API_KEY=${GDELT_API_KEY}
    ```

    Pass at runtime:

    ```bash theme={null}
    docker run -e GDELT_API_KEY=gdelt_sk_... myapp
    ```
  </Tab>
</Tabs>

## Managing Keys

### Revoke Keys

<Steps>
  <Step title="Open API Keys">
    Navigate to [Dashboard](https://gdeltcloud.com/dashboard) → **API Keys**
  </Step>

  <Step title="Click Revoke">
    Find the key and click **"Revoke"**

    <Warning>
      Revocation is immediate. All applications using this key will lose access.
    </Warning>
  </Step>
</Steps>

### Key Rotation

Best practice: rotate keys every 90 days.

<Steps>
  <Step title="Create new key">
    Generate a new key with descriptive name.
  </Step>

  <Step title="Update applications">
    Update environment variables in all services.
    Test thoroughly before revoking old key.
  </Step>

  <Step title="Revoke old key">
    After confirming new key works, revoke the old one.
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="MCP Tools" icon="wrench" href="/mcp/tools/progressive-discovery">
    Explore the Progressive Discovery wrapper and v2 GDELT Cloud catalog
  </Card>

  <Card title="Code References" icon="book" href="/mcp/resources/codes">
    CAMEO, Conflict, CAMEO+, and Goldstein interpretation
  </Card>

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