> ## Documentation Index
> Fetch the complete documentation index at: https://plainrouter.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect an AI agent

> Connect an MCP-compatible client with an account-bound workspace execution token.

PlainRouter exposes a remote Model Context Protocol server at:

```text theme={null}
https://plainrouter.com/mcp
```

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 Signal tracker secret, workspace execution token,
or OAuth management credential, see [Authentication and
clients](/docs/auth).

<Warning>
  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.
</Warning>

## Before you begin

You 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`.

## Connect with a workspace token

<Steps>
  <Step title="Issue the token">
    In PlainRouter, switch to the intended workspace and open **Account** → **API**. Choose the exact ad account, a Read, Write, or Admin tier, and an expiry.
  </Step>

  <Step title="Copy it once">
    Copy the complete token immediately after issuance. PlainRouter cannot display it again.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Confirm the bound account">
    Call `get_account_state` first. Confirm the returned workspace and account before continuing.
  </Step>
</Steps>

See [Workspace tokens](/docs/actions/workspace-tokens) for tier selection, rotation, and revocation.

## Permissions

| Permission        | Allows                                                                                    |
| ----------------- | ----------------------------------------------------------------------------------------- |
| `ad-account.read` | Read the approved account and its PlainRouter Signals context.                            |
| `signals.verify`  | Write the identity-free, consent-safe Signal verification event used for 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.

<Warning>
  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.
</Warning>

## Recommended workflows

For Signals analysis:

1. `get_account_state`
2. `verify_signal_ingestion` if Signal activation is still waiting for its server-side check
3. `get_signal_health`
4. `get_performance` when stored reconciliation is relevant
5. `propose-actions` only after the evidence and human-supplied target are clear

For a creative variant:

1. `get_account_state`
2. `get-creative-library`
3. `upload-asset` if the approved account does not already contain the intended image
4. `duplicate-ad-with-creative` using an asset ID returned by a PlainRouter tool
5. Direct the person to the returned `approval_queue_url`

Ask the agent to state clearly whether a proposal is suggest-only, pending approval, blocked, awaiting verification, or Landed.

## Authorization lifetime and revocation

Workspace tokens expire after 30, 90, or 365 days. The owner can rotate or revoke them immediately from **Account** → **API**.

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

### 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](/docs/signals/overview) and call the tools again.