AI Agents - Advuna

Quick Start

1. Get your API key

Sign up and create an API key from your dashboard.

2. Configure your MCP client

Add Advuna to your Claude Desktop or MCP-compatible client:

{
  "mcpServers": {
    "advuna": {
      "url": "https://advuna.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

3. Start creating

Ask Claude to create ad creatives from any website URL!

Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer adv_your_api_key_here

API keys start with adv_ and should be kept secret. Never commit them to version control.

Human Intervention Required

Some operations require a human to complete the action in a browser:

Action	Tool	Human Must Do
Subscribe	advuna_get_checkout_url	Complete payment in browser

Note: Lost API keys can be recovered via email using advuna_request_key_recovery + advuna_complete_key_recovery. If the AI agent has email access, this flow is fully automated.

Available Tools (18)

Account Tools

advuna_get_account

Get current user account information, subscription status, and usage limits

advuna_create_account

Create a new Advuna account. Returns an API key. No auth required.

`email` *	string	Email address
`password` *	string	Password (min 6 chars)

advuna_list_api_keys

List all API keys for your account (shows prefix only, not full key)

advuna_regenerate_api_key

Generate a new API key. Optionally revoke an existing key.

`name` *	string	Name for the new key
`revoke_prefix`	string	Revoke key with this prefix

advuna_request_key_recovery

Request a recovery code to generate a new API key. No auth required.

email * string Email address of the account

advuna_complete_key_recovery

Complete key recovery with email code. Returns new API key. No auth required.

`email` *	string	Email address of the account
`code` *	string	6-digit recovery code from email

advuna_get_checkout_url

Get the Paddle checkout URL to upgrade subscription

plan string 'monthly' or 'yearly' (default: monthly)

Project Tools

advuna_create_project

Create a new project from a URL. Automatically scrapes website, extracts brand, generates copy, and renders ad creatives.

`url` *	string	Website URL to scrape
`name`	string	Optional project name

advuna_list_projects

List all projects

`page`	integer	Page number (default: 1)
`per_page`	integer	Results per page (default: 20)
`status`	string	Filter by status

advuna_get_project

Get full project details including brand, copy, and creative counts

project_id * integer Project ID

advuna_update_brand

Optional: Customize auto-extracted brand settings (name, slogan, colors)

`project_id` *	integer	Project ID
`brand_name`	string	Brand name
`slogan`	string	Slogan/tagline
`brand_colors`	array	Hex color codes
`confirm`	boolean	Confirm brand (default: true)

advuna_delete_project

Delete a project and all associated data

project_id * integer Project ID

Creative Tools

advuna_generate_creatives

Regenerate creatives with specific templates or sizes (creatives are auto-generated on project creation)

`project_id` *	integer	Project ID
`templates`	array	Templates to generate: bold_stacked, bold_statement, split, stock_fullbleed, stock_gradient, stock_split, stock_textbar
`sizes`	array	Specific sizes to generate

advuna_list_creatives

List all creatives for a project

`project_id` *	integer	Project ID
`template`	string	Filter by template
`status`	string	Filter by status
`page`	integer	Page number (default: 1)
`per_page`	integer	Results per page (default: 20, max: 100)

advuna_get_creative

Get details of a specific creative

`project_id` *	integer	Project ID
`creative_id` *	integer	Creative ID

advuna_regenerate_creative

Re-render a specific creative

`project_id` *	integer	Project ID
`creative_id` *	integer	Creative ID

advuna_update_creative

Update creative copy selection

`project_id` *	integer	Project ID
`creative_id` *	integer	Creative ID
`headline_id`	integer	Headline copy ID
`description_id`	integer	Description copy ID
`cta_id`	integer	CTA copy ID

advuna_delete_creative

Delete a specific creative

`project_id` *	integer	Project ID
`creative_id` *	integer	Creative ID

Job Tools

advuna_get_job_status

Check the status of an async job (project, creatives)

job_id * string Job ID (e.g., 'project_123')

Response Format

Success Response

{
  "success": true,
  "data": {
    "project_id": 123,
    "status": "scraping"
  },
  "message": "Project created successfully"
}

Async Operation

{
  "success": true,
  "data": {
    "job_id": "project_123",
    "status": "processing"
  },
  "message": "Poll advuna_get_job_status to check progress."
}

Error Response

{
  "success": false,
  "error": {
    "code": "limit_exceeded",
    "message": "Preview mode limited to 1 project.",
    "action": "Subscribe for unlimited."
  }
}

Error Codes

Code	Description
unauthorized	Invalid or missing API key
forbidden	Action not allowed for this user
not_found	Resource does not exist
validation_error	Invalid parameters
limit_exceeded	Usage limit reached
subscription_required	Feature requires paid plan
rate_limited	Too many requests

Rate Limits

100 requests/minute - General operations
10 requests/minute - Expensive operations (create_project, generate_creatives)
3 requests/hour - Key recovery operations (request_key_recovery, complete_key_recovery)

Rate limits are per API key (or IP for unauthenticated endpoints). Exceeding limits returns a 429 status with a Retry-After header.

Example Workflow

Creating ads is fully automated. Just create a project and wait for completion — brand extraction, copy generation, and creative rendering all happen automatically.

1

Create a project

advuna_create_project(url: "https://example.com")

2
Poll for completion

The project automatically progresses through scraping → generating copy → rendering creatives.
```
advuna_get_job_status(job_id: "project_123")
```
3
List and download creatives

Once status is previews_ready or completed, your ads are ready.
```
advuna_list_creatives(project_id: 123)
```

Optional: Use advuna_update_brand to customize brand settings or advuna_update_creative to change copy selections before downloading.

Connect AI Agents