# auth.md - AI Agent Authentication Guide

> Authentication, registration, and discovery guide for AI assistants and autonomous coding agents connecting to ThumbnailGPT.

## Overview

ThumbnailGPT integrates with AI agents and coding assistants via:
1. **Model Context Protocol (MCP)**: For IDE assistants (Cursor, Claude Desktop, Windsurf, Antigravity).
2. **Command Line Interface (CLI)**: For terminal automation and scripts (`npx thumbnailgpt`).
3. **Web Studio**: Direct creator interface at https://thumbnailgpt.com/studio.

*(Note: ThumbnailGPT authenticates agent workflows using Personal API keys via MCP or CLI, and supports standard OAuth Protected Resource Metadata discovery).*

---

## 1. Authentication Credentials & Agent Registration

AI agents and automated tools authenticate using a **Personal API Key**:

- **Key Format**: `tgpt_live_xxxxxxxxxxxxxxxx`
- **Generate Key**: Obtain your key from your user settings at [https://thumbnailgpt.com/studio?settings=api-key](https://thumbnailgpt.com/studio?settings=api-key).
- **Web Sign-in**: Accounts are created via email or social login at [https://thumbnailgpt.com/login](https://thumbnailgpt.com/login).
- **Agent Registration Endpoint**: `https://thumbnailgpt.com/api/api-keys`
- **Supported Identity Types**: `autonomous_agent`, `user_delegated`, `service_auth`, `anonymous`
- **Supported Credential Types**: `api_key`, `bearer`

---

## 2. Connecting AI Coding Assistants via MCP

Connect Cursor, Claude Desktop, or Windsurf to ThumbnailGPT:

- **Server URL**: `https://mcp.thumbnailgpt.com`
- **Transport**: Streamable HTTP
- **Authentication**: Bearer API key in headers

### Cursor Configuration (`.cursor/mcp.json`)
```json
{
  "mcpServers": {
    "thumbnailgpt": {
      "url": "https://mcp.thumbnailgpt.com",
      "headers": {
        "Authorization": "Bearer tgpt_live_YOUR_API_KEY_HERE"
      }
    }
  }
}
```

### Claude Desktop Configuration (`claude_desktop_config.json`)
```json
{
  "mcpServers": {
    "thumbnailgpt": {
      "url": "https://mcp.thumbnailgpt.com",
      "headers": {
        "Authorization": "Bearer tgpt_live_YOUR_API_KEY_HERE"
      }
    }
  }
}
```

### Windsurf Configuration
```json
{
  "mcpServers": {
    "thumbnailgpt": {
      "serverUrl": "https://mcp.thumbnailgpt.com",
      "headers": {
        "Authorization": "Bearer tgpt_live_YOUR_API_KEY_HERE"
      }
    }
  }
}
```

---

## 3. CLI Automation (`npx thumbnailgpt`)

Agents with shell/terminal execution capabilities can run commands directly:

```bash
# Authenticate
npx thumbnailgpt login --key tgpt_live_YOUR_API_KEY

# Check status and available credits
npx thumbnailgpt whoami

# Generate a 2K YouTube thumbnail
npx thumbnailgpt generate "Extreme 100 Days Hardcore Survival in Minecraft" --res 2K
```

---

## 4. Discovery & OAuth Endpoints

- **OAuth Protected Resource Metadata (RFC 9728)**: `https://thumbnailgpt.com/.well-known/oauth-protected-resource`
- **OAuth Authorization Server Metadata (RFC 8414)**: `https://thumbnailgpt.com/.well-known/oauth-authorization-server`
- **OpenID Configuration**: `https://thumbnailgpt.com/.well-known/openid-configuration`
- **JWKS Endpoint**: `https://thumbnailgpt.com/.well-known/jwks.json`
- **MCP Server Card**: `https://thumbnailgpt.com/.well-known/mcp/server-card.json`
- **Agent Skills Discovery**: `https://thumbnailgpt.com/.well-known/agent-skills/index.json`
- **ARD Capability Catalog**: `https://thumbnailgpt.com/.well-known/ai-catalog.json`

---

## 5. Contact & Support

- **Settings**: https://thumbnailgpt.com/studio?settings=api-key
- **Documentation**: https://thumbnailgpt.com/docs
- **Support**: support@thumbnailgpt.com
