Autonomous AI

How autonomous AI agents can obtain Popmelt credentials programmatically.

tl;dr AI agents can obtain Popmelt MCP credentials through two flows: Device Authorization (interactive, one-time human approval) or Email Registration (fully headless for CI/CD). Both methods return credentials your agent can use immediately.

Why agent registration?

Standard OAuth requires a browser and human interaction during the auth flow itself. That works fine for humans using AI tools like Claude or Cursor, but it doesn't work for autonomous agents running in CI/CD pipelines, server environments, or automated workflows.

Agent registration solves this with two patterns, both returning persistent secret keys:

Method	Best for	Human interaction
Device Authorization	Interactive agent setup where a human can approve once	One-time code entry (any device)
Email Registration	CI/CD, automated deployments, server-to-server	One-time email click

Method 1: Device Authorization Flow

This is the recommended approach when a human can approve the agent once. It's the same pattern used by GitHub CLI, AWS CLI, and Azure CLI.

Step 1: Request a device code

curl -X POST https://mcp.popmelt.com/device/code \
  -H "Content-Type: application/json"

Response:

{
  "device_code": "GmRhmhcxhZA...",
  "user_code": "WDJB-MJHT",
  "verification_uri": "https://popmelt.com/device",
  "verification_uri_complete": "https://popmelt.com/device?code=WDJB-MJHT",
  "expires_in": 900,
  "interval": 5,
  "qr_code": "▄▄▄▄▄▄▄▄▄▄▄...(ASCII QR code)..."
}

Step 2: Direct the user to authorize

Display the user_code and verification_uri to the human operator. They can visit the URL on any device (phone, laptop, etc.) and enter the code.

The response includes a qr_code field containing an ASCII QR code that can be displayed in terminals. Users can scan this with their phone camera to open the verification URL directly.

To authorize this agent, visit: https://popmelt.com/device
Enter code: WDJB-MJHT

Or scan:
▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
█ ▄▄▄▄▄ █▄█ █ █ ▄▄▄▄▄ █
...

The user must be logged into Popmelt and have an active account (not on the waitlist).

Step 3: Poll for authorization

While the user authorizes, poll the token endpoint every interval seconds:

curl -X POST https://mcp.popmelt.com/device/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
    "device_code": "GmRhmhcxhZA..."
  }'

You'll receive one of these responses:

Still waiting:

{
  "error": "authorization_pending",
  "error_description": "User has not yet authorized"
}

Polling too fast:

{
  "error": "slow_down",
  "error_description": "Please wait before polling again",
  "interval": 10
}

User denied:

{
  "error": "access_denied",
  "error_description": "User denied the authorization request"
}

Success:

{
  "secret_key": "abc123def456...",
  "key_preview": "abc123de...f456",
  "setup": {
    "claude_code": "claude mcp add popmelt https://mcp.popmelt.com --header \"Authorization: Bearer abc123def456...\"",
    "codex_cli": "[mcp_servers.popmelt]\nurl = \"https://mcp.popmelt.com\"\nhttp_headers = { \"Authorization\" = \"Bearer abc123def456...\" }",
    "codex_cli_env": "[mcp_servers.popmelt]\nurl = \"https://mcp.popmelt.com\"\nbearer_token_env_var = \"POPMELT_SECRET_KEY\"",
    "gemini_cli": "{ \"mcpServers\": { \"popmelt\": { ... } } }",
    "gemini_cli_env": "{ \"mcpServers\": { \"popmelt\": { ... } } }",
    "env_var": "export POPMELT_SECRET_KEY=\"abc123def456...\""
  },
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Important: The secret_key is shown exactly once. Store it securely - you cannot retrieve it later.

Step 4: Add Popmelt to your toolkit

The response includes ready-to-run setup commands. Just copy and execute the appropriate one:

Claude Code

Run the command from setup.claude_code:

claude mcp add popmelt https://mcp.popmelt.com --header "Authorization: Bearer YOUR_SECRET_KEY"

Verify with claude mcp list. The Popmelt tools (connect, search, use, sample, create) are now available.

Codex CLI

Add the config from setup.codex_cli to ~/.codex/config.toml:

[mcp_servers.popmelt]
url = "https://mcp.popmelt.com"
http_headers = { "Authorization" = "Bearer YOUR_SECRET_KEY" }

Or use setup.codex_cli_env with environment variables for better security.

Gemini CLI

Add the config from setup.gemini_cli to ~/.gemini/settings.json (or .gemini/settings.json in your project):

{
  "mcpServers": {
    "popmelt": {
      "httpUrl": "https://mcp.popmelt.com",
      "headers": {
        "Authorization": "Bearer YOUR_SECRET_KEY"
      }
    }
  }
}

Or use setup.gemini_cli_env with environment variables:

{
  "mcpServers": {
    "popmelt": {
      "httpUrl": "https://mcp.popmelt.com",
      "headers": {
        "Authorization": "Bearer $POPMELT_SECRET_KEY"
      }
    }
  }
}

Other MCP clients

Use the server URL https://mcp.popmelt.com with your secret key as a Bearer token in the Authorization header.

Method 2: Email Registration

For fully headless environments where no human is present during setup, use email-based registration. This returns a secret key you can use immediately.

New email address: Creates a new Popmelt account
Existing account: Adds a new secret key to the existing account

Step 1: Request registration

curl -X POST https://popmelt.com/api/agents/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "agent@company.com",
    "agent_name": "Production Agent"
  }'

Response:

{
  "status": "verification_sent",
  "message": "If this email is valid, you will receive a verification email. Check your inbox."
}

Step 2: Verify via email link

The email contains a verification link. You can either:

Click the link in a browser to complete verification interactively
Extract and call the token programmatically:

# The email link looks like:
# https://popmelt.com/api/agents/verify?token=abc123...

curl "https://popmelt.com/api/agents/verify?token=abc123..."

Response:

{
  "status": "verified",
  "secret_key": "abc123def456...",
  "key_preview": "abc123de...f456",
  "setup": {
    "claude_code": "claude mcp add popmelt https://mcp.popmelt.com --header \"Authorization: Bearer abc123def456...\"",
    "codex_cli": "[mcp_servers.popmelt]\nurl = \"https://mcp.popmelt.com\"\nhttp_headers = { \"Authorization\" = \"Bearer abc123def456...\" }",
    "codex_cli_env": "[mcp_servers.popmelt]\nurl = \"https://mcp.popmelt.com\"\nbearer_token_env_var = \"POPMELT_SECRET_KEY\"",
    "gemini_cli": "{ \"mcpServers\": { \"popmelt\": { \"httpUrl\": \"https://mcp.popmelt.com\", \"headers\": { \"Authorization\": \"Bearer abc123def456...\" } } } }",
    "gemini_cli_env": "{ \"mcpServers\": { \"popmelt\": { \"httpUrl\": \"https://mcp.popmelt.com\", \"headers\": { \"Authorization\": \"Bearer $POPMELT_SECRET_KEY\" } } } }",
    "env_var": "export POPMELT_SECRET_KEY=\"abc123def456...\""
  }
}

Important: The secret_key is shown exactly once. Store it securely - you cannot retrieve it later.

Step 3: Add Popmelt to your toolkit

The response includes ready-to-run setup commands, just like the device flow. Copy and execute the appropriate one for your environment - see Step 4 above for details.

Rate limits

Email registration is rate-limited per IP and per email address. Verification tokens expire after 24 hours and have limited attempts before lockout.

Storing credentials

Claude Code and Codex CLI agents should use their native MCP configuration (shown above) - this stores the credential automatically.

For other environments, store credentials securely:

Environment variables - POPMELT_SECRET_KEY=abc123...
Secret managers - AWS Secrets Manager, HashiCorp Vault, etc.
CI/CD secrets - GitHub Actions secrets, GitLab CI variables, etc.

Never commit credentials to source control.

Token expiration

Secret keys (from both methods) don't expire automatically but can be revoked from the Popmelt dashboard. Generate new keys if compromised.

The device flow also returns a short-lived access_token for backwards compatibility, but you should use the secret_key for persistent access.

Common questions

Which method should I use?

Both methods return persistent secret keys that don't expire. Choose based on your setup:

Use Device Authorization when:

A human can approve the agent once (even remotely)
You want the familiar "scan QR code" or "enter code" flow
The agent is running interactively (CLI, local development)

Use Email Registration when:

Running in CI/CD with no human in the loop
Setting up server-to-server integrations
The agent has access to receive email programmatically

Can an agent access my private taste models?

Yes, with either method. Device Authorization grants access to the authorizing user's account. Email Registration either creates a new account or adds a key to an existing account if the email matches - either way, the agent can access that account's private taste models.

What happens if my token expires during a long-running task?

The MCP server will return a 401 error. Your agent should catch this and re-authenticate.

What if my account is on the waitlist?

Both methods require an admitted account. Device Authorization shows a "You're on the Waitlist" message when the user tries to authorize. Email Registration verifies your email but returns a "not admitted" error instead of a secret key. You'll receive an email when your account is admitted.

Is there a sandbox environment?

Not currently. Use the production endpoints for all testing. Rate limits are generous enough for development.

What's next

Claude Code - Connect Popmelt to Claude Code
MCP Basics - Understand how Popmelt's MCP server works
Building Landing Pages - Put your credentials to work
Usage Limits - Understand rate limits and quotas

Better prototypes with less prompting

Start creating