Meta Ads MCP: connect your agent with Plainrouter

Connect Claude Code to Plainrouter MCP, verify a synthetic response, then configure a workspace execution token for your own Meta ad account. A successful production setup returns the workspace and account you selected when issuing the token. For supported tasks, client requirements, and approval boundaries, start with the MCP introduction.

Try synthetic data

Check the client connection without a Plainrouter account or token.

Connect your account

Configure your workspace token and confirm the first account read.

Choose your MCP endpoint

Endpoint	Use	Credential
`https://plainrouter.com/mcp/sandbox`	Prove a client against four synthetic tools.	None
`https://plainrouter.com/mcp`	Read one approved account and submit governed proposals.	Workspace execution token for tool calls and account data

Plainrouter MCP uses owner-issued workspace execution tokens. Each token binds the client to one workspace, one Meta ad account, and an explicit access tier. If you are choosing between a Signals workspace secret, workspace execution token, or OAuth management credential, see Authentication and clients.

OAuth management credentials cannot authenticate to the MCP server. They may read only GET /api/v1/agent/context for account discovery. Use a workspace token for every MCP tool call.

Before you begin

For the sandbox, you only need a client with remote HTTP MCP support. For production, you also need:

A Plainrouter account with access to the intended workspace.
An active Meta ad account connection.
An MCP-compatible client that can send a fixed bearer token to a remote HTTP server.
A workspace owner who can issue the token.
A clear choice of the one advertising account the client should use.

For creative-library reads, the Meta connection needs ads_read or ads_management. Governed creative execution needs ads_management.

Start in test mode

In a terminal with Claude Code installed, add the test server:

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

Open Claude Code in the same directory and run /mcp to check the connection. No Plainrouter account or credential is required. Other MCP clients can use the same URL with HTTP transport. The endpoint exposes:

get_account_state
get_signal_health
get_performance
validate_sandbox_event

Every response is synthetic and carries "sandbox": true. Test mode reads no tenant data, persists nothing, and contacts no advertising provider. It exposes no proposal, write, approval, Launcher, or spend-affecting tool. Ask the agent:

Use plainrouter-test to call get_account_state, then get_signal_health.
Summarize the synthetic account and signal health. Do not call other tools.

A successful account response includes the following fields. This is an excerpt from the synthetic response, not a real advertising account:

{
  "sandbox": true,
  "workspace": { "id": 0, "name": "Sandbox Workspace" },
  "ad_account": {
    "id": 0,
    "external_id": "act_SANDBOX",
    "name": "Sandbox Ad Account"
  }
}

Both calls should return without a tool error. This proves the test connection works; it does not verify your production account or event collection. When the client can discover or initialize the server, list tools, and call a sandbox tool, change its server URL to https://plainrouter.com/mcp and configure a workspace execution token. The three read-tool names and their argument shapes match production.

The production endpoint exposes its protocol handshake, tool and resource catalogs, and static ui:// app shells without a credential. Tool calls and account-data reads remain account-bound and return HTTP 401 without a valid workspace execution token.

Which MCP protocol should my client use?

Plainrouter supports 2026-07-28 through server/discover. Existing clients using initialize can negotiate 2025-11-25 or 2025-06-18. Let your MCP client handle the protocol; the Claude Code configuration below does not need manual protocol fields. For a custom HTTP client, start with this credential-free sandbox discovery request:

curl https://plainrouter.com/mcp/sandbox \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, text/event-stream' \
  --header 'MCP-Protocol-Version: 2026-07-28' \
  --header 'Mcp-Method: server/discover' \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "server/discover",
    "params": {
      "_meta": {
        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
        "io.modelcontextprotocol/clientCapabilities": {}
      }
    }
  }'

Check that result.supportedVersions includes 2026-07-28 and result._meta["io.modelcontextprotocol/serverInfo"].name is Plainrouter Sandbox. Discovery confirms protocol compatibility; it does not read your account or verify a tool call. For subsequent 2026-07-28 requests:

Field or header	Requirement
`params._meta`	Include both protocol version and client capabilities on each request.
`MCP-Protocol-Version`	Match the protocol version in `_meta`.
`Mcp-Method`	Match the JSON-RPC `method`, such as `tools/list` or `tools/call`.
`Mcp-Name`	For `tools/call`, match `params.name`. For `resources/read`, match `params.uri`.
`Authorization`	Include the workspace bearer token on every production tool call or account-data read.

Requests are stateless: do not wait for or require an Mcp-Session-Id response header. Legacy clients without protocol metadata in _meta remain on the compatibility path; do not mix the two request formats. Sending either protocol metadata key selects the modern validation path. The published server card lists the current protocol, tools, and resources. The transport upgrade reference explains modern headers and legacy compatibility.

Connect with a workspace token

Issue the token

In Plainrouter, switch to the intended workspace and open API in the dashboard. Choose the exact ad account, a Read, Write, or Admin tier, and an expiry.

Copy it once

Copy the complete token immediately after issuance. Plainrouter cannot display it again.

Add the Plainrouter MCP server

In your MCP client, add https://plainrouter.com/mcp as a remote HTTP server and configure the token as its bearer credential.

Confirm the bound account

Call get_account_state first. Confirm the returned workspace and account before continuing.

See Workspace tokens for tier selection, rotation, and revocation.

Configure Claude Code for your Meta ad account

Add this server entry to your project’s .mcp.json, preserving any existing servers. Claude Code expands environment variables in MCP headers.

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

Supply PLAINROUTER_WORKSPACE_TOKEN in the terminal environment through your local secret manager before starting Claude Code. Keep the variable reference in the file; do not replace it with the token or paste the token into an agent prompt. Open /mcp and allow the project connection when prompted. Start with a Read token for account and library inspection. Use Write or Admin only when you need proposal-producing tools.

Confirm a read-only production connection

Ask the agent:

Use plainrouter to call get_account_state. Show the workspace name and
Meta ad account name and external ID, then stop. Do not propose changes.

Check that the returned workspace and Meta ad account match the ones you selected when issuing the token. If they do, ask for get_signal_health to inspect conversion delivery and matching diagnostics. Missing Signals setup or measurement history is a separate setup issue; a successful account read does not establish healthy tracking. For the returned fields and their meaning, see the MCP tool reference.

Permissions

Permission	Allows
`ad-account.read`	Read the approved account and its Plainrouter Signals context.
`signals.verify`	Write an identity-free, consent-safe Signal ingestion diagnostic. It does not complete onboarding.
`actions.propose`	Submit actions through workspace policy and the approval pipeline.
`creative.read`	Read the approved Meta account’s creative library.
`creative.write`	Stage creative assets and propose creative changes. It does not bypass `actions.propose`.

The agent cannot supply another account ID to widen access. Creative tools recheck that provider objects belong to the approved account.

Creative write permission is not direct mutation authority. upload-asset and duplicate-ad-with-creative return a governed proposal. A later policy decision or human approval determines whether execution is queued.

Recommended workflows

Once the account read succeeds, choose a task:

Diagnose Signals with a stored read. Use ingestion verification only when you explicitly want a diagnostic write; it does not verify a real arrival.
Inspect stored reconciliation and its evidence limits.
Create a paused creative variant: read the account library, select the source ad and asset, submit a proposal, and review the approval link.

Ask the agent to distinguish suggest-only, pending approval, blocked, awaiting verification, and Landed. The Actions overview lists supported changes.

Example: request a creative proposal

After you select a source ad and an asset from the approved account’s creative library, ask:

Use the source ad and asset I selected to propose a paused ad copy.
Summarize the proposed change and show its approval link. Stop for my review.

The creative tool submits a proposal to Plainrouter; it does not change Meta during that MCP call. In Suggest only, approval records agreement without execution. In an executable mode, supported creative work still requires policy checks and human approval. A new ad copy remains PAUSED. Follow the creative workflow and proposal review guide for the next steps. Use the Actions overview to check supported changes before requesting a different operation.

Authorization lifetime and revocation

Workspace tokens expire after 30, 90, or 365 days. The owner can rotate or revoke them immediately from API in the dashboard. Plainrouter also caps a token by the issuing person’s current workspace role on every request. If that person’s role no longer covers the token tier, the token stops authenticating at that tier. Issue a new token instead of trying to reuse a credential whose authority changed.

Troubleshoot

A custom client gets HTTP `400` or a protocol error

For JSON-RPC error -32020, compare MCP-Protocol-Version, Mcp-Method, and, where required, Mcp-Name with the request body. A missing required header or mismatched value fails before the tool runs. Ensure your reverse proxy preserves these headers. For -32022, check the protocol version against discovery and use a supported version. Follow the complete modern request format; changing only the version header is not enough. An authentication 401 is a separate credential failure.

The client waits for a session ID

Plainrouter processes requests independently and does not return Mcp-Session-Id. Update a client or custom transport that requires that header. Keep sending the workspace bearer credential on each production tool request; a successful discovery response does not authorize later calls.

Claude Code cannot load the token variable

Confirm PLAINROUTER_WORKSPACE_TOKEN is set in the environment that starts Claude Code. Restart the client after supplying it. Keep the variable name consistent with .mcp.json; do not print the token to debug the connection.

The client receives `401 Unauthorized`

Confirm the client sends the complete workspace token as a bearer credential and that it has not expired or been revoked. Also confirm its issuing person still holds a workspace role that covers the token tier. If the client is sending an OAuth access token, the rejection is expected. Replace it with a workspace execution token.

A creative tool reports a missing permission

Issue a token with the required tier. Use Read for library access and Write or Admin for proposal-producing creative tools and Launcher draft batches.

Plainrouter asks you to reconnect Meta

The selected account may lack an active Meta connection or the required ads_read or ads_management access. Reconnect Meta, confirm the same ad account, and retry the same idempotent request.

The wrong account appears

Revoke the token and issue another one for the correct advertising account. Tool calls do not accept an account override.

Signals tools show setup required

The account may be authorized correctly while its workspace has no active Signal or destination. Complete Signals setup and call the tools again.

Overview

Access

Reference

Meta Ads MCP: connect your agent with Plainrouter

Try synthetic data

Connect your account

Choose your MCP endpoint

Before you begin

Start in test mode

Which MCP protocol should my client use?

Connect with a workspace token

Configure Claude Code for your Meta ad account

Confirm a read-only production connection

Permissions

Recommended workflows

Example: request a creative proposal

Authorization lifetime and revocation

Troubleshoot

A custom client gets HTTP `400` or a protocol error

The client waits for a session ID

Claude Code cannot load the token variable

The client receives `401 Unauthorized`

A creative tool reports a missing permission

Plainrouter asks you to reconnect Meta

The wrong account appears

Signals tools show setup required

Try synthetic data

Connect your account

​Choose your MCP endpoint

​Before you begin

​Start in test mode

​Which MCP protocol should my client use?

​Connect with a workspace token

​Configure Claude Code for your Meta ad account

​Confirm a read-only production connection

​Permissions

​Recommended workflows

​Example: request a creative proposal

​Authorization lifetime and revocation

​Troubleshoot

​A custom client gets HTTP 400 or a protocol error

​The client waits for a session ID

​Claude Code cannot load the token variable

​The client receives 401 Unauthorized

​A creative tool reports a missing permission

​Plainrouter asks you to reconnect Meta

​The wrong account appears

​Signals tools show setup required

Choose your MCP endpoint

Before you begin

Start in test mode

Which MCP protocol should my client use?

Connect with a workspace token

Configure Claude Code for your Meta ad account

Confirm a read-only production connection

Permissions

Recommended workflows

Example: request a creative proposal

Authorization lifetime and revocation

Troubleshoot

A custom client gets HTTP `400` or a protocol error

The client waits for a session ID

Claude Code cannot load the token variable

The client receives `401 Unauthorized`

A creative tool reports a missing permission

Plainrouter asks you to reconnect Meta

The wrong account appears

Signals tools show setup required