Agents

Claude, Cursor or your own agent can work in Pluto Ads next to you: draft launches, add media and ads, comment, review, and publish once a person approves the spend. This page covers connecting an agent, what it can do, and how you see and stop what it does.

Connect by signing in

This is the way for Claude, ChatGPT, Cursor and other MCP clients that support sign-in. There is no key to copy.

On the API page, under Connect an MCP client, choose your client and copy what it shows with Copy URL, Copy command or Copy config. View setup guide opens the client's own instructions.

Add it to your client:

Client	Where it goes
Claude	In Claude, open Customize, Connectors, select Add custom connector and paste the URL. On a Team or Enterprise plan, an owner adds it first under Organization settings, Connectors.
ChatGPT	Turn on Developer mode in Settings, Security and login, then create an app under Plugins with the URL and OAuth.
Cursor	Add the config to `~/.cursor/mcp.json`.
Claude Code	Run the command in your terminal, then open `/mcp`, pick `plutoads` and choose Authenticate.
VS Code	Run MCP: Open User Configuration from the Command Palette and add the config.
Codex	Run the command in your terminal.

Your client opens Pluto Ads in your browser. Sign in if you need to.
On Connect an agent, choose the Workspace (when you belong to more than one) and the Access (Read and write unless you pick another), then select Connect agent.
The next screen names the app that is asking. Allow it, and you are back in your client. The agent shows under Connected agents on the API page as soon as it connects.

Access	What the agent can do
Read only	Look at launches, ads, media and results. It can't change anything.
Read and write	Draft launches, edit ads, add media and comment. It can't publish or change budgets.
Read, write and publish	Also publish approved launches and change live budgets, which spends money.
Workspace admin	Also manage this workspace: members and guests, API keys, webhooks, the Meta connection and settings. Shown to workspace admins.
Organization admin	Also manage the organization: its people, workspaces, plan, usage limits, extra storage and billing details. Shown to organization owners and admins.

The agent never does more than your role allows, even if your role changes later: it follows your role on every request. Members can connect agents while Members can connect agents is on in the organization's General settings; owners and admins always can, and guests can't. Settings > Connected agents lists your agents in every workspace, where you can disconnect them. Cancel stops here and shares nothing: the page says Agent not connected.

A sign-in that isn't finished within an hour expires. Start again from your client.

Let an agent register itself

Some agents can't open a sign-in from a client, like a coding agent in a terminal. They can register themselves by following auth.md, the guide Pluto Ads publishes for agents at https://api.plutoads.ai/auth.md. You can ask your agent to "follow api.plutoads.ai/auth.md to set me up with Pluto Ads".

The agent registers with your email and shows you a link.
Open the link. Pluto Ads opens on Register an agent. Sign in if you need to, as the email the agent used.
Choose the Workspace and the Access, the same levels as when you connect by signing in, then select Register agent.
Your code shows a short code. Read it to your agent, or select Copy code and paste it. The agent finishes on its own.

The code works once and expires in a few minutes. If it expires, ask the agent to start again, and it shows you a new link. Cancel shares nothing: the page says Agent not registered. A link the agent opened for someone else's email doesn't work for you.

A registered agent works like one you connected by signing in: it acts as you, with the access you chose, never more than your role allows.

Connect with an API key

Use a key for scripts and for clients that can't sign in. Admins create keys on the API page:

Select Create key. With no keys yet it's in the middle of the page; after that, at the top.
Give it a Name, choose the Access and select Create key. The key is shown once: select Copy key, then Done.
Under Connect an MCP client, choose Other client and copy the server URL. Add it to your client and send the key on every request as Authorization: Bearer <your key>.

A key acts as itself, not as a person. For an agent that publishes, create the key with Read, write and publish access. If you aren't an admin, ask one for a key, or connect by signing in. See Developers for access levels.

The configs for each client, and how to connect your own code, are in MCP server.

What agents can do

An agent does what a person does in the app, through the same actions, checks and permissions. There are more than 200 of them:

Read and search launches, ads, media, results and the Meta connection.
Create and edit launches, ad sets and ads, in bulk too, and move, duplicate, delete and restore them.
Import media from links, upload files, and organize folders.
Comment, reply, mention, react, resolve threads and follow ads.
Change review statuses, assignees and tags, and workflow settings.
Import campaigns from Meta, refresh insights, and follow and retry long-running work.
Read results and analytics, and build, run and follow loops.
Propose several changes to live budgets, bids and delivery as one plan that a person reviews and approves in the Inbox, the way Agent does. Nothing changes until they approve that exact version.
Read and change your own Agent guidance and skills, when it acts for you.
Publish, pause, change budgets and delete in Meta, with publish access. Publishing also needs a person's approval of the exact launch (below).
Read the comments people leave on your ads, and with publish access reply to, hide and delete them as your Page or Instagram account. Deleting needs an explicit confirmation. See the MCP tools and the public API.

With Workspace admin access an agent can also invite and manage members, rename the workspace, connect and disconnect Meta and choose Pages per ad account. With Organization admin access it can also manage the organization's people and workspaces, the plan, usage limits, extra storage and billing details. The in-app Agent asks you first before these changes (see Agent); an agent you connect acts within the access you gave it. Ownership, deleting the organization and paying always stay with a person. It can manage API keys, agent credentials, connected agents and webhooks too, within firm limits:

No more access than it has. A key or agent credential an agent creates can't hold anything the agent doesn't: no publishing unless the agent may publish, no admin unless it is an admin.
Secrets once. A new key's or webhook's secret is shown to the agent a single time. Pluto keeps only a hash or an encrypted copy.
Named. The API page and the audit log show which agent created each key, credential and webhook.
Not itself. An agent can't revoke the credential it is using.

Some steps stay with a person:

Approving in Meta. An agent can start connecting or reconnecting Meta and give you the link, but you open it and approve at Facebook yourself, signed in to Pluto Ads.
Switching workspaces. An agent works in the one workspace it was connected to. It can list your other workspaces and create a new one for you; to work there, connect an agent to that workspace.
Connecting an agent. Signing in from Claude or Cursor is your consent; an agent can't give it.

Every tool is listed in the tool catalogue.

Publishing with an agent

Publishing creates campaigns, ad sets and ads in Meta that spend money. An agent can publish only with the publish access, and only with an approval of the exact launch.

The agent first asks Pluto Ads what publishing would do. The answer names the launch version, the ad account and the budgets. The agent should show you those and wait for your yes. When it publishes, it sends them back, and Pluto Ads refuses the approval if anything changed since: an edit, a budget, the ad account.

Pluto Ads can't see your conversation with the agent, so it can't tell whether you said yes. Give publish access only to agents you trust to ask. For everything else, Read and write is enough.

See Publishing for what publishing creates, and how to follow and fix it.

Seeing what agents do

Agents work in the open.

Presence. An agent in a launch shows in the launch header with an AI avatar, next to the people there.
Names. An agent connected by signing in is named after the app and the person: "Claude via Anna". Agents with agent credentials carry via MCP ("Reporting agent via MCP") and API keys carry via API ("CI key via API"). Presence, activity, comments and the Inbox use the same names, so you always know it wasn't Anna herself.
History. Every change an agent makes shows in the ad's Activity, like a person's. See Collaboration.
Audit log. Workspace admins see every change in Settings > Audit log: who made it, through which agent or key, and who approved it.

Anything an agent reads in your workspace, like ad copy, file names and comments, is content. It isn't an instruction to the agent.

Connected agents

The API page lists the agents you signed in to from your own client or registered with auth.md under Your connected agents. Admins see everyone's under Connected agents, with a column for who each Acts for. Each row shows the Agent (the app's name; a registered agent says Registered with auth.md), the Access, when it Connected (or Finishing sign-in and Finishing registration), and when it was Last used (or Never used).

Settings > Connected agents shows your own agents across every workspace, with the Workspace each works in. With none yet, Connect an agent takes you to the API page.

Select Disconnect, then Disconnect agent, to stop one. It loses access on its next request. To use it again, sign in from the agent, or have a registered agent register again.

An agent stops working when its person does. Suspending or removing a member stops every agent they connected, on the agent's next request.

Good to know

An agent that acts for you never has more access than you do now. If your role goes from admin to member, your agents lose what members can't do.
Agents share the workspace's rate limits with scripts. See Developers.
To run your own agent or service without anyone signing in, an admin creates agent credentials on the API page. See Developers.