---
title: "Connect an AI assistant (MCP)"
description: "Step by step to connect an AI assistant to OneClick Ads through MCP: connection via OAuth (login, as in the Claude connector) or via an API key in the Authorization header, with a curl example."
---

> Connect an AI assistant (such as **Claude**) to your OneClick Ads data and
> ask questions in natural language about campaigns, optimizations and conversions.

OneClick Ads offers an **MCP server** (Model Context Protocol) — an endpoint that
AI assistants understand natively. Once connected, the assistant can look up,
for example, your ad accounts, campaigns, optimizations and the OneClick Tracking
conversion logs.

## The server address

```
https://mcp.oneclickads.com.br/mcp
```

This is the only address you need to give your assistant.

There are **two ways** to authenticate the connection. Choose the one your app supports:

| Method               | When to use                                                                                                                                                    |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **OAuth (login)**    | Apps that support an MCP connector and interactive login — for example, the **Claude** apps (Claude.ai, Claude Desktop, Claude Code).                          |
| **API key (header)** | Integrations that send a fixed token in the `Authorization` header — for example, the **Claude API** (MCP connector parameter) or your own server-side agents. |

---

## Option 1 — Connect via OAuth (login)

Recommended for clients that open a login window. This is the case for Claude's custom
connectors. In this flow you **don't need to generate any key**: the app itself
handles the login and asks for your authorization.

1. In your assistant, add a **custom MCP connector/server**.
2. Enter the server address: `https://mcp.oneclickads.com.br/mcp`.
3. The app will open a **OneClick Ads login** window. Sign in with your account.
4. Review and **authorize** the requested access (read and/or write).
5. Done — the connection is saved in the app. Access renews automatically while
   the app is in use; after **30 days without use**, the connection disconnects and
   you need to authorize it again.

In Claude's case, this OAuth flow is run end to end by the app itself.
For details about Claude's MCP connector, see the
[official Anthropic documentation](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector).

You can review authorized connections, with the date each one was last used, and
revoke them at any time in
[**Connections → Connected apps**](https://app.oneclickads.com.br/user/connections).
Revoking disconnects the app immediately: it has to be authorized again.

---

## Option 2 — Connect via API key (`Authorization` header)

Recommended for integrations that don't do an interactive login and send a fixed token in the
`Authorization: Bearer <token>` header. It is the simplest method for your own agents and
for the Claude API.

### Step 1 — Generate your API key

1. Go to [**Connections → API Keys**](https://app.oneclickads.com.br/user/connections) in
   your OneClick Ads account.
2. Choose the key's scope:
   - **Read only** (recommended to start) — looks up data without changing anything.
   - **Read and write** — also allows changing optimizations and accounts.
3. Click **Generate key** and **copy the token right away** — it is shown **only once** and
   cannot be retrieved later.
4. Store the token as a **secret** (the app's password vault). Never paste it into
   documents, code or public conversations.

### Step 2 — Use the key in the header

Send the token in the `Authorization` header:

```
Authorization: Bearer SUA_CHAVE_DE_API
```

### Connecting through the Claude API

The Claude API accepts MCP servers that use a token in the header. Enter the server
address and your API key in the connector's authorization field:

```json
{
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.oneclickads.com.br/mcp",
      "name": "oneclickads",
      "authorization_token": "SUA_CHAVE_DE_API"
    }
  ]
}
```

Claude sends the `authorization_token` as `Authorization: Bearer SUA_CHAVE_DE_API`.
See the details in the
[Claude MCP connector documentation](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector).

---

## Manage several clients, each with their own OneClick account (agencies)

If you are an agency or media buyer and each client has their **own OneClick Ads account**, the
connection is always **per login**: the assistant sees exactly the ad accounts of the login
that authorized the connection. To operate another client's accounts, you switch **which login** is
connected.

- **Via OAuth (login):** each connection applies to **one login**. To switch clients,
  disconnect the connector and reconnect by signing in to **their** OneClick account (or ask the
  client to authorize it). Within the same app there is usually **one connector per login** — to
  keep several clients active at the same time, use separate assistant logins/sessions.
- **Via API key:** generate **one key per client** (each one in that client's OneClick
  account) and point each agent/session to the right key. This is the most practical path
  for automations that serve several accounts.

:::tip[Confirm which client you are on]
Before operating, confirm the active connection: _"Claude, which ad accounts can I see
right now?"_ — the accounts listed belong to the connected login/key. If the wrong client shows up,
switch the connection before any write action.
:::

:::note[One action across several accounts of the same login is something else]
Here we cover clients with **separate OneClick accounts**. If the multiple ad accounts
are **under the same login**, you don't switch connections — just ask for the action on all of them
at once. See
[Edit campaigns, ad sets and ads with AI](/en/mcp/edit-campaigns-ad-sets-and-ads-with-ai/).
:::

---

## Testing the connection with curl

To confirm your key works, make a read call. The command below
lists your Meta ad accounts:

```bash
curl https://mcp.oneclickads.com.br/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Authorization: Bearer SUA_CHAVE_DE_API' \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "listMetaAdAccounts",
      "arguments": {}
    }
  }'
```

- **With the correct key**, the response returns your data (HTTP status `200`).
- **Without the key** (or with an invalid key), the response is `401 Unauthorized`.
- With a **read-only** key, attempting a write action returns an error stating
  that the operation requires the write scope — exactly the expected behavior.

---

## Where to start after connecting

Connected the assistant and not sure where to start? Open **Prompts**, in the OneClick Ads
side menu (`app.oneclickads.com.br/prompts`). The page has ready-made commands,
organized into four themes — understanding the account, optimizing campaigns, creatives and
tracking — each with a **copy** button. Paste it into your assistant and adapt the
details (campaign name, values) before sending.

If you haven't connected an assistant yet, the page shows the same prompts with a notice and
a shortcut to [**Connections**](https://app.oneclickads.com.br/user/connections) — so you can see
what the assistant will be able to do even before connecting.

For more advanced **action** commands (configuring in bulk, creating campaigns by
replication), see [Ready-made prompts to operate campaigns](/en/mcp/campaign-prompts/).

---

## Security and best practices

- **Start with read access.** Connect first with read-only scope, validate the data and only
  then consider write access.
- **Writing changes real campaigns.** Actions such as turning optimizations on/off change
  the real behavior of your campaigns. Use write scope only when necessary and,
  preferably, with human confirmation before each change.
- **Treat the key like a password.** It gives access to your account. Store it only in the
  app's secrets vault.
- **Revoke whenever you want.** If a key leaks or is no longer used, revoke it in
  [**Connections → API Keys**](https://app.oneclickads.com.br/user/connections) and generate a
  new one. The same applies to apps connected via OAuth.
