MCP Server

Introduction

The Refiner MCP Server is an implementation of the Model Context Protocol that enables AI agents to securely interact with your Refiner account.

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.”