MCP Integration

Connect Thumbfa.st to AI assistants like Claude, Cursor, or any MCP-compatible client using the Model Context Protocol.

Getting Your API Key

1. Go to Settings → Developer in your dashboard
2. Click Create API Key
3. Copy your key (starts with tf_)

Keep your API key secret. It provides full access to your account.

Integration Methods

Method 1: Direct HTTPS (Recommended)

For clients that support Streamable HTTP MCP (Claude Desktop 2025+, newer clients):

{
  "mcpServers": {
    "thumbfast": {
      "url": "https://thumbfa.st/api/mcp/mcp",
      "headers": {
        "Authorization": "Bearer tf_your_api_key_here"
      }
    }
  }
}

Method 2: Using mcp-remote (Legacy)

For clients that only support stdio transport (older Claude Desktop, some IDEs):

{
  "mcpServers": {
    "thumbfast": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://thumbfa.st/api/mcp/sse",
        "--header",
        "Authorization: Bearer tf_your_api_key_here"
      ]
    }
  }
}

Client-Specific Setup

Claude Desktop

1. Open Claude Desktop settings
2. Go to Developer → MCP Servers
3. Add configuration:

{
  "mcpServers": {
    "thumbfast": {
      "url": "https://thumbfa.st/api/mcp/mcp",
      "headers": {
        "Authorization": "Bearer tf_abc123..."
      }
    }
  }
}

4. Restart Claude Desktop

Claude Code (CLI)

Add to your project's .mcp.json file:

{
  "mcpServers": {
    "thumbfast": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://thumbfa.st/api/mcp/sse",
        "--header",
        "Authorization: Bearer tf_abc123..."
      ]
    }
  }
}

Cursor

Add to Cursor MCP settings:

{
  "mcpServers": {
    "thumbfast": {
      "url": "https://thumbfa.st/api/mcp/mcp",
      "headers": {
        "Authorization": "Bearer tf_abc123..."
      }
    }
  }
}

Windsurf / Continue.dev

Use the mcp-remote method:

{
  "mcpServers": {
    "thumbfast": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://thumbfa.st/api/mcp/sse",
        "--header",
        "Authorization: Bearer tf_abc123..."
      ]
    }
  }
}

Example Conversation

Once connected, you can interact with Thumbfa.st directly through your AI assistant:

You: Generate a thumbnail with me looking shocked, MrBeast style

Claude: I'll help you create that thumbnail. Let me first check your
available persons and inspirations...

[Calling list_persons...]
[Calling list_inspirations...]

Found your person "John" and a MrBeast-style inspiration.
Now generating the thumbnail...

[Calling generate_thumbnail with personIds and inspirationIds...]

Started generating 1 thumbnail!
- Generation ID: gen_abc123
- Estimated time: ~10 seconds

The thumbnail will appear in your dashboard once ready.

Available Tools

Once connected, your AI assistant has access to these tools:

See the Tools Reference for detailed documentation of each tool.

Troubleshooting

"Unauthorized" error

• Check your API key is correct
• Ensure the key hasn't been revoked
• Verify the Authorization: Bearer prefix

"Connection refused"

• Try the mcp-remote method instead of direct HTTPS
• Check your firewall settings
• Ensure npx is installed (npm install -g npx)

Tools not appearing

• Restart your MCP client after configuration
• Check the MCP server logs for errors
• Verify the JSON syntax in your configuration

Rate limiting

If you're hitting rate limits, consider:

• Reducing the frequency of API calls
• Upgrading your plan for higher limits
• Using batch operations where available

Next Steps

• API Overview - Learn about the REST API
• Tools Reference - Detailed tool documentation