> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gleap.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Surveys with AI agents (MCP)

> The Gleap MCP server's survey tools: build, validate and launch surveys, read results and insights, and reach out to respondents.

The Gleap MCP server lets AI agents such as Claude, ChatGPT, Cursor or Kai work with your surveys: build a survey from a one-line request, check its logic, launch it once you give the go-ahead, read results and AI insights, and draft follow-ups to respondents.

## Connect

Add the Gleap MCP server as a custom connector in your AI client and sign in with Gleap (OAuth):

| Data region | MCP server URL |
| - | - |
| EU (default) | `https://mcp.gleap.io/mcp` |
| US | `https://mcp.us.gleap.ai/mcp` |

Clients that can't do OAuth send the headers `x-gleap-api-key` and `x-gleap-project-id` instead. The agent acts with your role in the project.

## Tools

| Tool | What it does | Access |
| - | - | - |
| `list_surveys` | Surveys with id, SDK id, status, format, published version and unpublished changes. `get_surveys` is an alias. | Read |
| `get_survey` | The draft (or published) definition — questions, logic, endings, hidden fields — plus page settings and targeting. | Read |
| `create_survey` | New survey from a definition, optionally with an in-app event trigger and audience. Always a draft. | Draft only |
| `update_survey` | Replace the draft definition. On a live survey it saves the next draft; respondents keep seeing the published version. | Draft only |
| `validate_survey` | Check a definition or the stored draft: loops, unreachable questions, dead ends, conditions that don't fit the question type. Saves nothing. | Read |
| `publish_survey` | Launch: publish the draft as the next version. With `goLive: true` it also shows the survey in your app to its audience. The agent calls it once you agreed. | Write |
| `pause_survey` | Take a live survey off. | Write |
| `get_survey_results` | Totals, start and completion rates, NPS, per-question counts and drop-off, endings, channels and common paths — from stored counters — plus the question funnel when analytics events exist. | Read |
| `get_survey_analytics` | [Analytics](/documentation/surveys/analytics) with the previous period for comparison: views, starts, submissions, rates, the question funnel with drop-off, timing, score, versions, device and channel breakdowns, busiest times, reminders, email and quality counts. Filters: date range, version, channel, device. | Read |
| `get_survey_insights` | AI themes with sentiment, summary, drivers, segments and spike alerts. Returns the stored insights at once; after new responses, reading them starts one update in the background (`updating: true`, read again in a minute). | Read |
| `ask_survey_results` | A plain-language question → an answer with cited response ids. Uses AI (token usage). | Read |
| `get_survey_responses` | Compact response rows. Filters: status, answer by key (`{ "nps_score": "0..6" }`), theme, channel, contact, text. Cursor pagination. | Read |
| `get_survey_response` | One response with labelled answers, the path taken, ending and contact. | Read |
| `reach_out_to_respondent` | Start a messenger or email conversation linked to a response. Returns a draft by default; sends only with `send: true`. | Needs approval |
| `get_survey_summary` | Stored AI summary of a survey's responses (legacy). | Read |

## How agents build a survey

1. `create_survey` with a [definition](/documentation/surveys/definition). The tool rejects common mistakes before saving — unknown properties, duplicate ids or keys, jumps to unknown or earlier questions, conditions on choice labels instead of choice ids, NPS ranges outside 0–10 — and returns Gleap's validation of the saved draft.
2. The agent fixes problems with `update_survey` (always the complete definition) or `validate_survey`.
3. The agent shows you what the survey asks and who will see it (or you open the `reviewUrl` in the editor).
4. Once you say "launch it", the agent calls `publish_survey` with `goLive: true`.

Example request to an agent:

> Create a churn survey for customers who cancel. Ask why, and if it's pricing, ask what price would have worked. Show it full screen right after they cancel.

The agent creates a full-screen draft with a `single` question, a jump from the `too_expensive` choice to a `number` question, two endings and the trigger `subscription_cancelled` (once per contact), and asks before launching it.

## Guardrails

* `create_survey` always saves `status: "draft"`; `update_survey` only writes the draft definition. Neither publishes nor changes a live survey's version, status or targeting.
* `publish_survey` goes through the same publish endpoint as the dashboard and needs survey edit rights. Agents are told to launch only after you agreed, the same rule as for other outbound messages.
* `reach_out_to_respondent` sends nothing unless the call passes `send: true`, which agents should only do after you approved the exact message.
* Results stay compact: lists are capped, long answers are clipped and responses are paged with a cursor.
* Customer-facing agent runs (Kai answering one customer) can't use survey tools.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.