Create a paused Meta ad variant with MCP

Use Plainrouter MCP to propose a copy of a human-selected Meta ad with a different creative asset. The request creates a governed proposal. Ask waits for human approval; Full can automatically queue a policy-allowed copy; Landed requires verification of the resulting Meta ad. This walkthrough uses an image already in the connected account’s library. It covers Plainrouter’s governed workflow. For provider selection, see the Meta Ads MCP comparison.

Before you begin

You need a connected agent, a Write workspace key for the intended workspace, and the required creative and proposal permissions. Read get_account_state to confirm scope. A person must select the source ad; obtain the selected asset ID from the account’s creative library. Check the workspace’s action policy. Use Ask for this walkthrough so you can review the proposal before execution. In Full, an allowed proposal can queue automatically; asking the agent to stop after submission does not prevent that execution. These creative tools cannot activate the copy. Canonical pause, resume, and daily-budget changes use separate governed proposals.

Creative tool flow

Stage	Tool or surface	Expected result
Confirm access	`get_account_state`	Intended workspace, Meta ad account, and required permissions.
Read assets	`get-creative-library`	Account-owned asset IDs and pagination; this makes live Meta reads.
Propose the copy	`duplicate-ad-with-creative`	A Plainrouter proposal with its policy result and frozen mode.
Decide in Ask	Inbox	A human approves the stated consequence or rejects the proposal. Full can skip this waiting step.
Verify	Inbox and Audit	For executed work, receipt and exact verification of the new paused ad.

The anonymous MCP sandbox has no creative tools. Use the authenticated production connection for this workflow. Reading the library contacts Meta; submitting the proposal writes to Plainrouter and performs account-bound provider reads. It does not itself create the copied Meta ad.

Example: propose a paused creative variant

The request examples below contain arguments for the named MCP tools, not Signals REST API requests. Your MCP client wraps them in tools/call. Example IDs and response excerpts are illustrative; substitute your selected account’s actual values.

1. Confirm the account and read its images

Call get_account_state to inspect the workspace’s Signals-bound Meta account. Confirm it is also eligible for Actions in this workspace. For the creative calls below, supply account_id when multiple eligible active accounts exist; use that same intended account throughout. Confirm the returned workspace and Meta ad account, then check authorization.permissions for creative.read, creative.write, and actions.propose. Stop if the account or permissions do not match the intended task; issue the appropriate workspace token before proceeding. For this example, 91 is the internal Plainrouter account ID verified in the first read, not the Meta external account ID. Keep the same account_id across the workflow. Call get-creative-library with:

{
  "account_id": 91,
  "asset_type": "image",
  "limit": 10
}

An illustrative response excerpt is:

{
  "assets": [
    {
      "asset_id": "image:0123456789abcdef0123456789abcdef",
      "type": "image",
      "name": "product-detail.jpg"
    }
  ],
  "pagination": {
    "images": { "after": null, "has_more": false }
  },
  "performance_window": "last_30d"
}

Select an asset_id from the returned assets. The human-selected source ad is a separate numeric Meta ad ID; an image hash, ad-set ID, or preview URL is not a source ad ID. If pagination.images.has_more is true, repeat the image request with the returned pagination.images.after value as cursor. Preserve the cursor unchanged. An empty page does not prove the account has no assets of another type. If you need to add an image, complete image upload and its verification before returning here.

2. Submit one proposal for the selected pair

Call duplicate-ad-with-creative with the source ad selected by the person and the chosen asset. This example uses the illustrative image above:

{
  "account_id": 91,
  "source_ad": "120012345678901",
  "asset_id": "image:0123456789abcdef0123456789abcdef",
  "rationale": "Create the requested product-detail image variant for human review while keeping the copy paused.",
  "name_suffix": "review variant",
  "idempotency_key": "creative-review-order-123"
}

Persist the idempotency key with this intent and reuse it for an identical retry. Use a distinct key for a new proposal, such as a different selected image. Do not recycle a key while changing its arguments. There is no status argument: Plainrouter fixes params.status to paused. It re-reads the selected source and asset under the approved account before producing the proposal. Do not ask the agent to choose a different account, guess a target, or activate the copy when validation fails.

3. Read the proposal before requesting approval in Ask

A passing proposal in Ask can return this excerpt. Other fields, including scope, evidence, and the queue URL, are omitted here:

{
  "proposal": {
    "id": "01J8Z6W9F6N8Q2R5T7V0X3Y4ZA",
    "execution_mode_snapshot": "ask",
    "status": "pending",
    "policy_decision": "require_approval",
    "approval_required": true,
    "actions": [
      {
        "type": "duplicate_ad_with_creative",
        "target_entity": {
          "type": "ad",
          "id": "120012345678901"
        },
        "params": {
          "asset_id": "image:0123456789abcdef0123456789abcdef",
          "status": "paused",
          "name_suffix": "review variant"
        }
      }
    ]
  }
}

This result means the example proposal awaits a person. It does not identify a newly created Meta ad: actions[].target_entity.id still identifies the source ad. Check these fields in the complete response:

Field	What to verify
`id` and `scope`	Save the proposal ID and confirm the account and workspace.
`execution_mode_snapshot`	Confirm Ask for this walkthrough; Full can queue automatically. Historical suggest-only batches do not execute.
`status`, `policy_decision`, and `policy_reasons`	Read any block before requesting another proposal.
`approval_required` and `inbox_url`	Follow the returned queue link when a human decision is required.
`actions`	Confirm the source ad, chosen asset, and `params.status: "paused"`.

If the client reports a protocol error or a tool result with isError: true, do not interpret transport success as proposal creation. Read the error and inspect the queue before retrying an uncertain result. The MCP error model distinguishes protocol failures from tool execution failures.

4. Follow the human decision and final outcome

For the Ask example, open the returned inbox_url for Inbox. The older approval_queue_url field remains an alias to the same link. Review the proposal and its execution_mode_snapshot before using the generic Approve button. The decision applies to the containing batch, not just the selected action.

Outcome	What it proves	Next step
Approved without execution	The person accepted a historical suggest-only recommendation. No Meta copy was created.	Finish this recommendation; do not look for a new ad ID.
Approved or Executing	Execution was authorized and still must pass current policy.	Follow Inbox and Audit; approval alone is not Landed.
Blocked	Proposal-time or execution-time policy stopped the work.	Read the reason and policy constraints.
Executed pending verification	A provider write has a receipt, but verification is incomplete.	Inspect the recorded next read and deadline; the copy is Not Landed.
Completed and Landed for this executed creative batch	The resulting ad passed exact receipt-addressed verification.	Inspect the receipt’s new ad ID, account, creative and paused state.

For the Ask example above, Approve queues execution after fresh policy checks; it does not complete the walkthrough. Follow the receipt until the copy is verified. A historical suggest-only approval appears separately under Approval recorded, nothing sent and never creates a copy. Changing current policy does not rewrite that historical snapshot. For executed copies, verify both status=PAUSED and effective_status=PAUSED on the exact receipt-addressed ad. A verified paused copy is not an active campaign, a delivery result, or evidence of improved advertising performance. See Paused-copy invariant for pending verification and compensation.

Give your agent a bounded request

After selecting the actual source ad and asset, use a request like this:

Confirm the workspace is in Ask mode before submitting this proposal.
Use the connected Plainrouter account. First call get_account_state and confirm
its workspace, Meta ad account, and creative/proposal permissions. Read the image
library and confirm my selected asset is present.

Prepare one paused-copy proposal using the source ad ID and asset ID I supplied.
Reuse our saved idempotency key for an identical retry. Return the proposal ID,
policy reasons, execution-mode snapshot, and approval-queue link, then stop for
human review. Do not select another target or claim that an ad was created.

Creative library output

get-creative-library returns account-owned images and videos, asset metadata, pagination, associated ads, and aggregated last-30-day impressions, clicks, spend, and conversions.

Do not treat creative-library history as causal performance or proof that an asset is a winner. Durable proposal provenance records only identity, account ownership, readiness, and status.

When requesting asset_type: "all", pagination is returned separately for images and videos. To continue from a cursor, request either image or video.

Image upload rules

Before staging an image, check its JPEG/PNG dimensions and crop for the intended placements. Meta image specifications explains placement review. Meeting a documented specification does not prove Meta acceptance; verify the upload through its execution receipt. If the image is not already in Meta, upload-asset privately stages its bytes and creates a separate upload_asset proposal. It does not immediately produce an uploaded Meta image. Ask requires approval; Full can queue a policy-allowed upload automatically. Wait for verified provider completion, then call get-creative-library again to select the returned image:<hash>. Do not use the staged manifest ID as the asset ID for duplication. The upload-asset convenience tool accepts:

account_id when needed to select the same authorized account
asset_type: "image"
A bare .jpg, .jpeg, or .png filename, up to 100 characters, that matches the detected content type; no directory path
Raw base64 bytes without a data URI prefix
A rationale of up to 1,000 characters
A stable idempotency key of up to 64 characters

The configured upload limit is 5 MiB unless the deployment overrides it. Reusing the same idempotency key with different bytes is rejected. Video assets can be read from the Meta creative library and used for ad duplication. New video upload execution is not supported in this release.

Paused-copy invariant

A duplicate must be created and verified with both configured and effective status equal to PAUSED. Creating a copy never activates it. A later governed resume action is a separate proposal that uses Ask or Full and its own policy checks. If Meta reports IN_PROCESS, the batch moves to Executed pending verification and remains Not Landed. Plainrouter performs scheduled reads for up to 48 hours. Contradictory state, rejection, or expiry triggers verified compensation, which archives the receipt-addressed copy.

Safe retries

Both proposal-producing creative tools are idempotent. Reuse the same idempotency key when retrying the same intent. Do not generate a new key merely because an MCP request timed out. After a timeout, check the returned or existing proposal in Inbox before attempting another action. Provider reconciliation uses the durable execution key and receipt to avoid silently creating duplicate objects.

Common failures

Symptom	Next step
Missing creative permission	Check the token tier, active grant, and account scope in workspace tokens.
Source ad or asset rejected	Re-read the intended account’s library and confirm the human-selected source belongs to that account. Do not substitute a guessed asset ID.
Upload rejected	Check detected JPEG/PNG content, a bare filename, raw base64 without a data URI prefix, byte limit, and reuse of the idempotency key.
Cursor rejected	Continue with `asset_type: "image"` or `"video"`, not `"all"`, and use the corresponding returned cursor.
Approved, but no new Meta ad	Check `execution_mode_snapshot`. A suggest-only approval records a recommendation without execution.
Request timed out	Check the existing proposal in the queue and retry only the same intent with the saved key.
Proposal blocked	Read its policy reasons and current policy constraints; approval does not bypass them.
Ad remains Not Landed	Follow the status in Inbox and receipt events in Audit. Do not activate or duplicate it to bypass verification.

Get started

Signals

Actions

Reference

Legacy Launcher

Create a paused Meta ad variant with MCP

Before you begin

Creative tool flow

Example: propose a paused creative variant

1. Confirm the account and read its images

2. Submit one proposal for the selected pair

3. Read the proposal before requesting approval in Ask

4. Follow the human decision and final outcome

Give your agent a bounded request

Creative library output

Image upload rules

Paused-copy invariant

Safe retries

Common failures

​Before you begin

​Creative tool flow

​Example: propose a paused creative variant

​1. Confirm the account and read its images

​2. Submit one proposal for the selected pair

​3. Read the proposal before requesting approval in Ask

​4. Follow the human decision and final outcome

​Give your agent a bounded request

​Creative library output

​Image upload rules

​Paused-copy invariant

​Safe retries

​Common failures

Before you begin

Creative tool flow

Example: propose a paused creative variant

1. Confirm the account and read its images

2. Submit one proposal for the selected pair

3. Read the proposal before requesting approval in Ask

4. Follow the human decision and final outcome

Give your agent a bounded request

Creative library output

Image upload rules

Paused-copy invariant

Safe retries

Common failures