Plainrouter

Official15 tools

by plainrouter · PHP

Meta Ads MCP: read ad accounts and signal health; propose governed changes under Ask or Full.

com.plainrouter/mcp (MCP) Server

The com.plainrouter/mcp Model Context Protocol (MCP) server inspects an approved ad account and first-party signal health. It then proposes policy-gated actions based on the inspected account and signal status.

🛠️ Key Features

Inspects an approved ad account
Evaluates first-party signal health
Proposes policy-gated actions

🚀 Use Cases

Reviewing approved ad account status
Checking health of first-party signals
Generating actions subject to policy gating

⚡ Developer Benefits

Provides structured inspection followed by action proposals
Supports workflows that require policy-gated outcomes

Topics

agent-skillsai-agentsclimcpopenapisdkplainrouterconversions-apifacebook-adsmcp-servermeta-adsmeta-ads-mcpmodel-context-protocol

Captured live from the server via tools/list.

get_account_state

Return the authorized advertising account, workspace, connection, Signal destination, and currently available account capabilities. This read-only inspection tool does not change the account.

Parameters2

workspace_id	integer	optional	Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces.
account_id	integer	optional	Advertising account ID. Signals reads use the workspace Meta destination when omitted; other tools may require an ID when multiple accounts are active.

Raw schema

{
  "type": "object",
  "properties": {
    "workspace_id": {
      "description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces.",
      "minimum": 1,
      "type": "integer"
    },
    "account_id": {
      "description": "Advertising account ID. Signals reads use the workspace Meta destination when omitted; other tools may require an ID when multiple accounts are active.",
      "minimum": 1,
      "type": "integer"
    }
  }
}

get_account_inventory

Read the authorized workspace account inventory from the Meta mirror, with optional level, status, parent, and ID cursor filters.

Parameters8

workspace_id	integer	optional	Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces.
account_id	integer	required	Advertising account ID available to the authorized workspace.
level	string	optional	Limit results to campaign, adset, or ad objects.
effective_status	string	optional	Filter by Meta effective status, such as ACTIVE, PAUSED, or ARCHIVED.
campaign_id	string	optional	Filter to objects under this parent campaign ID.
adset_id	string	optional	Filter to objects under this parent ad set ID.
after_id	integer	optional	Database ID cursor from the previous page; continue with its last object ID.
limit	integer	optional	Maximum objects to return, from 1 to 200.

Raw schema

{
  "type": "object",
  "properties": {
    "workspace_id": {
      "description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces.",
      "minimum": 1,
      "type": "integer"
    },
    "account_id": {
      "description": "Advertising account ID available to the authorized workspace.",
      "minimum": 1,
      "type": "integer"
    },
    "level": {
      "description": "Limit results to campaign, adset, or ad objects.",
      "enum": [
        "campaign",
        "adset",
        "ad"
      ],
      "type": "string"
    },
    "effective_status": {
      "description": "Filter by Meta effective status, such as ACTIVE, PAUSED, or ARCHIVED.",
      "type": "string"
    },
    "campaign_id": {
      "description": "Filter to objects under this parent campaign ID.",
      "type": "string"
    },
    "adset_id": {
      "description": "Filter to objects under this parent ad set ID.",
      "type": "string"
    },
    "after_id": {
      "description": "Database ID cursor from the previous page; continue with its last object ID.",
      "minimum": 1,
      "type": "integer"
    },
    "limit": {
      "description": "Maximum objects to return, from 1 to 200.",
      "default": 100,
      "minimum": 1,
      "maximum": 200,
      "type": "integer"
    }
  },
  "required": [
    "account_id"
  ]
}

list_workspaces

List the workspaces and effective access tiers in this credential scope.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

get_signal_health

Diagnostic view of first-party event flow, Meta delivery outcomes, match quality, and reconciliation gaps from Plainrouter stored measurements. Not admissible evidence for spend-affecting proposals. Does not call the Marketing API.

Parameters4

workspace_id	integer	optional	Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces.
account_id	integer	optional	Advertising account ID. Signals reads use the workspace Meta destination when omitted; other tools may require an ID when multiple accounts are active.
days	integer	optional	Trailing window in days. One of 7, 30, 90.
months	integer	optional	Trailing window of 12 calendar months, in place of days. Offered only where the workspace plan keeps that history and the workspace is set to keep it.

Raw schema

{
  "type": "object",
  "properties": {
    "workspace_id": {
      "description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces.",
      "minimum": 1,
      "type": "integer"
    },
    "account_id": {
      "description": "Advertising account ID. Signals reads use the workspace Meta destination when omitted; other tools may require an ID when multiple accounts are active.",
      "minimum": 1,
      "type": "integer"
    },
    "days": {
      "description": "Trailing window in days. One of 7, 30, 90.",
      "default": 7,
      "enum": [
        7,
        30,
        90
      ],
      "minimum": 7,
      "maximum": 90,
      "type": "integer"
    },
    "months": {
      "description": "Trailing window of 12 calendar months, in place of days. Offered only where the workspace plan keeps that history and the workspace is set to keep it.",
      "enum": [
        12
      ],
      "type": "integer"
    }
  }
}

get_performance

Admissible proposal evidence: reconciliation meta_reported is the existing Meta-reported conversions count compared with gateway_verified accepted conversions. The separate purchases block shows Meta-reported Purchase counts under the account attribution setting beside Plainrouter accepted server-side Purchase counts, with its completed account-local window start and end dates and no purchase gap or status. Includes stored daily Meta spend and delivery metrics. platform_claimed_clicks means Meta outbound clicks. Days before 2026-06-29, or not re-read by the daily sync since 2026-09-27, may still hold Meta link clicks or all clicks.

Parameters3

workspace_id	integer	optional	Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces.
account_id	integer	optional	Advertising account ID. Signals reads use the workspace Meta destination when omitted; other tools may require an ID when multiple accounts are active.
days	integer	optional	Number of reporting days to compare, from 1 to 90.

Raw schema

{
  "type": "object",
  "properties": {
    "workspace_id": {
      "description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces.",
      "minimum": 1,
      "type": "integer"
    },
    "account_id": {
      "description": "Advertising account ID. Signals reads use the workspace Meta destination when omitted; other tools may require an ID when multiple accounts are active.",
      "minimum": 1,
      "type": "integer"
    },
    "days": {
      "description": "Number of reporting days to compare, from 1 to 90.",
      "default": 7,
      "minimum": 1,
      "maximum": 90,
      "type": "integer"
    }
  }
}

get_inventory_metrics

Read daily Meta metrics beside counted PlainRouter arrivals for mirrored campaigns, ad sets and ads. object_metrics contains account-timezone daily comparisons; unmatched_arrivals is one workspace/window count without unknown IDs. Counts are null when the arrivals store is disabled. Optional change history is retention-clamped.

Parameters8

workspace_id	integer	optional	Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces.
account_id	integer	required	Advertising account ID available to the authorized workspace.
start_date	string	optional	Inclusive start date in YYYY-MM-DD format.
end_date	string	optional	Inclusive end date in YYYY-MM-DD format.
campaign_id	string	optional	Limit metrics to this campaign ID.
adset_id	string	optional	Limit metrics to this ad set ID.
ad_id	string	optional	Limit metrics to this ad ID.
include_changes	boolean	optional	Include object change history within the effective date window.

Raw schema

{
  "type": "object",
  "properties": {
    "workspace_id": {
      "description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces.",
      "minimum": 1,
      "type": "integer"
    },
    "account_id": {
      "description": "Advertising account ID available to the authorized workspace.",
      "minimum": 1,
      "type": "integer"
    },
    "start_date": {
      "description": "Inclusive start date in YYYY-MM-DD format.",
      "type": "string"
    },
    "end_date": {
      "description": "Inclusive end date in YYYY-MM-DD format.",
      "type": "string"
    },
    "campaign_id": {
      "description": "Limit metrics to this campaign ID.",
      "type": "string"
    },
    "adset_id": {
      "description": "Limit metrics to this ad set ID.",
      "type": "string"
    },
    "ad_id": {
      "description": "Limit metrics to this ad ID.",
      "type": "string"
    },
    "include_changes": {
      "description": "Include object change history within the effective date window.",
      "default": false,
      "type": "boolean"
    }
  },
  "required": [
    "account_id"
  ]
}

verify_signal_ingestion

Verify server-side Signal ingestion by writing one idempotent, identity-free modeled event for the authorized workspace. This confirms ledger receipt but does not count as real arrival evidence or complete onboarding. No spend capability.

Parameters1

workspace_id

integer

optional

Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces.

Raw schema

{
  "type": "object",
  "properties": {
    "workspace_id": {
      "description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces.",
      "minimum": 1,
      "type": "integer"
    }
  }
}

propose-actions

Propose a batch of budget, status, upload, or creative-duplication actions for the approved ad account. In Ask, every policy-allowed change waits for a person to approve it. In Full, policy-allowed changes run automatically. Rule violations are blocked and shown in the Inbox, and cannot be approved. The execution kill switch stops further writes and never undoes a landed change. Dispatch still requires a live grant, an account in the workspace, and no duplicate write. Legacy set_status and adjust_budget never run.

Parameters7

actions	array	required
rationale	string	required
idempotency_key	string	required
evidence	array	required
target_source	string	required
account_id	integer	optional
workspace_id	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "actions": {
      "minItems": 1,
      "maxItems": 25,
      "items": {
        "anyOf": [
          {
            "properties": {
              "type": {
                "enum": [
                  "increase_budget"
                ],
                "type": "string"
              },
              "target_entity": {
                "additionalProperties": false,
                "properties": {
                  "type": {
                    "enum": [
                      "ad_account",
                      "campaign",
                      "ad_set",
                      "ad"
                    ],
                    "maxLength": 64,
                    "type": "string"
                  },
                  "id": {
                    "maxLength": 128,
                    "pattern": "^[0-9]+$",
                    "type": "string"
                  },
                  "name": {
                    "maxLength": 255,
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "type": "object",
                "required": [
                  "type",
                  "id"
                ]
              },
              "params": {
                "additionalProperties": false,
                "properties": {
                  "new_daily_budget_minor": {
                    "minimum": 1,
                    "type": "integer"
                  }
                },
                "type": "object",
                "required": [
                  "new_daily_budget_minor"
                ]
              },
              "rationale": {
                "maxLength": 2000,
                "type": "string"
              },
              "idempotency_key": {
                "maxLength": 255,
                "type": "string"
              }
            },
            "type": "object",
            "required": [
              "type",
              "target_entity",
              "params",
              "rationale"
            ]
          },
          {
            "properties": {
              "type": {
                "enum": [
                  "decrease_budget"
                ],
                "type": "string"
              },
              "target_entity": {
                "additionalProperties": false,
                "properties": {
                  "type": {
                    "enum": [
                      "ad_account",
                      "campaign",
                      "ad_set",
                      "ad"
                    ],
                    "maxLength": 64,
                    "type": "string"
                  },
                  "id": {
                    "maxLength": 128,
                    "pattern": "^[0-9]+$",
                    "type": "string"
                  },
                  "name": {
                    "maxLength": 255,
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "type": "object",
                "required": [
                  "type",
                  "id"
                ]
              },
              "params": {
                "additionalProperties": false,
                "properties": {
                  "new_daily_budget_minor": {
                    "minimum": 1,
                    "type": "integer"
                  }
                },
                "type": "object",
                "required": [
                  "new_daily_budget_minor"
                ]
              },
              "rationale": {
                "maxLength": 2000,
                "type": "string"
              },
              "idempotency_key": {
                "maxLength": 255,
                "type": "string"
              }
            },
            "type": "object",
            "required": [
              "type",
              "target_entity",
              "params",
              "rationale"
            ]
          },
          {
            "properties": {
              "type": {
                "enum": [
                  "pause"
                ],
                "type": "string"
              },
              "target_entity": {
                "additionalProperties": false,
                "properties": {
                  "type": {
                    "enum": [
                      "ad_account",
                      "campaign",
                      "ad_set",
                      "ad"
                    ],
                    "maxLength": 64,
                    "type": "string"
                  },
                  "id": {
                    "maxLength": 128,
                    "pattern": "^[0-9]+$",
                    "type": "string"
                  },
                  "name": {
                    "maxLength": 255,
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "type": "object",
                "required": [
                  "type",
                  "id"
                ]
              },
              "params": {
                "additionalProperties": false,
                "type": "object"
              },
              "rationale": {
                "maxLength": 2000,
                "type": "string"
              },
              "idempotency_key": {
                "maxLength": 255,
                "type": "string"
              }
            },
            "type": "object",
            "required": [
              "type",
              "target_entity",
              "params",
              "rationale"
            ]
          },
          {
            "properties": {
              "type": {
                "enum": [
                  "resume"
                ],
                "type": "string"
              },
              "target_entity": {
                "additionalProperties": false,
                "properties": {
                  "type": {
                    "enum": [
                      "ad_account",
                      "campaign",
                      "ad_set",
                      "ad"
                    ],
                    "maxLength": 64,
                    "type": "string"
                  },
                  "id": {
                    "maxLength": 128,
                    "pattern": "^[0-9]+$",
                    "type": "string"
                  },
                  "name": {
                    "maxLength": 255,
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "type": "object",
                "required": [
                  "type",
                  "id"
                ]
              },
              "params": {
                "additionalProperties": false,
                "type": "object"
              },
              "rationale": {
                "maxLength": 2000,
                "type": "string"
              },
              "idempotency_key": {
                "maxLength": 255,
                "type": "string"
              }
            },
            "type": "object",
            "required": [
              "type",
              "target_entity",
              "params",
              "rationale"
            ]
          },
          {
            "properties": {
              "type": {
                "enum": [
                  "replace_creative"
                ],
                "type": "string"
              },
              "target_entity": {
                "additionalProperties": false,
                "properties": {
                  "type": {
                    "enum": [
                      "ad_account",
                      "campaign",
                      "ad_set",
                      "ad"
                    ],
                    "maxLength": 64,
                    "type": "string"
                  },
                  "id": {
                    "maxLength": 128,
                    "type": "string"
                  },
                  "name": {
                    "maxLength": 255,
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "type": "object",
                "required": [
                  "type",
                  "id"
                ]
              },
              "params": {
                "type": "object"
              },
              "rationale": {
                "maxLength": 2000,
                "type": "string"
              },
              "idempotency_key": {
                "maxLength": 255,
                "type": "string"
              }
            },
            "type": "object",
            "required": [
              "type",
              "target_entity",
              "params",
              "rationale"
            ]
          },
          {
            "properties": {
              "type": {
                "enum": [
                  "shift_spend"
                ],
                "type": "string"
              },
              "target_entity": {
                "additionalProperties": false,
                "properties": {
                  "type": {
                    "enum": [
                      "ad_account",
                      "campaign",
                      "ad_set",
                      "ad"
                    ],
                    "maxLength": 64,
                    "type": "string"
                  },
                  "id": {
                    "maxLength": 128,
                    "type": "string"
                  },
                  "name": {
                    "maxLength": 255,
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "type": "object",
                "required": [
                  "type",
                  "id"
                ]
              },
              "params": {
                "type": "object"
              },
              "rationale": {
                "maxLength": 2000,
                "type": "string"
              },
              "idempotency_key": {
                "maxLength": 255,
                "type": "string"
              }
            },
            "type": "object",
            "required": [
              "type",
              "target_entity",
              "params",
              "rationale"
            ]
          },
          {
            "properties": {
              "type": {
                "enum": [
                  "rollback"
                ],
                "type": "string"
              },
              "target_entity": {
                "additionalProperties": false,
                "properties": {
                  "type": {
                    "enum": [
                      "ad_account",
                      "campaign",
                      "ad_set",
                      "ad"
                    ],
                    "maxLength": 64,
                    "type": "string"
                  },
                  "id": {
                    "maxLength": 128,
                    "type": "string"
                  },
                  "name": {
                    "maxLength": 255,
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "type": "object",
                "required": [
                  "type",
                  "id"
                ]
              },
              "params": {
                "type": "object"
              },
              "rationale": {
                "maxLength": 2000,
                "type": "string"
              },
              "idempotency_key": {
                "maxLength": 255,
                "type": "string"
              }
            },
            "type": "object",
            "required": [
              "type",
              "target_entity",
              "params",
              "rationale"
            ]
          },
          {
            "properties": {
              "type": {
                "enum": [
                  "create_campaign"
                ],
                "type": "string"
              },
              "target_entity": {
                "additionalProperties": false,
                "properties": {
                  "type": {
                    "enum": [
                      "ad_account",
                      "campaign",
                      "ad_set",
                      "ad"
                    ],
                    "maxLength": 64,
                    "type": "string"
                  },
                  "id": {
                    "maxLength": 128,
                    "type": "string"
                  },
                  "name": {
                    "maxLength": 255,
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "type": "object",
                "required": [
                  "type",
                  "id"
                ]
              },
              "params": {
                "type": "object"
              },
              "rationale": {
                "maxLength": 2000,
                "type": "string"
              },
              "idempotency_key": {
                "maxLength": 255,
                "type": "string"
              }
            },
            "type": "object",
            "required": [
              "type",
              "target_entity",
              "params",
              "rationale"
            ]
          },
          {
            "properties": {
              "type": {
                "enum": [
                  "create_ad_set"
                ],
                "type": "string"
              },
              "target_entity": {
                "additionalProperties": false,
                "properties": {
                  "type": {
                    "enum": [
                      "ad_account",
                      "campaign",
                      "ad_set",
                      "ad"
                    ],
                    "maxLength": 64,
                    "type": "string"
                  },
                  "id": {
                    "maxLength": 128,
                    "type": "string"
                  },
                  "name": {
                    "maxLength": 255,
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "type": "object",
                "required": [
                  "type",
                  "id"
                ]
              },
              "params": {
                "type": "object"
              },
              "rationale": {
                "maxLength": 2000,
                "type": "string"
              },
              "idempotency_key": {
                "maxLength": 255,
                "type": "string"
              }
            },
            "type": "object",
            "required": [
              "type",
              "target_entity",
              "params",
              "rationale"
            ]
          },
          {
            "properties": {
              "type": {
                "enum": [
                  "create_ad"
                ],
                "type": "string"
              },
              "target_entity": {
                "additionalProperties": false,
                "properties": {
                  "type": {
                    "enum": [
                      "ad_account",
                      "campaign",
                      "ad_set",
                      "ad"
                    ],
                    "maxLength": 64,
                    "type": "string"
                  },
                  "id": {
                    "maxLength": 128,
                    "type": "string"
                  },
                  "name": {
                    "maxLength": 255,
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "type": "object",
                "required": [
                  "type",
                  "id"
                ]
              },
              "params": {
                "type": "object"
              },
              "rationale": {
                "maxLength": 2000,
                "type": "string"
              },
              "idempotency_key": {
                "maxLength": 255,
                "type": "string"
              }
            },
            "type": "object",
            "required": [
              "type",
              "target_entity",
              "params",
              "rationale"
            ]
          },
          {
            "properties": {
              "type": {
                "enum": [
                  "upload_asset"
                ],
                "type": "string"
              },
              "target_entity": {
                "additionalProperties": false,
                "properties": {
                  "type": {
                    "enum": [
                      "ad_account",
                      "campaign",
                      "ad_set",
                      "ad"
                    ],
                    "maxLength": 64,
                    "type": "string"
                  },
                  "id": {
                    "maxLength": 128,
                    "type": "string"
                  },
                  "name": {
                    "maxLength": 255,
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "type": "object",
                "required": [
                  "type",
                  "id"
                ]
              },
              "params": {
                "properties": {
                  "staged_asset_id": {
                    "maxLength": 255,
                    "pattern": "^stage_[a-f0-9]{40}$",
                    "type": "string"
                  },
                  "asset_type": {
                    "enum": [
                      "image"
                    ],
                    "type": "string"
                  },
                  "filename": {
                    "maxLength": 255,
                    "type": "string"
                  },
                  "content_sha256": {
                    "pattern": "^[a-f0-9]{64}$",
                    "type": "string"
                  },
                  "mime_type": {
                    "maxLength": 255,
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "size_bytes": {
                    "minimum": 1,
                    "type": [
                      "integer",
                      "null"
                    ]
                  }
                },
                "type": "object",
                "required": [
                  "staged_asset_id",
                  "asset_type",
                  "filename",
                  "content_sha256"
                ]
              },
              "rationale": {
                "maxLength": 2000,
                "type": "string"
              },
              "idempotency_key": {
                "maxLength": 255,
                "type": "string"
              }
            },
            "type": "object",
            "required": [
              "type",
              "target_entity",
              "params",
              "rationale"
            ]
          },
          {
            "properties": {
              "type": {
                "enum": [
                  "adjust_budget"
                ],
                "type": "string"
              },
              "target_entity": {
                "additionalProperties": false,
                "properties": {
                  "type": {
                    "enum": [
                      "ad_account",
                      "campaign",
                      "ad_set",
                      "ad"
                    ],
                    "maxLength": 64,
                    "type": "string"
                  },
                  "id": {
                    "maxLength": 128,
                    "type": "string"
                  },
                  "name": {
                    "maxLength": 255,
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "type": "object",
                "required": [
                  "type",
                  "id"
                ]
              },
              "params": {
                "properties": {
                  "new_daily_budget_minor": {
                    "minimum": 1,
                    "type": "integer"
                  }
                },
                "type": "object",
                "required": [
                  "new_daily_budget_minor"
                ]
              },
              "rationale": {
                "maxLength": 2000,
                "type": "string"
              },
              "idempotency_key": {
                "maxLength": 255,
                "type": "string"
              }
            },
            "type": "object",
            "required": [
              "type",
              "target_entity",
              "params",
              "rationale"
            ]
          },
          {
            "properties": {
              "type": {
                "enum": [
                  "set_status"
                ],
                "type": "string"
              },
              "target_entity": {
                "additionalProperties": false,
                "properties": {
                  "type": {
                    "enum": [
                      "ad_account",
                      "campaign",
                      "ad_set",
                      "ad"
                    ],
                    "maxLength": 64,
                    "type": "string"
                  },
                  "id": {
                    "maxLength": 128,
                    "type": "string"
                  },
                  "name": {
                    "maxLength": 255,
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "type": "object",
                "required": [
                  "type",
                  "id"
                ]
              },
              "params": {
                "properties": {
                  "status": {
                    "enum": [
                      "active",
                      "paused"
                    ],
                    "type": "string"
                  }
                },
                "type": "object",
                "required": [
                  "status"
                ]
              },
              "rationale": {
                "maxLength": 2000,
                "type": "string"
              },
              "idempotency_key": {
                "maxLength": 255,
                "type": "string"
              }
            },
            "type": "object",
            "required": [
              "type",
              "target_entity",
              "params",
              "rationale"
            ]
          },
          {
            "properties": {
              "type": {
                "enum": [
                  "duplicate_ad_with_creative"
                ],
                "type": "string"
              },
              "target_entity": {
                "additionalProperties": false,
                "properties": {
                  "type": {
                    "enum": [
                      "ad_account",
                      "campaign",
                      "ad_set",
                      "ad"
                    ],
                    "maxLength": 64,
                    "type": "string"
                  },
                  "id": {
                    "maxLength": 128,
                    "type": "string"
                  },
                  "name": {
                    "maxLength": 255,
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "type": "object",
                "required": [
                  "type",
                  "id"
                ]
              },
              "params": {
                "properties": {
                  "asset_id": {
                    "maxLength": 255,
                    "pattern": "^(image|video):.+$",
                    "type": "string"
                  },
                  "status": {
                    "enum": [
                      "paused"
                    ],
                    "type": "string"
                  },
                  "name_suffix": {
                    "maxLength": 100,
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "type": "object",
                "required": [
                  "asset_id",
                  "status"
                ]
              },
              "rationale": {
                "maxLength": 2000,
                "type": "string"
              },
              "idempotency_key": {
                "maxLength": 255,
                "type": "string"
              }
            },
            "type": "object",
            "required": [
              "type",
              "target_entity",
              "params",
              "rationale"
            ]
          }
        ]
      },
      "type": "array"
    },
    "rationale": {
      "maxLength": 4000,
      "type": "string"
    },
    "idempotency_key": {
      "maxLength": 64,
      "type": "string"
    },
    "evidence": {
      "minItems": 1,
      "maxItems": 3,
      "items": {
        "additionalProperties": false,
        "properties": {
          "source_tool": {
            "enum": [
              "get_account_state",
              "get_signal_health",
              "get_performance",
              "get-creative-library",
              "staged-asset-manifest"
            ],
            "type": "string"
          },
          "fields_used": {
            "minItems": 1,
            "maxItems": 50,
            "items": {
              "maxLength": 255,
              "type": "string"
            },
            "type": "array"
          },
          "action_index": {
            "minimum": 0,
            "type": "integer"
          }
        },
        "type": "object",
        "required": [
          "source_tool",
          "fields_used"
        ]
      },
      "type": "array"
    },
    "target_source": {
      "enum": [
        "human_supplied"
      ],
      "type": "string"
    },
    "account_id": {
      "minimum": 1,
      "type": "integer"
    },
    "workspace_id": {
      "minimum": 1,
      "type": "integer"
    }
  },
  "required": [
    "actions",
    "rationale",
    "idempotency_key",
    "evidence",
    "target_source"
  ]
}

dry_run_actions

Preview policy decisions and execution diffs for a proposed Action batch without writing it.

Parameters7

actions	array	required
rationale	string	required
idempotency_key	string	required
evidence	array	required
target_source	string	required
account_id	integer	optional
workspace_id	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "actions": {
      "minItems": 1,
      "maxItems": 25,
      "items": {
        "anyOf": [
          {
            "properties": {
              "type": {
                "enum": [
                  "increase_budget"
                ],
                "type": "string"
              },
              "target_entity": {
                "additionalProperties": false,
                "properties": {
                  "type": {
                    "enum": [
                      "ad_account",
                      "campaign",
                      "ad_set",
                      "ad"
                    ],
                    "maxLength": 64,
                    "type": "string"
                  },
                  "id": {
                    "maxLength": 128,
                    "pattern": "^[0-9]+$",
                    "type": "string"
                  },
                  "name": {
                    "maxLength": 255,
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "type": "object",
                "required": [
                  "type",
                  "id"
                ]
              },
              "params": {
                "additionalProperties": false,
                "properties": {
                  "new_daily_budget_minor": {
                    "minimum": 1,
                    "type": "integer"
                  }
                },
                "type": "object",
                "required": [
                  "new_daily_budget_minor"
                ]
              },
              "rationale": {
                "maxLength": 2000,
                "type": "string"
              },
              "idempotency_key": {
                "maxLength": 255,
                "type": "string"
              }
            },
            "type": "object",
            "required": [
              "type",
              "target_entity",
              "params",
              "rationale"
            ]
          },
          {
            "properties": {
              "type": {
                "enum": [
                  "decrease_budget"
                ],
                "type": "string"
              },
              "target_entity": {
                "additionalProperties": false,
                "properties": {
                  "type": {
                    "enum": [
                      "ad_account",
                      "campaign",
                      "ad_set",
                      "ad"
                    ],
                    "maxLength": 64,
                    "type": "string"
                  },
                  "id": {
                    "maxLength": 128,
                    "pattern": "^[0-9]+$",
                    "type": "string"
                  },
                  "name": {
                    "maxLength": 255,
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "type": "object",
                "required": [
                  "type",
                  "id"
                ]
              },
              "params": {
                "additionalProperties": false,
                "properties": {
                  "new_daily_budget_minor": {
                    "minimum": 1,
                    "type": "integer"
                  }
                },
                "type": "object",
                "required": [
                  "new_daily_budget_minor"
                ]
              },
              "rationale": {
                "maxLength": 2000,
                "type": "string"
              },
              "idempotency_key": {
                "maxLength": 255,
                "type": "string"
              }
            },
            "type": "object",
            "required": [
              "type",
              "target_entity",
              "params",
              "rationale"
            ]
          },
          {
            "properties": {
              "type": {
                "enum": [
                  "pause"
                ],
                "type": "string"
              },
              "target_entity": {
                "additionalProperties": false,
                "properties": {
                  "type": {
                    "enum": [
                      "ad_account",
                      "campaign",
                      "ad_set",
                      "ad"
                    ],
                    "maxLength": 64,
                    "type": "string"
                  },
                  "id": {
                    "maxLength": 128,
                    "pattern": "^[0-9]+$",
                    "type": "string"
                  },
                  "name": {
                    "maxLength": 255,
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "type": "object",
                "required": [
                  "type",
                  "id"
                ]
              },
              "params": {
                "additionalProperties": false,
                "type": "object"
              },
              "rationale": {
                "maxLength": 2000,
                "type": "string"
              },
              "idempotency_key": {
                "maxLength": 255,
                "type": "string"
              }
            },
            "type": "object",
            "required": [
              "type",
              "target_entity",
              "params",
              "rationale"
            ]
          },
          {
            "properties": {
              "type": {
                "enum": [
                  "resume"
                ],
                "type": "string"
              },
              "target_entity": {
                "additionalProperties": false,
                "properties": {
                  "type": {
                    "enum": [
                      "ad_account",
                      "campaign",
                      "ad_set",
                      "ad"
                    ],
                    "maxLength": 64,
                    "type": "string"
                  },
                  "id": {
                    "maxLength": 128,
                    "pattern": "^[0-9]+$",
                    "type": "string"
                  },
                  "name": {
                    "maxLength": 255,
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "type": "object",
                "required": [
                  "type",
                  "id"
                ]
              },
              "params": {
                "additionalProperties": false,
                "type": "object"
              },
              "rationale": {
                "maxLength": 2000,
                "type": "string"
              },
              "idempotency_key": {
                "maxLength": 255,
                "type": "string"
              }
            },
            "type": "object",
            "required": [
              "type",
              "target_entity",
              "params",
              "rationale"
            ]
          },
          {
            "properties": {
              "type": {
                "enum": [
                  "replace_creative"
                ],
                "type": "string"
              },
              "target_entity": {
                "additionalProperties": false,
                "properties": {
                  "type": {
                    "enum": [
                      "ad_account",
                      "campaign",
                      "ad_set",
                      "ad"
                    ],
                    "maxLength": 64,
                    "type": "string"
                  },
                  "id": {
                    "maxLength": 128,
                    "type": "string"
                  },
                  "name": {
                    "maxLength": 255,
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "type": "object",
                "required": [
                  "type",
                  "id"
                ]
              },
              "params": {
                "type": "object"
              },
              "rationale": {
                "maxLength": 2000,
                "type": "string"
              },
              "idempotency_key": {
                "maxLength": 255,
                "type": "string"
              }
            },
            "type": "object",
            "required": [
              "type",
              "target_entity",
              "params",
              "rationale"
            ]
          },
          {
            "properties": {
              "type": {
                "enum": [
                  "shift_spend"
                ],
                "type": "string"
              },
              "target_entity": {
                "additionalProperties": false,
                "properties": {
                  "type": {
                    "enum": [
                      "ad_account",
                      "campaign",
                      "ad_set",
                      "ad"
                    ],
                    "maxLength": 64,
                    "type": "string"
                  },
                  "id": {
                    "maxLength": 128,
                    "type": "string"
                  },
                  "name": {
                    "maxLength": 255,
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "type": "object",
                "required": [
                  "type",
                  "id"
                ]
              },
              "params": {
                "type": "object"
              },
              "rationale": {
                "maxLength": 2000,
                "type": "string"
              },
              "idempotency_key": {
                "maxLength": 255,
                "type": "string"
              }
            },
            "type": "object",
            "required": [
              "type",
              "target_entity",
              "params",
              "rationale"
            ]
          },
          {
            "properties": {
              "type": {
                "enum": [
                  "rollback"
                ],
                "type": "string"
              },
              "target_entity": {
                "additionalProperties": false,
                "properties": {
                  "type": {
                    "enum": [
                      "ad_account",
                      "campaign",
                      "ad_set",
                      "ad"
                    ],
                    "maxLength": 64,
                    "type": "string"
                  },
                  "id": {
                    "maxLength": 128,
                    "type": "string"
                  },
                  "name": {
                    "maxLength": 255,
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "type": "object",
                "required": [
                  "type",
                  "id"
                ]
              },
              "params": {
                "type": "object"
              },
              "rationale": {
                "maxLength": 2000,
                "type": "string"
              },
              "idempotency_key": {
                "maxLength": 255,
                "type": "string"
              }
            },
            "type": "object",
            "required": [
              "type",
              "target_entity",
              "params",
              "rationale"
            ]
          },
          {
            "properties": {
              "type": {
                "enum": [
                  "create_campaign"
                ],
                "type": "string"
              },
              "target_entity": {
                "additionalProperties": false,
                "properties": {
                  "type": {
                    "enum": [
                      "ad_account",
                      "campaign",
                      "ad_set",
                      "ad"
                    ],
                    "maxLength": 64,
                    "type": "string"
                  },
                  "id": {
                    "maxLength": 128,
                    "type": "string"
                  },
                  "name": {
                    "maxLength": 255,
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "type": "object",
                "required": [
                  "type",
                  "id"
                ]
              },
              "params": {
                "type": "object"
              },
              "rationale": {
                "maxLength": 2000,
                "type": "string"
              },
              "idempotency_key": {
                "maxLength": 255,
                "type": "string"
              }
            },
            "type": "object",
            "required": [
              "type",
              "target_entity",
              "params",
              "rationale"
            ]
          },
          {
            "properties": {
              "type": {
                "enum": [
                  "create_ad_set"
                ],
                "type": "string"
              },
              "target_entity": {
                "additionalProperties": false,
                "properties": {
                  "type": {
                    "enum": [
                      "ad_account",
                      "campaign",
                      "ad_set",
                      "ad"
                    ],
                    "maxLength": 64,
                    "type": "string"
                  },
                  "id": {
                    "maxLength": 128,
                    "type": "string"
                  },
                  "name": {
                    "maxLength": 255,
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "type": "object",
                "required": [
                  "type",
                  "id"
                ]
              },
              "params": {
                "type": "object"
              },
              "rationale": {
                "maxLength": 2000,
                "type": "string"
              },
              "idempotency_key": {
                "maxLength": 255,
                "type": "string"
              }
            },
            "type": "object",
            "required": [
              "type",
              "target_entity",
              "params",
              "rationale"
            ]
          },
          {
            "properties": {
              "type": {
                "enum": [
                  "create_ad"
                ],
                "type": "string"
              },
              "target_entity": {
                "additionalProperties": false,
                "properties": {
                  "type": {
                    "enum": [
                      "ad_account",
                      "campaign",
                      "ad_set",
                      "ad"
                    ],
                    "maxLength": 64,
                    "type": "string"
                  },
                  "id": {
                    "maxLength": 128,
                    "type": "string"
                  },
                  "name": {
                    "maxLength": 255,
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "type": "object",
                "required": [
                  "type",
                  "id"
                ]
              },
              "params": {
                "type": "object"
              },
              "rationale": {
                "maxLength": 2000,
                "type": "string"
              },
              "idempotency_key": {
                "maxLength": 255,
                "type": "string"
              }
            },
            "type": "object",
            "required": [
              "type",
              "target_entity",
              "params",
              "rationale"
            ]
          },
          {
            "properties": {
              "type": {
                "enum": [
                  "upload_asset"
                ],
                "type": "string"
              },
              "target_entity": {
                "additionalProperties": false,
                "properties": {
                  "type": {
                    "enum": [
                      "ad_account",
                      "campaign",
                      "ad_set",
                      "ad"
                    ],
                    "maxLength": 64,
                    "type": "string"
                  },
                  "id": {
                    "maxLength": 128,
                    "type": "string"
                  },
                  "name": {
                    "maxLength": 255,
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "type": "object",
                "required": [
                  "type",
                  "id"
                ]
              },
              "params": {
                "properties": {
                  "staged_asset_id": {
                    "maxLength": 255,
                    "pattern": "^stage_[a-f0-9]{40}$",
                    "type": "string"
                  },
                  "asset_type": {
                    "enum": [
                      "image"
                    ],
                    "type": "string"
                  },
                  "filename": {
                    "maxLength": 255,
                    "type": "string"
                  },
                  "content_sha256": {
                    "pattern": "^[a-f0-9]{64}$",
                    "type": "string"
                  },
                  "mime_type": {
                    "maxLength": 255,
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "size_bytes": {
                    "minimum": 1,
                    "type": [
                      "integer",
                      "null"
                    ]
                  }
                },
                "type": "object",
                "required": [
                  "staged_asset_id",
                  "asset_type",
                  "filename",
                  "content_sha256"
                ]
              },
              "rationale": {
                "maxLength": 2000,
                "type": "string"
              },
              "idempotency_key": {
                "maxLength": 255,
                "type": "string"
              }
            },
            "type": "object",
            "required": [
              "type",
              "target_entity",
              "params",
              "rationale"
            ]
          },
          {
            "properties": {
              "type": {
                "enum": [
                  "adjust_budget"
                ],
                "type": "string"
              },
              "target_entity": {
                "additionalProperties": false,
                "properties": {
                  "type": {
                    "enum": [
                      "ad_account",
                      "campaign",
                      "ad_set",
                      "ad"
                    ],
                    "maxLength": 64,
                    "type": "string"
                  },
                  "id": {
                    "maxLength": 128,
                    "type": "string"
                  },
                  "name": {
                    "maxLength": 255,
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "type": "object",
                "required": [
                  "type",
                  "id"
                ]
              },
              "params": {
                "properties": {
                  "new_daily_budget_minor": {
                    "minimum": 1,
                    "type": "integer"
                  }
                },
                "type": "object",
                "required": [
                  "new_daily_budget_minor"
                ]
              },
              "rationale": {
                "maxLength": 2000,
                "type": "string"
              },
              "idempotency_key": {
                "maxLength": 255,
                "type": "string"
              }
            },
            "type": "object",
            "required": [
              "type",
              "target_entity",
              "params",
              "rationale"
            ]
          },
          {
            "properties": {
              "type": {
                "enum": [
                  "set_status"
                ],
                "type": "string"
              },
              "target_entity": {
                "additionalProperties": false,
                "properties": {
                  "type": {
                    "enum": [
                      "ad_account",
                      "campaign",
                      "ad_set",
                      "ad"
                    ],
                    "maxLength": 64,
                    "type": "string"
                  },
                  "id": {
                    "maxLength": 128,
                    "type": "string"
                  },
                  "name": {
                    "maxLength": 255,
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "type": "object",
                "required": [
                  "type",
                  "id"
                ]
              },
              "params": {
                "properties": {
                  "status": {
                    "enum": [
                      "active",
                      "paused"
                    ],
                    "type": "string"
                  }
                },
                "type": "object",
                "required": [
                  "status"
                ]
              },
              "rationale": {
                "maxLength": 2000,
                "type": "string"
              },
              "idempotency_key": {
                "maxLength": 255,
                "type": "string"
              }
            },
            "type": "object",
            "required": [
              "type",
              "target_entity",
              "params",
              "rationale"
            ]
          },
          {
            "properties": {
              "type": {
                "enum": [
                  "duplicate_ad_with_creative"
                ],
                "type": "string"
              },
              "target_entity": {
                "additionalProperties": false,
                "properties": {
                  "type": {
                    "enum": [
                      "ad_account",
                      "campaign",
                      "ad_set",
                      "ad"
                    ],
                    "maxLength": 64,
                    "type": "string"
                  },
                  "id": {
                    "maxLength": 128,
                    "type": "string"
                  },
                  "name": {
                    "maxLength": 255,
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "type": "object",
                "required": [
                  "type",
                  "id"
                ]
              },
              "params": {
                "properties": {
                  "asset_id": {
                    "maxLength": 255,
                    "pattern": "^(image|video):.+$",
                    "type": "string"
                  },
                  "status": {
                    "enum": [
                      "paused"
                    ],
                    "type": "string"
                  },
                  "name_suffix": {
                    "maxLength": 100,
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "type": "object",
                "required": [
                  "asset_id",
                  "status"
                ]
              },
              "rationale": {
                "maxLength": 2000,
                "type": "string"
              },
              "idempotency_key": {
                "maxLength": 255,
                "type": "string"
              }
            },
            "type": "object",
            "required": [
              "type",
              "target_entity",
              "params",
              "rationale"
            ]
          }
        ]
      },
      "type": "array"
    },
    "rationale": {
      "maxLength": 4000,
      "type": "string"
    },
    "idempotency_key": {
      "maxLength": 64,
      "type": "string"
    },
    "evidence": {
      "minItems": 1,
      "maxItems": 3,
      "items": {
        "additionalProperties": false,
        "properties": {
          "source_tool": {
            "enum": [
              "get_account_state",
              "get_signal_health",
              "get_performance",
              "get-creative-library",
              "staged-asset-manifest"
            ],
            "type": "string"
          },
          "fields_used": {
            "minItems": 1,
            "maxItems": 50,
            "items": {
              "maxLength": 255,
              "type": "string"
            },
            "type": "array"
          },
          "action_index": {
            "minimum": 0,
            "type": "integer"
          }
        },
        "type": "object",
        "required": [
          "source_tool",
          "fields_used"
        ]
      },
      "type": "array"
    },
    "target_source": {
      "enum": [
        "human_supplied"
      ],
      "type": "string"
    },
    "account_id": {
      "minimum": 1,
      "type": "integer"
    },
    "workspace_id": {
      "minimum": 1,
      "type": "integer"
    }
  },
  "required": [
    "actions",
    "rationale",
    "idempotency_key",
    "evidence",
    "target_source"
  ]
}

list_actions

List proposed actions for the authorized workspace and advertising account.

Parameters4

workspace_id	integer	optional	Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces.
account_id	integer	optional	Advertising account ID. Signals reads use the workspace Meta destination when omitted; other tools may require an ID when multiple accounts are active.
status	string	optional
page	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "workspace_id": {
      "description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces.",
      "minimum": 1,
      "type": "integer"
    },
    "account_id": {
      "description": "Advertising account ID. Signals reads use the workspace Meta destination when omitted; other tools may require an ID when multiple accounts are active.",
      "minimum": 1,
      "type": "integer"
    },
    "status": {
      "enum": [
        "pending",
        "approved_without_execution",
        "rejected",
        "executing",
        "executed_pending_verification",
        "compensating",
        "measuring",
        "verified",
        "failed",
        "execution_uncertain",
        "rolled_back",
        "blocked"
      ],
      "type": "string"
    },
    "page": {
      "minimum": 1,
      "type": "integer"
    }
  }
}

get_action_batch

Get a proposed action batch for the authorized workspace and advertising account.

Parameters3

workspace_id	integer	optional	Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces.
account_id	integer	optional	Advertising account ID. Signals reads use the workspace Meta destination when omitted; other tools may require an ID when multiple accounts are active.
batch_id	string	required

Raw schema

{
  "type": "object",
  "properties": {
    "workspace_id": {
      "description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces.",
      "minimum": 1,
      "type": "integer"
    },
    "account_id": {
      "description": "Advertising account ID. Signals reads use the workspace Meta destination when omitted; other tools may require an ID when multiple accounts are active.",
      "minimum": 1,
      "type": "integer"
    },
    "batch_id": {
      "type": "string"
    }
  },
  "required": [
    "batch_id"
  ]
}

get_action

Get one proposed action for the authorized workspace and advertising account.

Parameters3

workspace_id	integer	optional	Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces.
account_id	integer	optional	Advertising account ID. Signals reads use the workspace Meta destination when omitted; other tools may require an ID when multiple accounts are active.
action_id	string	required

Raw schema

{
  "type": "object",
  "properties": {
    "workspace_id": {
      "description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces.",
      "minimum": 1,
      "type": "integer"
    },
    "account_id": {
      "description": "Advertising account ID. Signals reads use the workspace Meta destination when omitted; other tools may require an ID when multiple accounts are active.",
      "minimum": 1,
      "type": "integer"
    },
    "action_id": {
      "type": "string"
    }
  },
  "required": [
    "action_id"
  ]
}

get_action_decision_receipt

Get the persisted decision receipt for an authorized proposed action.

Parameters3

workspace_id	integer	optional	Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces.
account_id	integer	optional	Advertising account ID. Signals reads use the workspace Meta destination when omitted; other tools may require an ID when multiple accounts are active.
action_id	string	required

Raw schema

{
  "type": "object",
  "properties": {
    "workspace_id": {
      "description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces.",
      "minimum": 1,
      "type": "integer"
    },
    "account_id": {
      "description": "Advertising account ID. Signals reads use the workspace Meta destination when omitted; other tools may require an ID when multiple accounts are active.",
      "minimum": 1,
      "type": "integer"
    },
    "action_id": {
      "type": "string"
    }
  },
  "required": [
    "action_id"
  ]
}

get_action_policy

Get the effective Actions policy for the authorized workspace without creating a policy row.

Parameters2

workspace_id	integer	optional	Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces.
account_id	integer	optional	Advertising account ID. Signals reads use the workspace Meta destination when omitted; other tools may require an ID when multiple accounts are active.

Raw schema

{
  "type": "object",
  "properties": {
    "workspace_id": {
      "description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces.",
      "minimum": 1,
      "type": "integer"
    },
    "account_id": {
      "description": "Advertising account ID. Signals reads use the workspace Meta destination when omitted; other tools may require an ID when multiple accounts are active.",
      "minimum": 1,
      "type": "integer"
    }
  }
}

actions.rules.list

List stored performance rules available to this workspace key. This does not evaluate them.

Parameters3

workspace_id	integer	optional	Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces.
page	integer	optional
per_page	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "workspace_id": {
      "description": "Workspace ID returned by list_workspaces. Required when this credential reaches multiple workspaces.",
      "minimum": 1,
      "type": "integer"
    },
    "page": {
      "minimum": 1,
      "type": "integer"
    },
    "per_page": {
      "minimum": 1,
      "maximum": 100,
      "type": "integer"
    }
  }
}

README.md14 KBView on GitHub

Plainrouter: Meta Ads MCP server, SDKs and CLI

Plainrouter is a hosted Meta Ads MCP server and API for developers and AI agents. Connect Claude, ChatGPT, Codex, Cursor, Gemini CLI or another MCP client to read a Meta ad account and its conversion-signal health. The agent can then propose pauses, resumes, budget changes and creative tests. Workspace policy checks every proposal. In Ask mode a person approves each change; in Full mode policy-allowed changes run automatically. New ad copies are created paused.

Plainrouter also keeps its own count of website arrivals and verified revenue beside Meta's reported numbers, so an agent can check Meta's claims against independent evidence.

This repository holds Plainrouter's public SDKs (TypeScript, Python, Ruby and PHP; Go lives in plainrouter/sdk-go), the CLI, MCP metadata and official Agent Skills.

At a glance


MCP endpoint	`https://plainrouter.com/mcp` (Streamable HTTP)
Sandbox	`https://plainrouter.com/mcp/sandbox`: no account or credential, synthetic data, never contacts Meta
Authentication	A Workspace key sent as a bearer token, or Plainrouter OAuth sign-in where the client supports it
Access tiers	Read for account, signal, inventory and creative reads; Write adds previews and proposals
Approvals	Ask: a person approves each change. Full: policy-allowed changes run automatically. Rule violations are blocked, the kill switch stops further writes, and every change gets a decision receipt
Clients	Claude Code, Claude, ChatGPT (developer mode), Codex, Cursor, Gemini CLI, Grok, Meta Muse, Hermes, OpenClaw, n8n and Make (setup guides)
Pricing	MCP is included on every plan and calls are not metered. Free below €300 of monthly ad spend (pricing)
Registry	`com.plainrouter/mcp` in the official MCP Registry
Docs	MCP overview · Meta Ads MCP server

Quick start

1. Try the sandbox, no account needed

Claude Code:

claude mcp add --transport http plainrouter-test https://plainrouter.com/mcp/sandbox

Codex (~/.codex/config.toml):

toml

[mcp_servers.plainrouter-test]
url = "https://plainrouter.com/mcp/sandbox"

Ask the agent to call get_account_state, then get_signal_health. Every response is synthetic and marked "sandbox": true.

2. Connect your Meta ad account

Create a Workspace key in Settings → Workspace keys (start with Read), keep it in an environment variable, and point your client at https://plainrouter.com/mcp.

Claude Code (.mcp.json):

json

{
  "mcpServers": {
    "plainrouter": {
      "type": "http",
      "url": "https://plainrouter.com/mcp",
      "headers": { "Authorization": "Bearer ${PLAINROUTER_WORKSPACE_TOKEN}" }
    }
  }
}

Codex (~/.codex/config.toml):

toml

[mcp_servers.plainrouter]
url = "https://plainrouter.com/mcp"
bearer_token_env_var = "PLAINROUTER_WORKSPACE_TOKEN"

ChatGPT (developer mode), Claude custom connectors and Cursor can sign in with OAuth instead. Add https://plainrouter.com/mcp, then choose the Meta ad account and Read or Write access on Plainrouter's consent screen. Never put a credential in the endpoint URL or in a prompt.

Call get_account_state first and confirm the workspace and Meta ad account before any other work. Other clients: setup guides.

FAQ

What is a Meta Ads MCP server?

A Model Context Protocol server that exposes a Meta ad account as tools an AI client can call. Plainrouter's is hosted, so there is nothing to install or keep a Meta token for. It adds conversion-signal diagnostics, one-workspace keys and an approval step for supported changes.

Can an AI agent analyze my Meta ads without changing anything?

Yes. A Read key covers account, Signals, inventory and creative-library reads and cannot preview or propose changes. It can still submit feedback and run the optional ingestion diagnostic, which writes one identity-free test event.

How is this different from Meta's own Ads MCP server?

Meta hosts a first-party server at https://mcp.facebook.com/ads for its own advertising operations, and it is the first option to evaluate for direct access. Plainrouter adds an independent conversion count and delivery diagnostics, Ask/Full approvals with policy checks and receipts, and keys scoped to one workspace. See the Meta Ads MCP comparison.

Does it work with ChatGPT?

Yes, in ChatGPT developer mode on paid plans. Add https://plainrouter.com/mcp with OAuth and choose the ad account on Plainrouter's consent screen. The sandbox works there with No Authentication.

What does it cost?

MCP is included on every Plainrouter plan, and MCP calls are not metered. Plainrouter is free below €300 of observed monthly ad spend.

Agent Skills

For agents, the repository also includes:

repository guidance for Claude Code, Codex, Cursor, and Windsurf;
Agent Plugin manifests for Claude Code and Codex;
a Streamable HTTP MCP configuration for https://plainrouter.com/mcp; and
three official Agent Skills:
- get-ad-account-context for approved account context and read-only measurements;
- verify-signal-ingestion for an idempotent identity-free onboarding check; and
- propose-governed-ad-actions for evidence-backed proposals governed by Ask or Full.

Install the skills with the open Agent Skills CLI:

npx skills add plainrouter/sdk

Tools

The live server advertises 32 tools. Your key tier, grants and the selected ad account decide which ones a connection can use. The full contracts are in the MCP tool reference.

Tool	Kind	What it does
Account and reporting
`get_account_state`	Read	Return the authorized advertising account, workspace, connection, Signal destination, and currently available account capabilities.
`get_account_inventory`	Read	Read the authorized workspace account inventory from the Meta mirror, with optional level, status, parent, and ID cursor filters.
`get_inventory_metrics`	Read	Read daily Meta metrics beside counted Plainrouter arrivals for mirrored campaigns, ad sets and ads.
`get_performance`	Read	Compare Meta-reported conversions with the conversions Plainrouter accepted and verified for the selected account.
`get_arrivals_comparison`	Read	Return counted arrivals beside Meta outbound clicks for the authorized workspace and selected trailing window.
`get-creative-library`	Read	Return Meta image and video assets with the ads and last-30-day performance historically associated with each asset.
Conversion signals
`get_signal_health`	Read	Diagnostic view of first-party event flow, Meta delivery outcomes, match quality, and reconciliation gaps from Plainrouter stored measurements.
`get_install_instructions`	Read	Return managed-hostname Path A installation material and first-arrival state for the authorized workspace.
`verify_signal_ingestion`	Write	Verify server-side Signal ingestion by writing one idempotent, identity-free modeled event for the authorized workspace.
Actions (governed changes)
`dry_run_actions`	Read	Preview policy decisions and execution diffs for a proposed Action batch without writing it.
`propose-actions`	Write	Propose a batch of budget, status, upload, or creative-duplication actions for the approved ad account.
`upload-asset`	Write	Stage a JPEG/PNG image and submit a canonical upload action through workspace policy.
`duplicate-ad-with-creative`	Write	Submit a canonical proposal to duplicate a source Meta ad with a different creative asset.
`list_actions`	Read	List proposed actions for the authorized workspace and advertising account.
`get_action_batch`	Read	Get a proposed action batch for the authorized workspace and advertising account.
`get_action`	Read	Get one proposed action for the authorized workspace and advertising account.
`get_action_decision_receipt`	Read	Get the persisted decision receipt for an authorized proposed action.
`get_action_policy`	Read	Get the effective Actions policy for the authorized workspace without creating a policy row.
Launch
`launch.creatives.index`	Read	List creatives in the workspace bound to the authenticated execution token.
`launch.creatives.show`	Read	Show one creative in the workspace bound to the authenticated execution token.
`launch.creatives.store`	Write	Store one JPEG, PNG, MP4, or QuickTime creative from strict base64 content in the token-bound workspace.
`launch.creatives.store-from-url`	Write	Fetch and store one creative from a vetted HTTPS URL in the token-bound workspace.
`launch.creatives.status`	Write	Set the status of one creative in the workspace bound to the authenticated execution token.
`launch.plans.list`	Read	List deployment plans for the approved ad account, including each current review_version to pass when executing the reviewed plan.
`launch.plans.show`	Read	Read one deployment plan and its current review_version and latest launch-intent status in the workspace and ad account bound to the execution token.
`launch.plans.create`	Write	Create a deployment plan for the approved ad account.
`launch.plans.update`	Write	Update a deployment plan for the approved ad account.
`launch.plans.validate`	Write	Validate a deployment plan for the approved ad account.
`launch.plans.copy`	Write	Copy a failed plan to a new draft with the same content.
`launch.plans.execute`	Write	Execute one deployment plan in the workspace and ad account bound to the execution token; requires the review_version returned by the plan read you acted on.
Workspace
`revoke_grant`	Write	Revoke an active workspace grant.
`submit_feedback`	Write	Report a bug or a missing capability you hit while using this server.

Every change to Meta goes through Actions: policy checks, the workspace's Ask or Full mode, provider verification and a decision receipt.

TypeScript SDK

Install the generated SDK:

npm install @plainrouter/sdk

Inject a Signal Tracker secret explicitly, then call a generated operation:

import { configurePlainrouter, listEvents } from "@plainrouter/sdk";

configurePlainrouter({
  signalTrackerSecret: process.env.PLAINROUTER_TOKEN!,
});

const response = await listEvents();

The default API base URL is https://plainrouter.com/api/v1. The SDK never embeds credentials.

Action policy compatibility

The next npm and Python version is 0.7.0; the next Ruby version is 0.3.0. These breaking 0.x updates remove retired workspace policy settings from the generated clients. Policy reads expose execution mode and outcome-check settings. Update integrations to consume the current signed policy response.

In Ask mode, a person approves every change first. In Full mode, the workspace lets changes run automatically without a per-change approval. Every change gets a receipt, and the kill switch stops all changes. It does not undo earlier changes.

Python SDK

Install the Python SDK:

python -m pip install plainrouter

python

from plainrouter import create_client, list_events

client = create_client("your-signal-tracker-secret")
response = list_events.sync(client=client)

Python 3.11 or newer is required. Python package releases are versioned independently from the API contract and are verified against the vendored, signed OpenAPI contract before publication.

Ruby SDK

Install the Ruby gem:

gem install plainrouter-sdk

Use the compact client facade for the three API areas:

ruby

require "plainrouter"

client = PlainRouter::Client.new(
  token: ENV.fetch("PLAINROUTER_TOKEN")
)

events = client.operations.list_events(per_page: 25)

Ruby 3.2 or newer is required. The complete generated models and HTTP-aware methods remain available under PlainRouter::OpenAPI without crowding the top-level SDK documentation.

PHP SDK

Install the PHP package:

composer require plainrouter/sdk

Use the compact client facade for the three API areas:

php

use Plainrouter\Client;

$client = new Client(token: getenv('PLAINROUTER_TOKEN'));

$events = $client->operations->listEvents(25);

PHP 8.2 or newer is required. The complete generated models and HTTP-aware methods remain available under Plainrouter\OpenAPI.

Go SDK

The generated Go client is published as its own standard Go module:

go get github.com/plainrouter/sdk-go@v0.5.0

CLI

Install the canonical scoped CLI globally:

npm i -g @plainrouter/cli
plainrouter --help

Or run the scoped package without installing it globally:

npx @plainrouter/cli --help

Python users can install the equivalent CLI from PyPI with pipx:

pipx install plainrouter
plainrouter --help

Both distributions expose the plainrouter command. Keep only one global installation on your PATH to avoid selecting an unintended executable.

Provide a Signal Tracker secret without placing it in shell history:

read -s PLAINROUTER_TOKEN
export PLAINROUTER_TOKEN
plainrouter events list
unset PLAINROUTER_TOKEN

The same CLI is also available from the official Homebrew tap:

brew install plainrouter/tap/plainrouter

Developer resources

Official developer resources: documentation, API documentation, and OpenAPI specification.

Official project: plainrouter.com · documentation · source

This repository is in 0.x development. Stability and support are not yet promised.

Install

Tools (15)

get_account_stateget_account_inventorylist_workspacesget_signal_healthget_performanceget_inventory_metricsverify_signal_ingestionpropose-actions

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://plainrouter.com/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://plainrouter.com/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.

com.plainrouter/mcp (MCP) Server

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

Topics

get_account_state

get_account_inventory

list_workspaces

get_signal_health

get_performance

get_inventory_metrics

verify_signal_ingestion

propose-actions

dry_run_actions

list_actions

get_action_batch

get_action

get_action_decision_receipt

get_action_policy

actions.rules.list

Plainrouter: Meta Ads MCP server, SDKs and CLI

At a glance

Quick start

1. Try the sandbox, no account needed

2. Connect your Meta ad account

FAQ

What is a Meta Ads MCP server?

Can an AI agent analyze my Meta ads without changing anything?

How is this different from Meta's own Ads MCP server?

Does it work with ChatGPT?

What does it cost?

Agent Skills

Tools

TypeScript SDK

Action policy compatibility

Python SDK

Ruby SDK

PHP SDK

Go SDK

CLI

Developer resources

Install

Remote endpoint

Related servers