It acts as a bridge between LLM-powered agents and customer feedback data, allowing automation of analytics, user management, and survey workflows through natural language.

At a high level, this server exposes Refiner survey response data as structured tools that AI agents can discover and invoke dynamically.

How to use our MCP server

With the Refiner MCP Server, you can connect your Refiner workspace directly to AI tools like ChatGPT and Claude to analyze survey responses on demand using natural language. This enables ad-hoc exploration of feedback data, from summarizing open-text responses to identifying trends and anomalies in real time.

Beyond analysis, you can power workflow automations – such as triggering actions based on new responses or syncing insights across systems – using tools like Claude Code. The result is a more dynamic, AI-driven feedback loop where insights can be generated and acted upon instantly without manual intervention.

MCP server endpoint

The Refiner MCP server is reachable under the following URL:

https://app.refiner.io/v001/mcp

Authentication

Refiner MCP uses OAuth 2.0 Authorization Code + PKCE.

Discovery endpoints

https://app.refiner.io/.well-known/oauth-authorization-server
https://app.refiner.io/.well-known/oauth-protected-resource
https://app.refiner.io/.well-known/oauth-protected-resource/v001/mcp

Scopes

mcp:projects-read – list accessible environments/projects
mcp:forms-read – read surveys/forms
mcp:responses-read – read individual responses
mcp:reporting-read – read aggregated reporting data

Tools

All tools are read-only and registered in RefinerServer.

get-aggregated-response-data

Get aggregated reporting and chart data. Requires project_uuid from get-projects. Filter by form UUIDs (surveys), segment UUIDs, tag UUIDs, question identifiers and date range. Chart types: nps, csat, ratings, count, distribution. The date range defaults to the past 30 days and can extend back up to 12 months.

Scope: mcp:reporting-read
Input: project_uuid, required type, optional form_uuids, segment_uuids, tag_uuids, question_identifiers, date_range_start, date_range_end
type: nps, csat, ratings, count, distribution
Read-only
Not destructive

get-forms

List surveys in a project. Requires project_uuid from get-projects. Available lists: all, all_with_archived, archived, published, drafts.

Scope: mcp:forms-read
Input: project_uuid, optional page, list
list: all, all_with_archived, archived, published, drafts
Read-only
Not destructive

get-projects

List surveys in a project. Requires project_uuid from get-projects. Available lists: all, all_with_archived, archived, published, drafts.

Lists available projects.

Scope: mcp:projects-read
Input: none
Output: items[] with uuid, name
Read-only
Not destructive

get-responses

Get access to a list of survey responses. Requires project_uuid from get-projects. Filter by form UUIDs (surveys), segment UUIDs, tag UUIDs, and date range. Returns up to 500 responses per page. Contact data is excluded for privacy reasons. The date range defaults to the past 30 days and can extend back up to 12 months.

Scope: mcp:responses-read
Input: project_uuid, optional form_uuids, segment_uuids, tag_uuids, date_range_start, date_range_end, page, page_cursor
Notes:
filters can be comma-separated UUID strings
defaults to last 30 days
max lookback 12 months
up to 500 responses/page
contact data excluded for privacy
Read-only
Not destructive

get-segments

List user segments in a project. Requires project_uuid from get-projects.

Scope: mcp:projects-read
Input: project_uuid
Read-only
Not destructive

get-traits

List response tags in a project. Requires project_uuid from get-projects.

Scope: mcp:projects-read
Input: project_uuid, optional include
include: all, form, contact
Read-only
Not destructive

get-tags

List attributes in a project. Requires project_uuid from get-projects. include options: all, form, contact.

Scope: mcp:projects-read
Input: project_uuid
Read-only
Not destructive

Resources

Resources provide URI-based reads for MCP clients that support resources.

Available Resources:

refiner://projects
refiner://project/{project_uuid}/forms
refiner://project/{project_uuid}/form/{form_uuid}
refiner://project/{project_uuid}/segments
refiner://project/{project_uuid}/tags

Behavior:

MIME type: application/json
Same scope and project-access checks as corresponding tools
Consistent structured responses and explicit access errors

Sample prompts

Refiner exposes built-in MCP prompts to guide robust multi-step analysis workflows.

Built-in prompts

nps_get_score_and_counts
csat_get_score_and_counts
multiple_choice_response_distribution
retrieve_survey_responses
nps_analyze_verbatim
csat_analyze_verbatim
analyze_open_ended_text_responses

Example user prompts

“List my available Refiner environments and surveys.”
“Show NPS score and detractor/passive/promoter counts for the last 30 days.”
“Analyse recent NPS open-text verbatim and tell me which are the biggest drivers for the current score. Tell me what we do right and what we can improve based on the open-text verbatim.”
“What is our current CSAT score in the X project in Refiner?”
“Show CSAT score and distribution for survey X in Q1.”
“Retrieve responses tagged churn-risk from the past 14 days.”
“Analyze open-ended feedback and suggest top improvement actions.”
“Show multiple-choice response distribution for question onboarding_experience.”

The best way to contact us and get help is to fill out our support form. You can also send an email to contact@refiner.io. We usually reply within a few hours.

Introduction