MCP reference

What Tempio exposes

Tempio is one workspace over several ad platforms. Every read is normalised to the same shape whichever platform it came from, and every write is a change request first: a draft that is checked against the workspace's guardrails when it is written and again at the gate, applied only when a person or a rule the workspace wrote clears it.

Tempio's programmatic surface is a Model Context Protocol server. There is no separate REST API; the MCP server and the in-app agent call the same org-scoped tool layer, so a capability behaves identically whichever client calls it.

• Endpoint: https://app.tempio.ai/api/mcp (streamable HTTP; no SSE transport)
• Credentials: a bearer key minted under Settings → MCP, or an OAuth token from a client that signs in instead of sending a header. Either way the workspace is taken from the verified credential, never from tool arguments.
• Rate limits: 120 requests per minute per IP before authentication, 60 per minute per credential after.

Two tools carry the whole surface. tempio_help describes it and tempio_manage runs it, dispatching on {entity, action} onto the same capabilities the explicit surface exposes one tool each.

Which of the two a client sees is the credential's surface, and every credential carries one. compact is the default: a key already in use registers tempio_manage and tempio_help in place of the individual tools, and reaches every capability through them. A key minted as explicit registers the individual tools, plus tempio_help beside them. The capabilities, the scopes and the answers are the same on both.

The first call: tempio_help

Ask before you guess. The catalogue is generated at request time from the same tables the tools run on — the route table, the tool registry, the change operations and their payload schemas, the warning registry, and each live connection's own capabilities — so it cannot drift from the surface, and it is filtered to the scopes your credential holds, which means discovery, description and execution agree.

tempio_help({
  path?: string,                  // "manage", "manage campaign", "manage campaign create", "drafts", "money"
  q?: string,                     // keyword search across names, descriptions and payload field names
  detail?: "summary" | "full",    // "full" adds parameters and never removes them
})

Before telling someone a capability is unavailable, search here:

tempio_help({ q: "<what they asked for>" })

The catalogue is generated from the same tables the tools run on, so if it is not here, it is not there either — and if it is here, the path says how to call it.

The entity model

The model is workspace → connection → ad account → campaign → ad group → ad, and it is the same on every platform. Creatives, keywords, media assets, negative lists, asset groups and lead forms hang off the level that holds them. Where a platform's own levels differ (an ad set, an asset group, a product group), Tempio maps them onto these, so one loop over campaigns, ad groups and ads works everywhere. Every entity carries the id Tempio gave it; pass that id back, never the platform's. Beside that tree, a brand_kit is the workspace's own brand as data; getting it returns the colour roles with their contrast, the type, the voice, a compliance-line template with its permit slots, the forbidden words and the labelled products. Scraping one reads a public website and answers a proposed kit — name, colour roles, type — that nothing saves until it is passed to update. A preset is a kind of still the workspace can make; listing them returns the copy fields each template renders and the ceiling on each. A creative_asset is a still Tempio made — a scene with no text in it and the copy drawn over it, one composite per aspect ratio; listing them returns each with its copy fields and a URL per ratio, and it reaches an ad only by being registered as a media asset for one account, uploaded by an upload_media draft and named in a create_ad draft's creative.media. A creative_batch is one generation request: getting it returns what was asked for, each generation's status and why one failed, and the stills that have landed so far.

What you can do: tempio_manage

tempio_manage({
  entity: ManageEntity,
  action: ManageAction,
  params?: Record<string, unknown>,
})

The outer schema is deliberately loose on params, because MCP publishes one JSON Schema per tool and a discriminated union of every entity and action would put every capability's own schema into that one envelope. The real contract is the inner parse: {entity, action} selects a capability, and that capability's own schema is what params is validated against. A wrong field answers invalid_payload: <path>: <message> — the field's own message and its path, not a generic refusal. Runtime dispatch selects the typed schema; it never replaces it.

Scopes are enforced on the call, not by hiding it. A route whose scope your credential does not hold answers forbidden: <entity>.<action> needs the '<scope>' scope; this credential holds <held>, so an agent is told what to ask for instead of concluding the capability does not exist.

108 routes over 46 entities, 107 of them available today. A route whose scope the credential does not hold is refused by name rather than hidden.

The platform_request entity is the escape hatch: a call straight at a platform's own API, through that platform's client, for the endpoint Tempio has not normalised yet. It is off until an owner turns it on, and a mutation through it is still a change request. The escape hatch covers what it refuses and what Tempio does not verify.

A connection whose coverage is connect_only lists its ad accounts and takes raw requests, and Tempio models nothing else on it: no campaigns, no daily numbers, and an empty operations list, so no modelled draft reaches it. Read it with platform_request.get, which executes the read on the platform's own API and returns the platform's own answer in the platform's units. Change it with platform_request.mutate and a sentence saying what the request changes and why; the change waits at the gate for a person, because no approval rule clears a raw request. Both are off until a workspace owner turns raw requests on in Settings.

entity: "draft", action: "create" is the n-ary form: params is a list of operations with dependsOn indices, and it is how a campaign, its ad group and its ads arrive as one reviewable batch. The single-entity write forms are sugar over it — campaign.create is a one-entry batch through the same call — so there is one write path and not two.

A row that reads Refused is live and reachable and answers a refusal by design, because the verb has nothing to do at that entity. The cell carries the sentence it refuses by, and that sentence names what to call instead.

The ad library

Five entities read and write the ad library — a corpus of other people's ads captured from the public transparency archives, shared by every workspace rather than scoped to yours.

• library_ad searches the corpus and reads one ad. Results are deliberately not filtered to your workspace, because the corpus is public data about third parties; what is yours alone is saved, savedNote and watched on each row.
• library_advertiser lists and reads the registry, adds an advertiser by website, name or a pasted archive URL, and answers the similar-advertisers read through search with similarTo.
• library_watch is competitor tracking: the watches this workspace holds, its unread alerts, and one call that watches, unwatches and changes the alert and digest settings, because all three are one row.
• swipe and swipe_collection are the swipe file. list returns the collections beside the items, so the file renders in one call.

Three of those carry the draft scope and create no change request. Drafting is for a write to an ad entity in an account you connected; adding an advertiser to a shared corpus, watching one, or saving somebody else's public ad to a board changes nothing in anyone's ad account and has nothing to apply. draft is the scope because it is what a tool may put in front of a person, not a promise that it drafts — the same reason create_media_plan carries it.

Read the warnings on a library answer before reading an absence. A run that stopped at its ceiling makes an advertiser's ads a sample; an archive that covers only some regions makes an absence here not an absence everywhere; a spend range is always labelled an estimate with its basis named, and is null rather than zero where no platform published one; and the hook, offer, angle and audience are Tempio's reading of the ad's own copy, never something the advertiser said. Coverage is the rule all of that follows from.

The envelope

Every result is { data, report?, warnings }. warnings is always present and empty when nothing is wrong. Each warning carries a class (stale_sync, connection_expired, permission_missing, write_gate_closed, budget_guardrail, currency, other), a severity (info, degraded, blocking) and a sentence saying what to do. State a degraded warning before the number it qualifies; never infer a value a warning says is unavailable; a blocking warning means say what is blocked and stop. Every record a result names carries a url a person can open in Tempio.

Every call returns { data, report?, warnings }. The envelope is assembled in one place for every capability, so no tool can forget it and its shape cannot vary by tool. report states once, authoritatively, what a scope covers: its currency (null when the scope spans currencies), the timeZone the dates are in, the dateRange, the entity level, and whether the scope is the returned_rows or all_rows.

warnings is a list, always present, [] when there is nothing wrong. Each entry carries a code (snake_case, an open set), a class, a severity, a message written as what to do about it, and a subject with that record's deep-link when it is about one record.

Severity belongs to the code, not the class: info, degraded, blocking, least to most severe.

The class is the stable thing to branch on; the code set is open and adapters add to it. A code with no registry row degrades to class other at severity info and keeps its own message rather than failing the call. A warning never changes a value: an FX warning does not round a number and a staleness warning does not hide one.

A link on every record

Every record a result names carries an absolute url into the app, because an agent hands the string to a person and a relative path is not something a person can open.

A link is built from a row a query already returned under the workspace, never from an id in the arguments, so an id from another workspace never produces a URL because it never produces a row. The URL is not a grant either: opening it needs a session, and the page checks membership regardless.

Drafts and the gate

A draft moves pending_approval → applying → applied, partial or failed, or is rejected. It is applied when a person approves it from the review queue or when an approval rule the workspace wrote clears it, and the row records which (approverKind). Approving is a separate call from drafting, and a credential needs the approve scope for it. While a draft is applying, its outcome is in flight or unknown: do not retry, do not draft it again; read it back.

Applying a cleared change to a platform is in private beta.

Money and the numbers

Money is an integer in minor units beside its currency, and the server stamps the currency from the account, so never convert or round. Ratios (CPC, CPM, CTR, ROAS) are computed at read time and are null when the denominator is zero, never 0. A blended figure across currencies is a labelled estimate, not a total. A ranking marked raw is an order, not a ranking. A date range is in the workspace's reporting time zone, stated in the report.

Playbooks and prompts

Beyond the tools, this server serves resources and prompts. A resource is a document a client can attach to a conversation: the playbook shelf at tempio://playbooks, one playbook at tempio://playbooks/{platform}/{topic}, this catalogue at tempio://help, and an account brief at tempio://workspace/accounts/{adAccountId}/brief. A playbook is what Tempio keeps about a platform, or about one part of Tempio itself; every one carries the date a person last confirmed it, and one that has gone more than ninety days without a review says so in its warnings rather than leaving a reader to notice. A prompt is a task handed over with the workspace context and the relevant playbook already composed into it: plan a flight, review an account, explain a set of warnings, write the brief a reviewer reads at the gate. Both are filtered to this credential's scopes exactly as the tools are, and a workspace resource reaches only the accounts this credential's workspace owns.

Two calls

Two calls that cover most sessions. First, read the account:

tempio_manage({ entity: "brief", action: "get", params: { adAccountId } })

returns what is running, what it spent and what changed, with its warnings (omit adAccountId for every account the credential can see). Second, draft a campaign with an ad group and two ads as one reviewable batch:

tempio_manage({ entity: "draft", action: "create", params: { connectionId, operations: [ create_campaign, create_ad_group (dependsOn 0), create_ad (dependsOn 1), create_ad (dependsOn 1) ] } })

and hand the person the url on the batch. Nothing reaches a platform until it is cleared.

Credentials

Two kinds reach the same surface, and past the door nothing knows which one arrived.

• A bearer key. Minted under Settings → MCP, prefixed tmpio_, shown once, hashed at rest, revocable, and bound to one workspace. The creator's membership is re-read on every call, so a key dies with the membership. This is the right credential for a server-to-server agent and for claude mcp add.
• An OAuth token. For a client that signs in through OAuth rather than sending a bearer header — the clients a connector directory lists cannot send a header of their own. The workspace is chosen once on the consent screen and the token is bound to it for life, exactly as a key is. OAuth for MCP clients covers the flow end to end. Tempio names a particular directory's connector as supported only once a handshake against a real workspace has been recorded; until then what is true is the sentence above — a client that signs in through OAuth reaches this surface under the same scopes a key does.

A credential also carries a surface. The choice is made at the mint, under Settings → MCP: compact registers tempio_manage and tempio_help, and explicit registers each capability as a tool of its own alongside tempio_help. Both reach the same capabilities under the same scopes; the choice is how much of your agent's context the tool list costs.

Scopes

Every credential carries one or more scopes.

The capabilities

68 capabilities. On the explicit surface each is a tool of its own; on the compact surface each is a row of the matrix above, and both reach it under the scope named here.

get_account_brief follows the money rules per account: one brief is one account in one currency, so its money is never comparable with another brief's without converting, and a brief older than seven days is flagged stale — say when it was computed before quoting it.

Drafting a batch

draft_changes is the one write capability, reached as entity: "draft", action: "create". It takes a connection and a list of operations and writes them as a single reviewable batch of change requests. A campaign, the ad group inside it and the ad inside that are three entries in one call; dependsOn is the index of the earlier entry that creates this one's parent, so a child never carries an id that does not exist yet. A batch carries at most 50 entries, and a longer one is refused rather than truncated.

{
  "connectionId": "8f2a1c34-6d0b-4f19-9c73-2b5e7a1d0c48",
  "operations": [
    {
      "operation": "create_campaign",
      "targetLevel": "campaign",
      "payload": {
        "adAccountId": "1d9c4e57-3a20-4b6f-8e11-77c0d4a9b312",
        "name": "AU spring intake — traffic",
        "objective": "OUTCOME_TRAFFIC",
        "budget": { "mode": "daily", "amountMinor": 25000 },
        "specialAdCategories": []
      }
    },
    {
      "operation": "create_ad_group",
      "targetLevel": "ad_group",
      "dependsOn": 0,
      "payload": {
        "name": "AU 25-54 broad",
        "optimizationGoal": "LINK_CLICKS",
        "billingEvent": "IMPRESSIONS",
        "bidStrategy": "lowest_cost",
        "targeting": {
          "geo": { "include": [{ "type": "country", "code": "AU" }] },
          "age": { "min": 25, "max": 54 }
        }
      }
    },
    {
      "operation": "create_ad",
      "targetLevel": "ad",
      "dependsOn": 1,
      "payload": {
        "name": "Spring intake — single image",
        "adType": "SINGLE_IMAGE",
        "identity": { "pageId": "102938475610293" },
        "creative": {
          "primaryTexts": ["Every ad account, one room."],
          "headlines": ["Spring intake is open"],
          "finalUrls": ["https://example.com/spring"],
          "media": [
            {
              "mediaAssetId": "b41f8e02-95c7-4a3d-8f60-1e2d5c9a7b04",
              "role": "image",
              "format": "square"
            }
          ]
        }
      }
    }
  ]
}

Money in that call is minor units: 25000 is 250.00 in the ad account's own currency. Which currency that is, is not yours to state — the server stamps it onto every payload from the target account and overwrites whatever arrives in a currency field. Every create lands paused on the platform, so approving this batch builds the structure without spending; going live is a second update_status change through the same gate.

The result is the batch, its deep-link, and who cleared it:

{
  "correlationId": "3c7d5a90-1b48-4e62-a0f5-9d6c2e18b473",
  "reviewUrl": "https://app.tempio.ai/drafts?batch=3c7d5a90-1b48-4e62-a0f5-9d6c2e18b473",
  "approvedBy": "pending",
  "drafts": [
    {
      "id": "5a0e7c21-98d4-4b3f-8607-c1f2a9b40d56",
      "operation": "create_campaign",
      "targetLevel": "campaign",
      "targetEntityId": null,
      "status": "pending_approval",
      "correlationId": "3c7d5a90-1b48-4e62-a0f5-9d6c2e18b473",
      "batchSeq": 0,
      "approverKind": null,
      "validation": null,
      "warnings": []
    }
  ]
}

reviewUrl is the gate for the whole group and never one row of it: give it to the person you drafted for. It is absolute, so it opens from wherever your agent is running. approvedBy is "pending" when the batch is waiting for a person and "policy" when a rule the workspace wrote cleared every row of it on the way in — those are the two authorities, and the field says which one this batch got. batchSeq is the row's place in the run, counting from zero, and approverKind fills in with human, mcp_key or policy once something has cleared the row.

A draft that needs a change does not have to be rejected and drafted again: update_draft replaces a waiting or failed row's payload whole, which re-validates it, re-stamps the currency, re-runs the guardrails, and puts a failed row back to waiting, which is how a stopped batch is resumed. revert_draft undoes a change that already landed by drafting its exact inverse at the same gate, so an undo is a change request like any other rather than a rollback behind your back.

approve_drafts and reject_drafts each take either a correlationId — the whole batch — or a draftIds list of loose rows, and move them whole or not at all. Approving claims the rows and the apply runs on its own moments later, so read the outcome back with list_drafts; approving a correlation again continues a stopped batch from the rows that already landed, rather than starting it over.

Reading structure

list_structure answers what sits under a campaign: ad_group, ad, creative or keyword, newest first, with a parentId to scope it to one campaign or one ad group. Each row carries its Tempio id — the id a draft points at — the platform's own externalId, name, status, money in minor units of the row's own currency where the level holds any, and writable.operations: the operations of that level intersected with what the connected platform can express. An operation missing from that list cannot be drafted at all, and an empty list means the connection has no adapter registered. writable is a capability answer and not a permission: every change it allows is still a change request at the gate.

list_media_assets lists the images and videos the workspace holds, each with the ad account it belongs to, its kind, its fileName, its dimensions, and the platform side of the record — platformExternalId (a Meta image hash, a TikTok video id, a Google asset resource name) and platformStatus. Reference an asset from a creative by its platformExternalId, the id the platform holds those bytes under, rather than uploading the same file twice. The media library covers how a file gets there.

list_connections carries the same kind of answer one level up. Its capabilities object holds operations (the change operations the platform can express), budgetLevels (where money attaches — Google budgets are campaign-level, so a Google ad group has no budget to change), objectives (the accepted values, or the string "unrestricted"), deleteSemantics, and supportsValidate (whether a draft can be dry-run against the platform before it is applied). deleteSemantics: "remove" — Google and TikTok — means a removal is irreversible: the entity is gone, not archived, and nothing here brings it back. "archive_only" is Meta, whose archive is update_status with status archived, and that is undoable.

Renamed tools

The write surface was five narrow tools over four operations; it is draft_changes over every operation it drafts (the raw platform request is its own entity). The old names are deleted rather than aliased, because no external consumer held them.

• create_campaign_draft is draft_changes with one create_campaign entry.
• update_campaign_budget_draft is draft_changes with one update_budget entry, at whichever level holds the budget.
• update_campaign_status_draft is draft_changes with one update_status entry.
• approve_draft is approve_drafts, which takes a correlationId or a list of ids.
• reject_draft is reject_drafts, on the same selection.

Client setup

Claude Code

claude mcp add --transport http tempio https://app.tempio.ai/api/mcp --header "Authorization: Bearer YOUR_KEY"

Cursor (mcp.json)

{
  "mcpServers": {
    "tempio": {
      "url": "https://app.tempio.ai/api/mcp",
      "headers": { "Authorization": "Bearer YOUR_KEY" }
    }
  }
}

Any MCP client that can send an Authorization header over streamable HTTP works the same way. A client that cannot send a header of its own signs in through OAuth instead: OAuth for MCP clients.

The draft model

Every write from every client is a change request. A draft records who asked for it (a person, the in-app agent, or an MCP credential), what it changes, the state the entity was in before it, and the guardrail checks it passed. Applying it is a separate act under the approve scope: the guardrails run again, the change goes through the platform adapter, Tempio verifies it landed, and the audit log records it. The authority that cleared it is on the row either way — you, a credential you minted, or a rule your workspace wrote.