By default, you connect the Retently MCP to your AI agent (Claude Cowork, Claude Code, or OpenAI Codex) through OAuth. OAuth is the recommended path for interactive clients: there is no token to generate and no credential to paste. The connection articles for Claude Cowork, Claude Code, and OpenAI Codex all use it.

This article covers the alternative: a personal access token (PAT). A PAT is a long-lived bearer token you generate in Retently and paste into your client. Use it when OAuth is not an option or when you need tighter control over what a connection can access.

When to Use a PAT Instead of OAuth

Reach for a PAT in any of these cases:

OAuth is not available. Your client, script, or headless automation cannot run the OAuth browser flow.
Your AI agent requires it. The specifics of the agent or MCP client you are using mean a manually supplied token is the only way to connect.
You need more limited access. You want a connection that is scoped down to specific tools or to read-only data, or that has no access to personal identifiable information (PII). A PAT lets you grant exactly the permissions you choose, and nothing more.

Note: the claude.ai web app supports OAuth only. There is no token-paste option there. Use a PAT with clients that accept custom request headers, such as Claude Code, Claude Desktop, Codex, and other MCP clients.

Step 1: Create a Personal Access Token

Open your AI Connections page in Retently.
Choose to create a new access token.
Give the token a name so you can identify it later.
Set how long the token stays active. You can choose anywhere from 30 days up to one year (365 days). When it expires, the connection stops working until you issue a new token.
Choose the permissions for the token (see below).
Create the token, then copy it immediately.

The token is shown only once. After you leave the page, it cannot be viewed again. If you lose it, create a new one.

Permissions and scopes

You set the access level per group of tools. Each group can be granted read-only access or read and write access. Write access lets the connection make changes in your account: updating survey responses, tagging responses, setting topics, creating customers, sending surveys, and so on.

The available scopes include:

Feedback: feedback:read, feedback:tag, feedback:topic, feedback:curate, feedback:reply, feedback:import, feedback:delete
Customers: customers:read, customers:write
Campaigns: campaigns:read, campaigns:write
Reports: reports:read
Surveys: surveys:send
Suppressions: suppressions:read, suppressions:write
Templates: templates:read
Outbox: outbox:read, outbox:write
Integrations: integrations:read
Team: team:read
Personal data: pii:read, pii:write

The PII toggle

Personal data (customer emails, names, custom properties, location, and reply identity) is gated separately by the pii:read and pii:write scopes:

Without pii:read: read tools still work but return de-identified data.
Without pii:write: tools that write personal data are not allowed.

Turning PII off limits a lot of the tools, but the connection can still pull quantitative, aggregate data. This is the setting to use when you want a teammate or a script to work with the numbers without exposing customer identities.

A token's scopes are fixed when you create it. To change what a connection can access, create a new token with the scopes you want and update the client's Authorization header.

Step 2: Connect the MCP with the Token

Connecting with a PAT means adding an Authorization request header to the MCP connection, using your token as a bearer credential.

Server URL: https://mcp.retently.com/mcp
Header: Authorization: Bearer rtly_mcp_pat_<id>_<secret>

Replace rtly_mcp_pat_<id>_<secret> with the token you copied in Step 1.

Claude Code

claude mcp add --transport http \
  retently https://mcp.retently.com/mcp \
  --header "Authorization: Bearer rtly_mcp_pat_<id>_<secret>"

Claude Desktop

Edit claude_desktop_config.json, then fully quit and reopen the app:

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

Store the token in an environment variable rather than hardcoding it in the config:

export RETENTLY_MCP_PAT="rtly_mcp_pat_<id>_<secret>"

Other clients (Codex and any MCP client)

For OpenAI Codex and any other MCP client that supports HTTP transport, add the same server URL and supply the Authorization: Bearer <token> header using that client's mechanism for custom headers. The connection details are identical: the URL https://mcp.retently.com/mcp and the bearer token.

After adding the server, restart your session. A session loads its available MCP tools when it first starts, so the Retently tools are not picked up until you restart.

Security Notes

Treat the token like a password. Anyone who has it can access your Retently data at the scopes you granted.
Prefer storing it in an environment variable or a secret manager over pasting it into a config file in plain text.
Scope tokens to the minimum access the connection needs. If a job only reads reports, grant only reports:read.
Set the shortest expiry that fits your use, and rotate tokens periodically.

Connect the Retently MCP with a Personal Access Token (PAT)