# Refiner — how to use (mcp.ai)

Connect your Refiner account and use 10 tools for forms and surveys straight from your AI agent. Connect with your own API key. Refiner is a customer feedback and survey tool designed to help businesses collect and analyze user insights.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_refiner?ms=1787291520000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `refiner_delete_contact`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/refiner`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/refiner/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/refiner/delete/contact` — Tool to delete a specific contact by its identifier. Provide either the user ID or email address to identify and delete the contact.
  - body: { id?: string, email?: string }
- `POST https://api.mcp.ai/api/refiner/get/account/info` — Retrieves Refiner account information including subscription plan, usage limits, and environment statistics. This action provides: - Current subscription plan and usage limits (MTU, MTE, MPV, MSR) - U
- `POST https://api.mcp.ai/api/refiner/get/contact` — Retrieve detailed information about a specific contact using their ID, email, or UUID. Returns all stored attributes, segments, and account information.
  - body: { id?: string, uuid?: string, email?: string }
- `POST https://api.mcp.ai/api/refiner/get/contacts` — Tool to retrieve a list of contacts from your Refiner account. Use when you need to filter or paginate through contacts.
  - body: { page?: integer, search?: string, order_by?: string, form_uuid?: string, page_cursor?: string, page_length?: integer, segment_uuid?: string }
- `POST https://api.mcp.ai/api/refiner/get/forms` — Tool to retrieve a list of forms (surveys) from your Refiner account with optional filtering and pagination. Use when you need to list surveys by state, page, or include extra info/config.
  - body: { list?: string, page?: integer, page_length?: integer, include_info?: boolean, include_config?: boolean }
- `POST https://api.mcp.ai/api/refiner/get/reporting` — Tool to retrieve aggregated reporting data for surveys including metrics and analytics. Use when you need survey analytics over a time range filtered by type, question identifiers, tags, forms, or seg
  - body: { type: string, tag_uuids?: string[], form_uuids?: string[], segment_uuids?: string[], date_range_end?: string, date_range_start?: string, question_identifiers?: string[] }
- `POST https://api.mcp.ai/api/refiner/get/responses` — Tool to retrieve all survey responses from your Refiner account with optional filtering and pagination. Use after confirming survey creation to pull response data.
  - body: { page?: integer, search?: string, include?: string, form_uuid?: string, form_uuids?: string[], page_cursor?: string, page_length?: integer, segment_uuid?: string, segment_uuids?: string[], date_range_end?: string, with_attributes?: boolean, date_range_start?: string }
- `POST https://api.mcp.ai/api/refiner/get/segments` — Tool to retrieve a list of user segments from your Refiner account. Use when you need to view or paginate segments.
  - body: { page?: integer, page_cursor?: string, page_length?: integer }
- `POST https://api.mcp.ai/api/refiner/track/event` — Tool to record a user event by name for a user identified via user ID or email. Use after confirming the identifier and event name.
  - body: { id?: string, email?: string, event: string }
- `POST https://api.mcp.ai/api/refiner/update/contact` — Tool to create or update a contact's attributes or account. Identifies a contact by `id` or `email` and updates their traits or account grouping. If the contact doesn't exist, it will be created autom
  - body: { id?: string, email?: string, account?: object, attributes?: object }

## Example prompts
- "What can I do in Refiner?"
- "Show me a summary of my Refiner account"

## More
- Page: https://mcp.ai/refiner
- Agent spec (llms.txt): https://mcp.ai/refiner/llms.txt
- Postman collection: https://mcp.ai/refiner/postman.json