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

# MCP Server

> Connect AI assistants to your Qonversion project data via the Model Context Protocol

<Note>
  The Qonversion MCP server is currently in **beta**. Tool names, arguments, and OAuth scopes may still change. Not recommended for production-critical workflows yet — we'd love your feedback while we stabilise it.
</Note>

Qonversion provides a remote MCP server that allows AI assistants to access your project data. The server is hosted at `https://mcp.qonversion.io/mcp` and uses OAuth 2.1 for authentication.

The server follows the [MCP Streamable HTTP spec](https://modelcontextprotocol.io/specification/2025-03-26) and supports clients that connect natively over HTTP, as well as clients that use [`mcp-remote`](https://github.com/geelen/mcp-remote) for compatibility.

<Note>
  The MCP server mirrors the [Qonversion REST API v4](/reference/v4/overview) resource surface — each MCP tool corresponds to a v4 operation. Authentication is different, though: HTTP clients authenticate with the project Secret Key, while MCP clients use OAuth 2.1 against your Qonversion account with per-tool scopes. See the full [v4 guide](/reference/v4/overview) for resource-by-resource context, or the [API Reference](/api-reference/rest-api-v4) for the underlying HTTP operations.
</Note>

## Capabilities

The Qonversion MCP server exposes the full surface of the v4 REST API as MCP tools, grouped by resource:

* **Customers** — list, read, delete (GDPR), set properties, list and mutate permissions, and read aggregated metrics.
* **Users, identities, purchases, properties** — look up users, attach external identities, inspect purchase history, set and query user properties.
* **Entitlements** — manage entitlement definitions and grant or revoke them per user.
* **Products** — CRUD products consumed by the SDK.
* **Remote Configurations** — list, create, replace, delete, change status, manage payload mappings, and attach or detach users.
* **Paywalls (Screens)** — list, create, update, publish, duplicate, and pull per-screen and overview analytics.
* **Experiments** — CRUD experiments and groups, change status, attach and detach users, read summary analytics.
* **Segments** — CRUD user segments and list system segments.
* **Analytics** — charts, KPI cards, cohorts, LTV, trial conversion, currencies, and narrative insights.
* **Exports** — start asynchronous data exports and poll their history and status.
* **Events** — inspect the event catalog and the raw event log.
* **Scheduled Reports** — CRUD recurring reports, list destinations, send a test delivery.
* **Integrations** — discover the catalog, create, toggle status, and delete integrations.
* **Automations** — CRUD event-driven automations and change their status.
* **Project settings** — read and update project configuration, rotate the Secret Key, manage store credentials.

The MCP server does **not** use Project or Secret API keys. Authentication is OAuth 2.1 against your Qonversion account, and access to each tool is gated by the OAuth scopes granted during the login flow (e.g., `customers:read`, `screens:read`, `experiments:write`). Your effective permissions mirror your role in the Qonversion dashboard.

## Destructive actions

Destructive tools (`delete_*`, `revoke_*`, `detach_*`, `regenerate_project_secret`) use a two-step confirmation flow designed around **human-in-the-loop** intent. The confirmation token is addressed to the operator, not to the agent — the agent is expected to surface the pending action and wait for explicit approval before executing.

### The flow

1. The agent calls the destructive tool (e.g., `delete_product(product_id: "prem_monthly")`).
2. The server **does not** perform the action. It returns a message listing the pending action, the target **Resource id**, and a short-lived **token** (5-minute TTL). The message is explicitly addressed to the human operator.
3. The agent must surface the pending action to the human and wait for explicit approval.
4. Once approved, the agent calls `confirm_destructive_action` with three required arguments:

| Field              | Type   | Notes                                                                                                                      |
| ------------------ | ------ | -------------------------------------------------------------------------------------------------------------------------- |
| `token`            | string | The opaque token from step 2                                                                                               |
| `resource_id_echo` | string | Must match the **Resource id** verbatim (case-sensitive). A mismatch cancels the pending action and returns a typed error. |
| `reason`           | string | Short justification, 1-256 characters. Captured in the audit log.                                                          |

### Why the echo + reason

These two fields turn a single-turn `delete → confirm` chain into an act of deliberate re-statement. The agent can't forward the token blindly — it has to restate the target (which surfaces the action to the human) and commit a reason (which is easy to spot in review if fabricated). Silent auto-confirmation stops being possible without the model making a distinct act that's visible in the transcript.

### Tokens

* Tokens are bound to the MCP session that requested them — another session can't consume them.
* Tokens expire after 5 minutes. Expired tokens must be re-requested from the original tool.
* A token can be used at most once. A mismatched `resource_id_echo` consumes the token and cancels the pending action.
* Tokens are **not** logged in the audit trail; the resource id and reason are.

### Destructive tools affected

`delete_automation`, `delete_customer`, `delete_entitlement`, `delete_experiment`, `delete_experiment_group`, `delete_integration`, `delete_product`, `delete_remote_configuration`, `delete_scheduled_report`, `delete_screen`, `delete_segment`, `detach_experiment_user`, `detach_user_from_remote_configuration`, `revoke_customer_permission`, `revoke_user_entitlement`, `regenerate_project_secret`.

## Setup

### Claude Desktop

Add the following to your `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "Qonversion": {
      "type": "streamable-http",
      "url": "https://mcp.qonversion.io/mcp"
    }
  }
}
```

### Claude Code

```bash theme={null}
claude mcp add --transport http Qonversion https://mcp.qonversion.io/mcp
```

Run `/mcp` in a Claude Code session to go through the authentication flow.

### Cursor

Add the following to your `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "Qonversion": {
      "url": "https://mcp.qonversion.io/mcp"
    }
  }
}
```

### Visual Studio Code

1. Press `CTRL/CMD + P` and search for **MCP: Add Server**.
2. Select **Command (stdio)**.
3. Enter the following and press enter:

```
npx mcp-remote https://mcp.qonversion.io/mcp
```

4. Enter the name **Qonversion** and press enter.
5. Open **MCP: List Servers**, select **Qonversion**, and click **Start Server**.

### Windsurf

1. Press `CTRL/CMD + ,` to open settings.
2. Go to Cascade → MCP servers.
3. Select **Add Server → Add custom server** and add the following:

```json theme={null}
{
  "mcpServers": {
    "Qonversion": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.qonversion.io/mcp"]
    }
  }
}
```

### Zed

1. Press `CMD + ,` to open settings.
2. Add the following:

```json theme={null}
{
  "context_servers": {
    "Qonversion": {
      "source": "custom",
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.qonversion.io/mcp"],
      "env": {}
    }
  }
}
```

### Codex

Add the following to your `~/.codex/config.toml`:

```toml theme={null}
[features]
experimental_use_rmcp_client = true

[mcp_servers.Qonversion]
url = "https://mcp.qonversion.io/mcp"
```

Run `codex mcp login Qonversion` to authenticate.

### Other clients

For clients that support MCP via stdio, use the following configuration:

* **Command**: `npx`
* **Arguments**: `-y mcp-remote https://mcp.qonversion.io/mcp`
* **Environment**: None

## Authentication

On the first connection, your MCP client will open a browser window to authenticate with your Qonversion account. No manual configuration of tokens or API keys is required.