Retently MCP Server

Overview

The Retently MCP server lets an AI client such as Claude work directly with your Retently account in natural language. Ask for your latest NPS, search and tag feedback, reply to detractors, send a transactional survey, or pull a monthly report, without leaving the chat.

It implements the Model Context Protocol over Streamable HTTP, so any MCP-capable client can connect to it as a remote server. There is nothing to install and nothing to host on your side.

What you need

• A Retently account you can log in to.
• An AI client that supports remote MCP servers, such as Claude, Codex, or ChatGPT, with its connector feature enabled.
• Tools act on your account and respect your Retently role and permissions, so you only ever see and change what your account allows. Some tools also depend on your plan and account type: Products tools need an ecommerce account, Companies tools need B2B Account-CX, and topic analytics tools need Topics.

Setup walkthroughs

Prefer to watch? These short videos walk through connecting the Retently MCP server end to end in two popular clients. Each one links to the full written guide if you would rather follow along in text.

Connect with OAuth (recommended)

With OAuth there is no token to generate. You log in once in the browser and approve the access you want. After that the client keeps itself connected in the background, so you never paste a credential. This is the best option for interactive clients.

Claude Code

Add the server, then trigger the login from the REPL:

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

In the Claude Code REPL, run /mcp. Your browser opens to Retently, you log in and approve the requested access, and Claude Code stores and renews the session for you. claude mcp list then shows retently as connected.

claude.ai (web)

Go to Settings, then Connectors, then Add custom connector. Name it Retently and use the URL https://mcp.retently.com/mcp. The web app runs the login and approval for you. On the web this is the only connection method, since there is no place to paste a token.

Claude Desktop

Add it as a remote connector under Settings, then Connectors, using the same URL. It runs the same browser login. Restart the app fully after adding it.

Connect with a personal access token

A personal access token (PAT) is a long-lived bearer token you generate and paste into a client. Use it for scripts, headless automation, or any client where you want a token you control by hand.

1. Create the token

• Log in to app.retently.com.
• Open Settings, then AI Connections.
• Create a personal access token, choose its scopes (see Scopes and PII), and set an expiry. The default is 90 days and the maximum is 365 days.
• Copy the token right away. It is shown only once. If you lose it, delete it on the same page and create a new one.

The token looks like this:

rtly_mcp_pat_<id>_<secret>

2. Add it to your client

Claude Code:

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

Claude Desktop, by editing the config file and then restarting the app fully:

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

Keep the token out of the file by setting it as an environment variable, for example export RETENTLY_MCP_PAT="rtly_mcp_pat_...". On the claude.ai web app there is no place to paste a token, so use OAuth there.

Scopes and PII

Each connection holds a set of scopes that decide what it can do. Grant the least you need. What you can grant is capped by your Retently role.

Customer personal data, including emails, names, custom properties, location, and reply identity, is gated separately by the pii:read and pii:write scopes. These are admin controlled and off by default. Without pii:read, most read tools still work but omit personal fields, while tools whose whole result is personal data, such as the suppressed email list, are not available. Without pii:write, tools that write personal data, such as send_survey, create_customer, and update_customer, are not allowed. An administrator enables them under Customer PII access on the same AI Connections page.

Reading topic analytics uses reports:read. Calling generate_topic_drivers additionally requires reports:generate, because it can create a paid AI report. The read-only get_topic_analysis tool never starts a generation and omits verbatim citation comments; retrieve the underlying source comments with list_topic_feedback and feedback:read.

Tool catalog

66 tools grouped by area. Read tools never change anything. Write tools change data and follow the safety flow described below. Your AI client discovers the tools and their arguments automatically once connected; which tools appear depends on your plan, permissions, and account type.

Prompts

Prompts are ready-made starting points for common feedback reviews. Claude Code shows them as slash commands. Other clients may not display them, so you can also ask the same questions in your own words.

Write safety

Every write tool runs as a dry run first. It returns a preview of exactly what would change plus a confirmation token, and changes nothing until the client calls it again with that token. Write actions are rate limited per account and recorded in an audit log.

• send_survey sends real surveys to real customers once confirmed. Use a test contact while you are trying it out. Suppressed addresses are dropped automatically.
• reply_feedback sends a real email to the customer. Sending cannot be undone.
• generate_topic_drivers can generate and save an AI report after confirmation, or return an existing report without generating another. Generation needs enough feedback on the topic and is limited to 50 reports per account per day, with a 24-hour cooldown for forced regeneration.

Verify it works

• In Claude Code, /mcp should show retently connected with a tool count above zero.
• Ask the client to call ping. It returns { "pong": true } and proves the connection is reachable, even without a valid credential.
• Ask for your most recent feedback or your NPS score. If nothing matches, the response includes the date range your feedback covers and the tools to try next.

The same check from the command line with a token:

curl -s https://mcp.retently.com/mcp \
  -H "Authorization: Bearer rtly_mcp_pat_<id>_<secret>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json,text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_score","arguments":{}}}'

Troubleshooting

Looking for the REST API instead? See the Retently API reference.