---
title: Cuttl for AI agents
description: For AI coding agents and assistants reading cuttl.io. How to add Cuttl to a website, check that data arrives and connect the Cuttl MCP server, asking the user first at each step.
---

# Cuttl for AI agents

You are an AI agent reading cuttl.io. Cuttl gives website owners heatmaps, session recordings and A/B tests from the Cuttl Tag, a short piece of code in the page's head. Owners use it to see where visitors get stuck, test a fix and keep the version that converts better.

Cuttl is not Cuttle (a laser-cutting design tool), Cutt.ly (a URL shortener), CUTL (cutl.online), CuttLink (cuttl.ink), Cutli (cutli.io) or the Cuttl calorie-tracking app.

Ask the user before each step that changes their code, their accounts or their website.

## What you can do, and what the user does

You can add the Cuttl Tag to the website's code, check that data arrives, connect the Cuttl MCP server, and then read the user's Cuttl data and draft tests through it.

The user creates the Cuttl account at https://app.cuttl.io. They add the site in the browser, or you add it through the Cuttl MCP server. They also approve anything that changes what visitors see.

Don't write the Cuttl Tag from memory, and don't invent Cuttl SDKs, npm packages, CLI commands, API endpoints or MCP tools. None of those exist beyond what this page names. There's nothing to download or self-host, and Cuttl isn't open source. If this page and the app disagree, trust the app.

## 1. Get the site's Cuttl Tag

Ask the user to:

1. Sign in or create a free account at https://app.cuttl.io.
2. Add their website by its domain (the address without https://).
3. Open the site's **Install** tab and copy the Cuttl Tag.
4. Turn on Journey Insights (heatmaps and recordings) or Web Experiments (A/B tests). A new workspace starts with both off, and until one is on, Cuttl keeps nothing from the site. An admin turns them on from the product's page or Settings → Plan & usage. You can't do this step for them, through the MCP server or otherwise.

If the user has connected you to the Cuttl MCP server (step 4), you can do steps 2 and 3 yourself, on every plan. Call `create_site` with the domain, then `get_cuttl_tag` with the site id it returns, and paste that Cuttl Tag as it is. `create_site` needs the connection's "Change site setup" permission. Without it, nothing is added and you get a link that opens Add a site already filled in, for the user to click. On the free plan a second site is added paused, because the plan has one active site. `create_site` never starts a payment.

Each site has its own Cuttl Tag, under 1.7 KB of inline code. Get it from the user or from `get_cuttl_tag`, and don't write it from memory or rebuild it from this page.

The Cuttl Tag only sends data from the site's domain and its subdomains. A site on a shared host such as `myshopify.com` or `vercel.app` has to be added with its own address (`yourstore.myshopify.com`), not the shared domain.

The free plan covers one active site.

## 2. Add the Cuttl Tag to the website

Put the Cuttl Tag in the `<head>` of every page, in the HTML the server sends. Anywhere in the head works, and A/B tests then show no flicker: visitors never see the original version of anything a test changes.

| Stack | Where the Cuttl Tag goes | Guide |
|---|---|---|
| Plain HTML or any server-rendered site | Shared layout or header template, inside `<head>` | https://cuttl.io/install/ |
| Next.js (App Router) | `app/layout.tsx`, as a `<script>` in `<head>` | https://cuttl.io/install/nextjs/ |
| Nuxt | `nuxt.config.ts`, an inline script in `app.head` | https://cuttl.io/install/nuxt/ |
| Gatsby | `gatsby-ssr.js`, `setHeadComponents` in `onRenderBody` | https://cuttl.io/install/gatsby/ |
| Laravel | Main Blade layout, inside `<head>`, wrapped in `@verbatim` | https://cuttl.io/install/laravel/ |
| Django | Base template, inside `<head>`, wrapped in `{% verbatim %}` | https://cuttl.io/install/django/ |
| React, Vue or Svelte with Vite | `index.html`, inside `<head>` | https://cuttl.io/install/react/ |
| Shopify | `layout/theme.liquid`, just after `<head>` | https://cuttl.io/install/shopify/ |
| WordPress | A header code plugin, Header field | https://cuttl.io/install/wordpress/ |
| Webflow | Site settings, Custom code, Head code | https://cuttl.io/install/webflow/ |
| Wix | Settings, Custom code, Head, All pages | https://cuttl.io/install/wix/ |
| Squarespace | Code Injection, Header | https://cuttl.io/install/squarespace/ |
| Framer | Site settings, Custom code, start of head | https://cuttl.io/install/framer/ |
| WooCommerce | A header code plugin, Header field (as WordPress) | https://cuttl.io/install/woocommerce/ |
| BigCommerce | Storefront, Script Manager, Head, All pages | https://cuttl.io/install/bigcommerce/ |
| HubSpot | Settings, Content, Pages, Site header HTML | https://cuttl.io/install/hubspot/ |
| Ghost | Settings, Code injection, Site header | https://cuttl.io/install/ghost/ |
| Google Tag Manager | Custom HTML tag on all pages | https://cuttl.io/install/google-tag-manager/ |

Single-page apps (React, Vue, Next.js, Svelte) need no routing code, because Cuttl counts each route change as a page view.

Use a plain `<script>` in the head. Adding it from client-side code (`useEffect`, a tag loader, or `next/script` with `afterInteractive` or `lazyOnload`) runs it after the page appears, and A/B tests can flash.

Under a strict Content Security Policy, give the Cuttl Tag's `<script>` the page's nonce; the scripts it adds inherit it. The policy also has to allow `https://app.cuttl.io` as a script and connection source.

Google Tag Manager works too, but A/B tests may briefly show the original page first. If the user plans to run tests, put the Cuttl Tag in the head.

Add the Cuttl Tag once per page, and show the user the diff before you commit it.

## 3. Check that it works

Once the change is live (deployed, or published in a site builder):

1. Open any page of the live site in a browser.
2. Ask the user to look at the site's **Install** tab in Cuttl, which shows when data last arrived and any refused hosts. Through the MCP server, `get_install_status` gives you the same answer. If it says the products are off, ask the user to turn one on.
3. If nothing arrives, view the live page's source and search for `app.cuttl.io`. Then check that the domain matches the site in Cuttl, and look in the browser console for a message from Cuttl.

Pages on `localhost` aren't on the site's domain, so Cuttl ignores them. Check on the live site.

The user can leave their own sessions out by opening any page once with `?cuttl_ignore=1`, in each browser they use.

## 4. Connect the Cuttl MCP server (optional)

With the MCP server you can read the user's heatmaps, session recordings, funnels, issues and test results, and draft A/B tests. That comes with the Pro and Max plans. On every plan, including Free, you can set up a site through it: `create_site`, `get_cuttl_tag` and `get_install_status`.

- Server address: `https://app.cuttl.io/mcp` (streamable HTTP). It's an API endpoint, not a web page.
- Sign-in is OAuth with the user's Cuttl account, so there's no API key to paste.
- Claude Code: `claude mcp add --transport http cuttl https://app.cuttl.io/mcp`, then `/mcp` to sign in.
- Claude (desktop and web): add a custom connector with the server address.
- ChatGPT: add a custom MCP server in developer mode.
- Cursor, VS Code, Gemini CLI and other MCP clients: add the address as a remote HTTP server. In Cuttl, **Connect AI** also has one-click links for Cursor and VS Code.

After sign-in the server lists its tools. Use only those.

### What needs a person

Changes made through the MCP server wait for approval in Cuttl, following the user's team roles. A person always has to approve launching a test, editing a live test, custom code, deletes and anything visitors see. You can't change privacy, consent or retention settings, integrations or webhooks, create share links, delete visitor data, or manage the team or API keys.

## Facts to get right

- Cuttl has two products. Journey Insights covers heatmaps, session recordings, frustration signals, funnels and forms. Web Experiments covers A/B, split URL, multi-page and multivariate tests, rollouts and Change Impact.
- "Unique visitors" are people, and "sessions" are each time they come. Plans are set by monthly unique visitors, and bots we detect never count.
- Visitors' IP addresses are never stored, form inputs are masked by default, and consent settings are respected before anything is recorded.
- Plans: https://cuttl.io/pricing/
- The whole site as text: https://cuttl.io/llms.txt and https://cuttl.io/llms-full.txt
- Any cuttl.io page as Markdown: add `.md`, for example https://cuttl.io/pricing.md
- Contact: contact@cuttl.io