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

# MCP server

> Connect Claude, ChatGPT, Cursor, VS Code, Claude Code and other AI assistants to Usertick through the Model Context Protocol, with a sign-in.

Usertick hosts a [Model Context Protocol](https://modelcontextprotocol.io) server, so nothing needs to be installed. An AI assistant that supports MCP connects to its URL, and you sign in to Usertick and choose what it may do. When you ask in plain language, the assistant reads your surveys, responses and metrics, triages responses, pauses surveys and manages webhook subscriptions. It can do only what you allowed and what your own role can do.

```text theme={null}
Server URL: https://mcp.usertick.com/mcp
```

Every member can connect an assistant for themselves. The sign-in follows the [MCP authorization spec](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization), so no key or token is copied anywhere. The server takes only the access tokens Usertick issues when an assistant signs in. API keys are for the [REST API](https://docs.usertick.com/developers/api/overview.md), and the MCP server refuses them.

## Connect an assistant

> [tab] Claude
>
> In Claude on the web, the desktop app or mobile, open **Settings → Connectors**, select **Add custom connector** and enter `https://mcp.usertick.com/mcp`. Claude opens the Usertick sign-in.

> [tab] ChatGPT
>
> In ChatGPT, open **Plugins**, select the plus button, then **Add custom MCP server**. Enter `https://mcp.usertick.com/mcp` and choose OAuth. ChatGPT opens the Usertick sign-in.

> [tab] Claude Code
>
> ```bash theme={null}
> claude mcp add --transport http usertick https://mcp.usertick.com/mcp
> ```
>
> Then run `/mcp` in Claude Code and select the Usertick server to sign in.

> [tab] Cursor
>
> Add the server to `.cursor/mcp.json`. Cursor opens the sign-in when it first connects.
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "usertick": { "url": "https://mcp.usertick.com/mcp" }
>   }
> }
> ```

> [tab] VS Code
>
> Add the server to the `mcp.json` file of VS Code. VS Code opens the sign-in when it first connects.
>
> ```json theme={null}
> {
>   "servers": {
>     "usertick": { "type": "http", "url": "https://mcp.usertick.com/mcp" }
>   }
> }
> ```

> [tab] Gemini CLI
>
> ```bash theme={null}
> gemini mcp add --transport http usertick https://mcp.usertick.com/mcp
> ```

> [tab] Windsurf and others
>
> An assistant without its own sign-in, such as Windsurf, Cline or Continue, runs the server through the `mcp-remote` bridge, which opens the sign-in in your browser. For Windsurf, add this to `mcp_config.json`:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "usertick": { "command": "npx", "args": ["-y", "mcp-remote", "https://mcp.usertick.com/mcp"] }
>   }
> }
> ```

Members who can manage developer settings find the same setup under **Settings → Developers → API keys**, in **Connect an AI assistant**, where Cursor and VS Code also get an install link.

## Sign in and choose the access

When the assistant first connects, Usertick asks you to sign in and shows what the assistant asks for.

**1. Pick the organization**

The assistant reaches one organization. Any organization you belong to can be picked, as long as your role reaches every survey in it.

**2. Choose what it may do**

Reading surveys, responses, metrics and webhooks is selected to start. Select more only when the assistant should change something, such as pausing surveys or updating responses.

**3. Allow access**

Usertick sends you back to the assistant, which can now use the tools your choice allows.

If Usertick doesn't recognize the assistant, the sign-in says so and names where it sends you after you answer. Allow access only to an assistant you are connecting yourself.

The assistant acts as you: what you allowed limits it, and so does your role. A change your role can't make fails with `AUTHZ-001-002`, whatever you allowed. To change what it may do, connect it again and choose its access anew: the new choice replaces the old one.

## Disconnect an assistant

Under **Settings → Security**, **Connected assistants and apps** lists the assistants you connected in the active organization. Select **Revoke access** to disconnect one at once. Members who can manage integrations or developer settings see every member's assistants under **Settings → Developers → API keys** and can revoke any of them.

Usertick also disconnects an assistant when you leave the organization or your account is deleted, and when it goes unused: a connection that never finished signing in after a day, and one without a usable refresh token after 90 days.

## Test the connection

Ask the assistant something like *"Use Usertick to pull the latest responses and summarize the main complaints."* The assistant calls `get_recent_responses` and answers from your data. If a tool fails, ask the assistant to run `test_auth`, which shows what you allowed. An `APK-004-004` error means you didn't allow the access that tool needs.

## Tools

Each kind of access you allow unlocks its own tools. A tool whose access you didn't allow returns `APK-004-004`.

| Tool | What it does | Scope needed |
| - | - | - |
| `test_auth` | Checks the connection and returns your organization, the assistant's name, what you allowed as scopes, and its rate limits. | None |
| `list_surveys` | Lists surveys by status, site or channel, with archived surveys only when asked. With a survey id, returns that survey with its questions, languages and settings. | `surveys:read` |
| `list_sites` | Lists your organization's sites. | `surveys:read` |
| `pause_survey` | Pauses a published survey. | `surveys:write` |
| `resume_survey` | Resumes a paused survey. | `surveys:write` |
| `list_responses` | Lists responses, newest first, with every filter combined: surveys, site, the respondent's email or user id, status, AI type, urgency, theme, category and sentiment, text answers only, a time window, and `updatedSince`. Pages by cursor, up to 100 per page. With a response id, returns that one response. | `responses:read` |
| `get_recent_responses` | Returns the newest responses, 3 by default and up to 100, from every survey or one survey. With `response.analyzed`, it returns only analyzed responses, and with `response.urgent`, only urgent ones. With `response.status_changed`, it returns the latest status changes, each with who made it. It filters by feedback type, urgency and theme where the event allows those filters. | `responses:read` |
| `list_themes` | Returns your categories and their themes, with the ids the theme and category filters take. | `responses:read` |
| `list_response_notes` | Lists a response's notes, oldest first. | `responses:read` |
| `update_response` | Changes a response's status, type, urgency or assignees. | `responses:write` and `responses:read` |
| `list_members` | Lists your organization's members, with the ids `update_response` assigns. | `responses:write` |
| `add_response_note` | Adds a note to a response. | `responses:write` |
| `update_response_note` | Changes the text of a note you wrote. | `responses:write` |
| `delete_response_note` | Deletes a note you wrote. | `responses:write` |
| `delete_response` | Erases one response and returns the erasure job. | `responses:delete` |
| `erase_respondent` | Erases every response of one person, by email or user id, and returns the erasure job. See [Erase personal data](https://docs.usertick.com/developers/api/erasure.md). | `responses:delete` |
| `get_job` | Shows how far an erasure job got. | `responses:delete` |
| `get_metrics` | Returns the headline numbers (responses, NPS, CSAT, CES and average score), one metric per day, week or month, or the responses per value of one dimension. See [Metrics](https://docs.usertick.com/developers/api/metrics.md). | `analytics:read` |
| `list_webhooks` | Lists the subscriptions the assistant made, without their secrets. | `webhooks:read` |
| `list_webhook_deliveries` | Lists a subscription's deliveries from the last 30 days, newest first, all of them or only successes or failures. | `webhooks:read` |
| `subscribe_webhook` | Subscribes an `https://` URL to one of the [six events](https://docs.usertick.com/developers/webhooks/events.md), for one survey or every survey, with the filters that event takes. Returns the subscription id and the `whsec_` signing secret. | `webhooks:write` and `responses:read` |
| `unsubscribe_webhook` | Deletes a subscription the assistant made, by its id. | `webhooks:write` |
| `resend_webhook_delivery` | Sends a delivery again with the same body and `webhook-id`. | `webhooks:write` |

Every tool tells the assistant whether it only reads or changes something. `delete_response`, `erase_respondent`, `delete_response_note` and `unsubscribe_webhook` are marked as removing data, so an assistant that confirms risky actions asks before it runs them.

Responses are returned as the [Response resource](https://docs.usertick.com/developers/api/response-object.md), with the survey, every answer with its question text, the respondent's email when there is one, the status and assignees, and the AI's type, urgency, theme, category and sentiment. Deliveries to a subscribed URL carry the same resource in `data`, except `theme.spiking` deliveries, which carry the spike. Deliveries are signed as [Verify signatures](https://docs.usertick.com/developers/webhooks/verify.md) describes.

The time window of `list_responses` and `get_metrics` (`from` and `to`) and `updatedSince` take an RFC 3339 time, such as `2026-10-14T09:30:00Z`, or a date alone, such as `2026-10-14`. A time without an offset reads as UTC. A date alone starts at that day's midnight in UTC, and as `to` it includes that whole UTC day. Any other value is refused before a request reaches the API.

The server is a thin layer over the [REST API](https://docs.usertick.com/developers/api/overview.md). The API itself enforces what you allowed, your role, the plan, retention windows and [rate limits](https://docs.usertick.com/developers/api/rate-limits.md). When a call fails, the tool's error carries the API's [error code](https://docs.usertick.com/developers/api/errors.md) with its message, or every invalid field with its message. When the API sends `Retry-After`, as it does with a `429`, the error also says how long to wait. The assistant can react to each of these.

## Limits

* **One message per request.** The server takes one JSON-RPC message per request, and a batch (a JSON array of messages) returns `400`.
* **120 requests per minute** to the server from one IP address. A request over the limit returns `429`, and the client can try again after a minute.
* **15 seconds per API call.** When the API doesn't respond in time, the tool returns an error that asks the assistant to try again.
* The API's own [rate limits](https://docs.usertick.com/developers/api/rate-limits.md) also apply to the connection.
* The organization's plan must include the API (Pro and up). After a move to a lower plan, the connection stays and its calls are refused, and the approval isn't revoked, so it works again after an upgrade.

> [!NOTE]
>
> Every connection belongs to the person who signed in. To give a script or a server Usertick access without a person, use an [API key](https://docs.usertick.com/developers/api/authentication.md) with the REST API instead.


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