# Refiner MCP

> Refiner connects your customer feedback account to any AI agent. It lets you pull in-product insights and churn signals by running micro-surveys when users hit specific moments—like after a checkout or clicking a feature. You can manage everything from NPS scores and raw feature feedback right inside your chat interface, keeping your user understanding loop closed without leaving the workspace.

## Overview
- **Category:** productivity
- **Price:** Free
- **Tags:** customer-feedback, nps-surveys, user-insights, churn-analysis, micro-surveys, data-collection

## Description

You connect your customer feedback account straight into any AI agent. Refiner lets you pull in-product insights and churn signals by running micro-surveys precisely when users hit a certain spot—think right after they complete checkout or click on some core feature. You manage everything from NPS scores to raw feature comments without ever leaving your chat interface, keeping your whole user understanding loop closed.

**Monitoring Survey Performance & Data Retrieval**

You need to know what's going down with your feedback. Use the agent to get a full rundown of every active survey—whether it's in-app, via email, or linked elsewhere—using `list_refiner_surveys`. This tool gives you the status and total response count for all of them right away. When you need deep data, run `list_refiner_responses` to pull up submitted answers. You can filter these responses by specific date ranges or unique identifiers (UUIDs), so you're spotting trends fast. Before making any big query, you should always check the server’s operational health using `check_refiner_status`. It confirms the API is running smoothly and ready for action.

**Identifying Users & Targeting Feedback**

To make sure your surveys land on the right people, you gotta manage user identity. You can use `identify_refiner_user` to confirm or update specific technical traits for any given user by their email address. This precision is key when you're sending out a micro-survey.

For group insights, you'll want to list and query your defined user segments using `list_refiner_segments`. This shows how your entire audience is distributed across those groups so you know who you're talking to. You can also manage basic product contact details or run simple user identification checks by listing contacts with `list_refiner_contacts` or getting specific details with `get_refiner_contact`.

**Driving Action & Analysis**

The real power is triggering things. Instead of waiting for users to complain, you make the survey show up at the perfect time. You use `track_refiner_event` to programmatically log a specific user action—an event in the system—which immediately triggers the delivery of that perfectly timed micro-survey. This lets your agent act as an automated feedback mechanism.

If you need a list of all available survey definitions, run through `list_refiner_surveys`. When you're ready to query user data, remember that `list_refiner_responses` handles the retrieval, letting you focus on the content. The combination of tracking an event (`track_refiner_event`) and pulling responses (`list_refiner_responses`), after ensuring the right users are targeted (`identify_refiner_user`), makes your whole feedback process airtight.

## Tools

### check_refiner_status
Verifies the API server's current operational health and status.

### get_refiner_contact
Retrieves specific contact details for product-related users or entities.

### identify_refiner_user
Identifies a user by email and allows you to update their technical traits in the system.

### list_refiner_contacts
Lists all product contacts available within the Refiner account.

### list_refiner_responses
Retrieves a list of specific survey submissions, allowing filtering by date or unique identifiers.

### list_refiner_segments
Lists defined user segments and allows querying the distribution of users within those groups.

### list_refiner_surveys
Retrieves a list of all current feedback surveys, detailing their status and total response count.

### track_refiner_event
Logs a specific user action (an event) for later analysis and potential micro-survey triggering.

## Prompt Examples

**Prompt:** 
```
List all my feedback surveys in Refiner.
```

**Response:** 
```
I've retrieved your surveys. You have 3 active surveys: 'NPS - Post Checkout', 'Beta Feedback', and 'New User Onboarding'. Which one would you like to see response counts or details for?
```

**Prompt:** 
```
Show me the last 5 responses for the 'NPS - Post Checkout' survey.
```

**Response:** 
```
I've fetched the latest responses. You have 5 recent submissions with scores ranging from 8 to 10. Users mentioned the 'speed of delivery' as a major positive. Shall I retrieve the full text for those responses?
```

**Prompt:** 
```
Track event 'Clicked Upgrade' for user 'mike@example.com'.
```

**Response:** 
```
Event tracked! I've logged 'Clicked Upgrade' for mike@example.com in Refiner. If you have any micro-surveys targeted to this event, they will be triggered for the user automatically.
```

## Capabilities

### Pull User Feedback Data
The agent pulls survey submissions using `list_refiner_responses`, allowing you to filter by UUIDs or specific date ranges to find trends.

### Trigger Surveys on Events
You can use `track_refiner_event` to programmatically log a user action, which triggers the delivery of a perfectly timed micro-survey.

### Target Specific Users
The agent uses `identify_refiner_user` to confirm or update traits for users, ensuring that targeted surveys reach the right people.

### List and Query User Groups
You can list user segments with `list_refiner_segments` to quickly see how your audience is distributed across defined groups.

### Audit Survey Statuses
Use `list_refiner_surveys` to get a full rundown of all active feedback surveys, including their status and response counts.

### Monitor API Health
The agent checks the server's operational health using `check_refiner_status` before running any major queries or actions.

## Use Cases

### The New Feature Launch Check
A PM wants to know how users feel about a new checkout button. Instead of waiting for the manual survey response, they ask the agent to run `list_refiner_surveys` to confirm the 'Checkout Flow' survey is active. Then, they use `track_refiner_event` every time a user hits that page, ensuring immediate feedback capture and getting real-time sentiment data.

### Debugging User Onboarding
A CS rep gets a complaint about a specific account. They ask the agent to use `identify_refiner_user` with the user's email. The agent confirms the identity and then runs `list_refiner_responses` for that user, pulling up all their past feedback submissions in seconds.

### Identifying High-Value Users
The Growth team needs to know which users saw a specific beta feature. They use the agent to run `list_refiner_segments` and query for 'Beta Testers'. This tells them exactly who is in the target group, allowing them to send a specialized follow-up survey.

### Auditing System Readiness
Before running a massive data pull, an engineer asks the agent to run `check_refiner_status`. The agent confirms the API is healthy. Then, they use `list_refiner_contacts` and `get_refiner_contact` to verify basic account credentials are solid before proceeding with complex analysis.

## Benefits

- Stop manually checking survey dashboards. Use `list_refiner_surveys` and `list_refiner_responses` to pull status, counts, and specific submissions instantly via a simple chat command.
- Never miss a critical user action. By using `track_refiner_event`, you log high-fidelity behavioral data that allows the system to trigger micro-surveys at the perfect moment in the user flow.
- Keep your audience always accurate. The agent uses `identify_refiner_user` and `list_refiner_segments` so you're only targeting feedback efforts toward verified, relevant groups of users.
- Get full operational visibility instantly. If you need to know if the system is running right before a campaign launch, just run `check_refiner_status`. It keeps everything reliable.
- Process data without leaving your workflow. Instead of copy-pasting user IDs or segment lists, simply ask the agent to query them using tools like `list_refiner_segments`.

## How It Works

The bottom line is: Your AI client manages your entire feedback system using natural conversation; you never have to leave the chat window to check survey results or log an event.

1. First, subscribe to this server and enter your Refiner API Key (you find that in your project settings).
2. Next, tell your agent what you need—for example, 'List all active surveys' or 'Track event Clicked Upgrade for mike@example.com'.
3. The agent executes the necessary tool calls (`list_refiner_surveys` or `track_refiner_event`), pulls the structured data back, and gives you a plain English summary of what it found.

## Frequently Asked Questions

**How do I list all my current feedback surveys using list_refiner_surveys?**
You ask the agent to run `list_refiner_surveys`. It will return a list of every active survey—like 'NPS - Post Checkout' or 'Beta Feedback'—and tell you how many responses each one has.

**Can I track an event for a specific user using track_refiner_event?**
Yes. You provide the agent with the event name and the target user ID. The tool logs that action, which means if you have micro-surveys tied to it, they'll automatically trigger.

**What is the difference between list_refiner_contacts and identify_refiner_user?**
`list_refiner_contacts` shows a general listing of product contacts. `identify_refiner_user`, however, requires you to pinpoint one user and allows you to update their specific traits for better targeting.

**How do I find out if the Refiner API is working right now?**
Just ask the agent to run `check_refiner_status`. This tool immediately verifies the server's operational status, letting you know if there are any connectivity issues before you start querying data.

**Can I query responses for a specific date range using list_refiner_responses?**
Yes. You specify the date range and ideally include technical filters like UUIDs in your request. The agent executes `list_refiner_responses` and returns submissions matching those criteria.

**When using `list_refiner_responses`, can I filter submissions by unique identifiers like UUIDs or technical traits?**
Yes, you pass the specific ID criteria to the tool call. This lets your agent pull an exact record rather than just searching within a date range. You can pinpoint single responses instantly.

**If I change a user's status or role, how do I use `identify_refiner_user` to make sure the update sticks?**
The command writes the changes directly to the user profile. This ensures that any subsequent segment checks or micro-surveys targeting those specific traits will see the new data immediately.

**When I run `list_refiner_segments`, am I seeing live data, or are these segments based on historical definitions?**
You are viewing the current segment definition and its associated user count. The tool queries the most up-to-date state of your audience distribution across all recorded events.

**Can I check the responses for a specific survey via AI?**
Yes! Use the `list_refiner_responses` tool and provide the Survey UUID. Your agent will retrieve the latest submissions, which you can then ask the AI to summarize or filter by date.

**How do I identify a user and add custom traits using the agent?**
Use the `identify_refiner_user` action. Provide the User ID or Email and a JSON string of `traits` (e.g., '{"plan":"pro"}'). This helps you target surveys based on specific user metadata.

**Is it possible to track a custom event to trigger a survey via AI?**
Absolutely. Use the `track_refiner_event` tool. Provide the event name and the user's ID/Email. When this event is logged, Refiner will trigger any surveys you have configured for that specific action.