Skip to main content
The Pleyor MCP endpoint accepts two auth modes. Both end up at the same set of tools — the only difference is how the bearer token is obtained.

​
OAuth (chat clients)

When you add Pleyor as a connector in Claude or ChatGPT, the host runs an OAuth flow against the Pleyor web app. You sign in, see a consent screen listing the scopes the connector needs, approve, pick a workspace (if you have multiple), and the host now holds a refresh token. Every MCP call attaches a bearer token derived from it. The flow:
  1. Host fetches /.well-known/oauth-authorization-server from the API
  2. Host dynamically registers itself as an OAuth client (Dynamic Client Registration)
  3. Browser opens to the Pleyor consent screen — you sign in (if needed) and approve scopes
  4. Host receives an authorization code, exchanges it at the token endpoint
  5. Host caches the access + refresh tokens; refreshes silently when access tokens expire
The first consent binds the connector to one of your workspaces. If you belong to multiple, you can rebind later by removing + re-adding the connector.

​
API keys (scripts)

For server-to-server use (cron jobs, internal tooling, custom MCP hosts), generate an API key from your Pleyor dashboard → Settings → API Keys. The key format is pk_live_*. Send it as a Bearer token to the same endpoint: 
curl -X POST <YOUR_MCP_ENDPOINT> \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxx' \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
API keys carry a fixed scope set you choose at creation time. They never expire (revoke + reissue to rotate). Keys are bound to a single organization — pick the right org when generating.

​
Scopes

ScopeAllows
agents:readList agents, read graphs, validate specs, port resolution, model suggestions, cost estimates
agents:writeCreate / replace / update / clone / delete agents, restore versions, manage shares
runs:readList runs, wait for runs, read pleyor://runs/{id}
runs:executeTrigger runs, cancel runs
apps:readList apps, read app metadata
apps:executeTrigger apps, publish apps, submit reviews
assets:writeUpload assets via the connector
openidRequired for OAuth flow (identity)
offline_accessRequired for OAuth refresh tokens
The OAuth consent screen requests the minimum scopes the connector needs to be useful. For API keys, only include the scopes the script actually needs — a read-only monitoring script doesn’t need agents:write or runs:execute.

​
Errors

If a tool needs a scope you don’t have, the call fails with a typed error: 
{
  "code": "SCOPE_MISSING",
  "message": "trigger_run requires 'runs:execute' but the bearer carries: agents:read, runs:read",
  "next_action": "Ask the user to reconnect Pleyor and grant 'runs:execute', or use a Pleyor API key (pk_live_*) whose scope set includes runs:execute."
}
See Errors for the full code list.

​
See also

Quickstart

Add the connector to Claude or ChatGPT.

Errors

Auth errors and how to recover from them.