# Connect your agent to Addy

> Official instructions from Addy (https://use-addy.site) for connecting an AI agent to the Addy MCP server, so it can make short-form video ads and publish them to Instagram Reels, TikTok and YouTube Shorts. Published at https://use-addy.site/agents (also https://use-addy.site/agents.md).

Addy MCP server: `https://use-addy.site/mcp` (Streamable HTTP). Sign-in is OAuth in the browser: no API key is created, copied or stored.

Do every step yourself by running the commands directly. The only exceptions are steps marked **User step**: OAuth sign-in and clicks inside an app's settings happen in the user's browser or app, so ask the user to do them and wait for them to confirm. All commands are safe to re-run. Never run a command that waits on an interactive prompt.

Use the section for the agent you are.

## Claude Code

```
claude mcp add --transport http --scope user addy https://use-addy.site/mcp
```

If it says addy already exists, it is already added; continue.

> **User step.** Ask the user to run `/mcp` inside Claude Code, choose **addy** → **Authenticate**, then sign in to Addy and click **Allow** in the browser. Wait for them to confirm.

## Codex (CLI, IDE extension, app)

```
codex mcp add addy --url https://use-addy.site/mcp
codex mcp login addy
```

> **User step.** `codex mcp login` opens the browser: the user signs in to Addy and clicks **Allow**. In the Codex app, they may need to quit and reopen it before the tools appear.

## Gemini CLI

```
gemini mcp add -s user -t http addy https://use-addy.site/mcp
```

> **User step.** Ask the user to run `/mcp auth addy` inside Gemini CLI and click **Allow** in the browser.

## Cursor

Merge this server into `~/.cursor/mcp.json` (create the file if it is missing; keep any other servers already there):

```json
{
  "mcpServers": {
    "addy": {
      "url": "https://use-addy.site/mcp"
    }
  }
}
```

> **User step.** Cursor shows **addy** under Settings → MCP with a **Needs login** button. Ask the user to click it, sign in to Addy and click **Allow**.

## VS Code (GitHub Copilot agent mode)

```
code --add-mcp '{"name":"addy","type":"http","url":"https://use-addy.site/mcp"}'
```

> **User step.** The first time an Addy tool runs, VS Code asks to sign in. The user clicks **Allow**.

## Windsurf, Cline, Zed, opencode, Goose, Kiro and any other agent

Add a server named `addy` with the HTTP (Streamable HTTP) transport and URL `https://use-addy.site/mcp` to your MCP configuration. Merge it into the existing config; do not overwrite other servers. If your agent can only run local (stdio) servers, use:

```json
{
  "mcpServers": {
    "addy": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://use-addy.site/mcp"
      ]
    }
  }
}
```

Then ask the user to approve the Addy sign-in in the browser on first use.

## ChatGPT, Claude.ai, Claude Desktop and other chat apps

You can't change your own settings, so give the user these exact steps and stop until they confirm:

- **Claude (claude.ai, Desktop, mobile):** Settings → Connectors → **Add custom connector** → name `Addy`, URL `https://use-addy.site/mcp` → **Add** → **Connect** → sign in → **Allow**. Then start a new chat.
- **ChatGPT:** Settings → Apps & Connectors → Advanced settings → turn on **Developer mode**. Then Apps & Connectors → **Create** → name `Addy`, URL `https://use-addy.site/mcp`, Authentication **OAuth** → **Create** → sign in → **Allow**. In a new chat, open **+** → Developer mode and turn on Addy.

## Headless agents (no browser, no user)

Use an Addy API key (Pro plan, from https://use-addy.site/app/api) as a bearer token instead of OAuth: send `Authorization: Bearer addy_…` to `https://use-addy.site/mcp`. Never ask the user to paste a key into the chat; ask them to set it in your MCP config or environment.

## Verify

After sign-in, the Addy tools are available (`create_ad`, `get_ad`, `publish_ad`, …). Call `get_account` and tell the user their credit balance. Only report Addy as connected once that call succeeds.

## Using Addy

1. `create_ad` with `product_url` (best) or `product_description`. Optional `format` (see `list_formats`), `idea`, `quality` (`hd` or `draft` for half the credits). Returns a `job_id`.
2. `get_ad` with the `job_id`. It waits up to ~45 s per call; renders take 1–3 minutes, so call it again until `status` is `completed`. Show the user the video URL, hook and caption.
3. Only if the user asks: `publish_ad` with the `ad_id` (and optional `platforms`, `publish_at`). If no social accounts are connected, it returns a link; give it to the user.

Every ad is 15 seconds and costs 105 credits in Standard quality (HD is twice that); new accounts get 150 free, enough for one ad. If a call fails for credits, `get_account` returns the top-up link. Use `write_ad_concepts` (free) when the user wants options before spending credits.

More: https://use-addy.site/developers/mcp