Agent setup guides

The programmatic surface is a Model Context Protocol server. There is no separate REST API to learn and no second code path to reason about: the MCP server and the in-app agent call the same organisation-scoped tool layer, so a tool behaves identically whichever client calls it.

The transport is streamable HTTP at a single endpoint, with no server-sent-events transport to configure. Authentication is a bearer key minted inside the product. Any MCP client that can send an Authorization header over streamable HTTP connects the same way, which is why the setup instructions for one client are mostly the setup instructions for all of them.

One property of that key matters more than the rest. The workspace a request operates on is taken from the verified key and never from a tool argument. A client cannot ask for another workspace's numbers by naming it, because nothing in the tool surface accepts a workspace to name. Keys are hashed at rest and revocable, and revoking one ends every session that was using it.

Every key carries read. Draft and approve are independent additions rather than rungs on a ladder — the check a tool makes is an exact match on the one scope it needs — and the difference between them is what a client can put in front of you rather than how much it writes.

Read covers the whole surface a reader wants: connections, ad accounts, campaigns, the structure underneath them, the media library, metrics, the list of drafts, and media plans. A read key is the one to mint first, and for many people it is the only one they ever need.

Draft covers writing change requests and editing plans. Nothing a draft key writes is a change to an ad account. A draft is a record of an intended change, with the state it is changing from and the checks it passed; it sits at the gate until something clears it.

Approve covers clearing a draft at the gate, and rejecting one so it can never be cleared. It is opt-in when a key is minted, and the in-app agent never holds it.

Tools are registered per request against the scopes the key carries, which has a consequence worth stating plainly: a read-only key does not see the drafting tools at all. They are absent from the client's tool list rather than present and refusing. An agent cannot be talked into using a tool it cannot see, and this is the cheapest guardrail in the system because it needs nobody to remember it.

The reading surface is the part that changes a working day. A client with a read key can answer, in one exchange, which platforms are connected and when each last synced, which campaigns exist including the ones that are not delivering, what the blended numbers look like across every channel with a per-channel breakdown underneath, which campaigns carried the spend, and what the account has looked like over its last ninety days.

Two conventions run through all of it and both are deliberate. Money is an integer in minor units with an explicit currency beside it, never a formatted string, so nothing is rounded twice or compared across currencies by accident. Ratios are computed when they are read and returned as null when the denominator is zero, so a blank means "there is nothing to divide by" rather than "zero". Reading a null as a zero is the single most common way a report lies, and the tool surface refuses to help you do it.

Every write is a change request before it is a change. A drafting call takes a connection and a list of operations and writes them as one reviewable batch: a campaign, the group inside it and the ad inside that are three entries in one call, with each child pointing at the index of the entry that creates its parent, so nothing carries an identifier that does not exist yet.

What comes back is the batch, a link to the gate for the whole group, and the authority that cleared it. That last field is the point of the arrangement. It says pending when the batch is waiting for a person, and it says policy when a rule the workspace wrote cleared every row of it on the way in. Those are the two authorities there are: approved by you, or by a rule you wrote. The record says which, and it says it on the row rather than in a log somebody has to go and find.

A draft that needs a change does not have to be rejected and re-drafted. Replacing its payload re-validates it, re-stamps the currency from the target account and re-runs the guardrails, and a row that failed its checks goes back to waiting. An undo has the same shape as anything else here: the inverse is drafted at the same gate, with the same guardrails and the same two authorities, rather than travelling a rollback path of its own.

The arrangement, stated once: your connections read your accounts, a change is written as a draft on the record with the state it would change from and the checks it passed, applying it is gated on approval — by you, or by a rule you wrote — and no platform write reaches a customer account until that platform has granted write access. Applying a cleared change to a platform is in private beta.

Start with read. It is the scope that answers questions, it cannot alter anything, and it is enough to find out whether an agent is useful on your accounts at all.

Add draft when you want the agent to prepare work rather than describe it. The failure mode of a draft key is a queue of change requests nobody wanted, which is an annoyance rather than an incident.

Add approve deliberately, to one key, and know what you have done. An approve key can clear a batch without asking, which is the correct arrangement for an automation you wrote and a poor one for a client you are still evaluating. The shape holds either way — every row records the state it would change from, so the inverse of anything cleared is a draft somebody can write — but the record is only useful if somebody reads it, so give an approve key a job specific enough that you would notice it doing something else.

Setup is the subject everything else assumes, and each of the other five is a different answer to "now what".

• Media planning is usually the first real use of a read key: a quarter argued about with the account's own ninety days in front of you instead of last year's memory.
• Budget and bidding is what a connected agent will ask to change first, and the limits it will meet when it does.
• Governance and approvals is the other half of the scope decision made here — a key says what a client may ask for, and a rule says what gets cleared without you.
• Measurement and metrics is how to read what the reading tools return, including the blank that is not a zero.
• Creative and testing is the one subject a connected client mostly observes rather than drives, because the library and the structure are readable and the judgement is not.