Connect your agent to Plainrouter MCP

Connect Codex or Claude through OAuth, follow the Cursor guide for OAuth or key setup, or configure a Workspace key for another client. A successful production read returns the intended workspace and selected Meta ad account. For installation before connecting Meta, use the workspace-only read below. For supported tasks, client requirements, and approval boundaries, start with the MCP introduction. For a summary of supported clients, account scope and pricing, see the Meta Ads MCP server overview.

Create a workspace key

Choose a Read key for the first authenticated workspace check.

Connect Claude

Connect Codex

Add the remote server and sign in through Plainrouter.

Connect Cursor

Choose OAuth sign-in or a protected Workspace key.

Find your tool in the client setup directory, including Gemini CLI, Grok, Muse, Hermes, OpenClaw, Cursor, n8n and Make.

Choose your MCP endpoint

Endpoint	Use	Credential
`https://plainrouter.com/mcp`	Inspect workspace Signals, read an approved account, and submit governed proposals.	Workspace key or workspace-scoped OAuth execution credential

Plainrouter MCP uses workspace execution tokens issued by a current owner or member. New workspace keys authorize a fixed set of selected workspaces, with role-capped Read or Write access in each. Calls act on one workspace at a time. Use list_workspaces and include workspace_id when multiple workspaces are authorized. Workspace selection. Account-scoped tools select an eligible account inside that workspace; older account-bound keys keep their original restriction. If you are choosing between a Signals workspace secret, workspace execution token, or OAuth management credential, see Authentication and clients.

OAuth sign-in from an MCP client, through Plainrouter’s consent screen, is supported and binds the chosen ad account. Only OAuth management credentials are rejected among OAuth credentials.OAuth management credentials cannot authenticate to the MCP server. They may read only GET /api/v1/agent/context for account discovery. Tool calls and other protected methods require a workspace credential: a workspace key or a workspace-scoped OAuth execution token. OAuth management credentials, management keys and Signals secrets are refused.

Before you begin

You need:

A Plainrouter account with access to the intended workspace.
An active Meta ad account connection for account-scoped reads and creative workflows. Workspace installation reads do not require one.
An MCP-compatible client that can send a workspace key to a remote HTTP server or sign in with OAuth. ChatGPT setup uses OAuth.
Current team membership with permission for the key tier you need. Check key permissions.
A clear choice of the advertising account for account-scoped workflows.

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

What happened to test mode?

The unauthenticated sandbox is retired. Old /mcp/sandbox protocol requests return HTTP 410 with error: "sandbox_retired"; validate_sandbox_event is no longer available. A normal HTML browser visit redirects to the product overview instead. Configure /mcp with workspace authorization and verify a read. Migration and SDK compatibility. The production endpoint exposes protocol discovery, catalogs and static ui:// app shells without a credential. Tool calls and account-data reads require workspace authorization. Discovery alone does not verify your credential, workspace or account.

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 public protocol-discovery request. It does not authorize a tool call:

curl https://plainrouter.com/mcp \
  --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 identifies Plainrouter. 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 Claude with OAuth

OAuth sign-in creates a workspace-scoped execution credential without copying a key into your configuration. You still need a Plainrouter account, workspace access and the intended Meta connection for account-scoped reads. Choose Read for analysis; Write is required for previews and proposals.

Claude Code

Add the workspace-authorized server:

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

Open Claude Code in the same directory, run /mcp, select Plainrouter and follow the sign-in prompt. Review the Plainrouter consent screen, callback host, workspace, Meta ad account and requested access before approving. Then confirm a read-only production connection. If a server named plainrouter is already configured at that scope, inspect it in /mcp first. An existing Authorization header selects key authentication; remove that header from the Plainrouter entry before switching to OAuth. Preserve other server entries. See Claude Code’s authentication instructions.

Claude web and Desktop

Open Customize → Connectors, select the plus icon, then Add custom connector. On a managed Claude team, an administrator may need to add the connector first.
Name it Plainrouter and enter https://plainrouter.com/mcp as the remote server URL.
Choose Sign in now for authentication and Register automatically for the OAuth client. Plainrouter does not currently support Use Claude’s published identity.
Add and connect the connector. Sign in to Plainrouter, select the intended workspace and account, and authorize the access tier you need.
Enable Plainrouter for the conversation through Connectors, then use the first read prompt.

Claude’s controls depend on your plan and organization settings. Follow Anthropic’s custom connector instructions if the controls differ.

Connect Codex with OAuth

With Codex CLI installed, add Plainrouter as a remote Streamable HTTP server and start OAuth sign-in:

codex mcp add plainrouter --url https://plainrouter.com/mcp
codex mcp login plainrouter

Follow the Plainrouter sign-in and consent prompts. Confirm the workspace, Meta ad account and requested access; choose Read for analysis or Write for previews and proposals. If adding the server already completed sign-in, a second login is unnecessary. Open Codex and use /mcp to inspect the server, then confirm a read-only production connection. Tool discovery alone does not prove workspace access. If plainrouter already exists, inspect its entry in ~/.codex/config.toml before changing it. When switching from key authentication, remove its explicit bearer-token setting or Authorization header so OAuth can be used. Preserve other server entries and never paste credentials into a prompt. See the official OpenAI MCP instructions.

Connect with a workspace token

Use a Workspace key when your client uses bearer headers or your scripted setup cannot complete interactive OAuth.

Issue the token

In Plainrouter, switch to the intended workspace and open Settings → Workspace keys. Enter a name, choose Read or Write and an expiry, then select Create key.

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 selected account

For Signals context, call get_account_state first; it resolves the workspace’s bound Meta destination when account_id is omitted. Confirm the returned workspace and account. For installation without Meta, use the workspace read below.

See Workspace tokens for tier selection, account selection, replacement, 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 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. If account_id is required,
ask me to select the intended Plainrouter account ID. Do not propose changes.

Check that the returned workspace and Meta ad account match the intended task. Signals reads use the workspace’s bound Meta destination. If you supply account_id, use that bound internal Plainrouter ID, not Meta’s external ID. Actions and creative tools retain their separate eligible-account selection rules. 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. Check connection.health as well as the selected account. It matches the provider status shown in Connections for this workspace; raw connection.status: "active" can still accompany attention_needed. Follow the health status reference. For the returned fields and their meaning, see the MCP tool reference.

Inspect installation before connecting Meta

With a production Read key configured, ask the agent:

Call list_workspaces. If several are available, ask which workspace to use.
Call get_install_instructions with the selected workspace_id. Confirm the workspace,
show its managed-hostname setup status and first-arrival state, then stop.
Do not change DNS or install anything.

The tool returns existing managed-hostname material. A null snippet means setup is not ready; same-origin forwarding is unsupported by this tool. After deploying the generated snippet yourself, repeat the read to check first_arrival. This is separate from the synthetic ingestion diagnostic. For reporting, call get_arrivals_comparison with {"days": 7}. Check its workspace, period, status, and unavailable values before comparing arrivals and clicks. Neither of these tools requires account_id. See the installation and arrivals tool reference.

Use a built-in Signals prompt

On the production connection, open your client’s prompt selector and choose Install the count on my site, Compare claimed clicks with counted arrivals, or Is my count healthy. The prompt reference lists their names, intended tool calls, and limits. Listing prompts needs no credential, but retrieving one requires your workspace key. Loading a prompt returns instructions; it does not run a tool or complete setup. Let the client call the referenced tool with the same workspace authorization and check the actual result. If your client has no prompt selector, use the direct tool examples above.

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 can select only accounts authorized by the workspace key; an account ID cannot widen that scope. 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. Choose Ask to require human approval. In Full, policy-allowed creative changes queue automatically; a prompt asking the agent to stop does not override that mode. A new ad copy is created PAUSED. A later resume requires a separate governed proposal. 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. From Settings → Workspace keys, the issuing member can create a replacement within their current role and Delete the old key to revoke it. The current UI has no token Rotate button. 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. The issuing person must also have a verified email address; an email change pauses protected account and agent access until the new address is verified. Restore verified account access. Also confirm its issuing person still holds a workspace role that covers the token tier. If the client is sending an OAuth management credential, the rejection is expected. Create a workspace key, then configure the MCP client to use it as the bearer credential.

OAuth does not complete or new tools are refused

For Claude web or Desktop, check Register automatically. For Claude Code, check that the server entry has no stale Authorization header when you intend OAuth. Restart sign-in from /mcp if a localhost callback fails; review the displayed callback host rather than changing redirect URLs manually. Plainrouter permits changing the port of a registered HTTP localhost callback, while its other URI components must still match. Custom authorization-code clients must use PKCE with code_challenge_method: "S256"; plain or missing PKCE is refused. Use the public OAuth metadata for the current endpoints and supported methods. Store each replacement refresh token atomically and serialize refreshes for one connection. Replaying a consumed refresh token is refused; later reuse can revoke its token family. If refresh is refused, start a fresh sign-in rather than repeatedly replaying the old token. A new connection still requires the correct workspace approval and scopes. A connector created before a new operation shipped may need a new grant. Disconnect and reconnect, review the requested access, and verify the selected workspace and account again. Successful catalog discovery alone does not prove permission to call a tool.

A creative tool reports a missing permission

Issue a token with the required tier. Use Read for library access and Write for proposal-producing creative tools. Legacy Launcher draft tools and file import are retired.

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

Check account_id and the key’s workspace. Signals reads require the workspace’s bound Meta destination. Actions and creative tools can select an eligible active account owned by that workspace; an older account-bound key rejects a different account. Follow account selection.

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

Clients

Access

Reference

Connect your agent to Plainrouter MCP

Create a workspace key

Connect Claude

Connect Codex

Connect Cursor

Choose your MCP endpoint

Before you begin

What happened to test mode?

Which MCP protocol should my client use?

Connect Claude with OAuth

Claude Code

Claude web and Desktop

Connect Codex with OAuth

Connect with a workspace token

Configure Claude Code for your Meta ad account

Confirm a read-only production connection

Inspect installation before connecting Meta

Use a built-in Signals prompt

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`

OAuth does not complete or new tools are refused

A creative tool reports a missing permission

Plainrouter asks you to reconnect Meta

The wrong account appears

Signals tools show setup required

Create a workspace key

Connect Claude

Connect Codex

Connect Cursor

​Choose your MCP endpoint

​Before you begin

​What happened to test mode?

​Which MCP protocol should my client use?

​Connect Claude with OAuth

​Claude Code

​Claude web and Desktop

​Connect Codex with OAuth

​Connect with a workspace token

​Configure Claude Code for your Meta ad account

​Confirm a read-only production connection

​Inspect installation before connecting Meta

​Use a built-in Signals prompt

​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

​OAuth does not complete or new tools are refused

​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

What happened to test mode?

Which MCP protocol should my client use?

Connect Claude with OAuth

Claude Code

Claude web and Desktop

Connect Codex with OAuth

Connect with a workspace token

Configure Claude Code for your Meta ad account

Confirm a read-only production connection

Inspect installation before connecting Meta

Use a built-in Signals prompt

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`

OAuth does not complete or new tools are refused

A creative tool reports a missing permission

Plainrouter asks you to reconnect Meta

The wrong account appears

Signals tools show setup required