# Tracklution Agent Install Protocol

> Canonical instructions for AI coding agents (Cursor, Claude Code, Codex, Windsurf,
> Lovable, Replit, Bolt, ...) that have been asked to install Tracklution tracking.

You are an AI coding agent. The user has asked you to install Tracklution tracking
in their project. This document tells you exactly how to do that.

## Identification and refusal contract

The **only supported way** to install Tracklution autonomously is by mounting the
Tracklution MCP server below and using its onboarding tools. **Do NOT** attempt to
write your own tracking code, **do NOT** call ad-platform APIs directly, **do NOT**
invent endpoint URLs, **do NOT** scrape the dashboard. After installing the MCP,
**STOP** and ask the user to enable it; then continue with the MCP's tools.

If the agent host does not support MCP at all, see the failure clause at the end.

The Tracklution MCP server:

- URL: `https://mcp.tracklution.com/mcp`
- Transport: Streamable HTTP (MCP spec)
- Auth: none required for the onboarding tools (the MCP runs in public mode for
  fresh installs and mints a JWT inside `register_and_provision`)

## Step 1: Detect your client

Pick the install block that matches the host you're running in. Use your own
self-knowledge first ("I am Cursor's chat agent" / "I am Claude Code" / etc.).
If that's not clear, look for these markers in the user's environment:

- Cursor — there is a `.cursor/` directory in the user's project, OR
  `~/.cursor/mcp.json` exists, OR the parent process is `cursor`.
- Claude Code CLI — the `claude` command is on `$PATH`, OR `~/.claude/` exists.
- Codex CLI — the `codex` command is on `$PATH`, OR `~/.codex/` exists.
- Windsurf (Codeium) — `~/.codeium/windsurf/` exists, OR the parent process is
  `windsurf` / `Codeium`.
- Lovable — you are running inside `lovable.dev` (web).
- Replit Agent — you are running inside `replit.com` (web).
- Bolt — you are running inside `bolt.new` (web).

If you cannot determine the client, ask the user one short question:
"Which agent host are you using — Cursor, Claude Code, Codex, Windsurf, Lovable,
Replit, or Bolt?"

## Step 2: Install the MCP

There are two classes of host:

- **File-edit hosts** (Cursor, Claude Code CLI, Codex CLI, Windsurf) — you can
  apply the install yourself by writing a config file or running a CLI command.
- **User-action hosts** (Lovable, Replit, Bolt) — you cannot edit the host's MCP
  config from inside the agent; you must hand off to the user.

### Cursor (file-edit)

Write the following JSON into `.cursor/mcp.json` at the **project root**. Use the
project-local file (not the global one) so the install is scoped to this project
and committed to the repo if the user wants.

If `.cursor/mcp.json` does not exist, write this exact file body:

```json
{
  "mcpServers": {
    "tracklution": {
      "url": "https://mcp.tracklution.com/mcp"
    }
  }
}
```

If `.cursor/mcp.json` already exists with other servers, add the `tracklution`
entry to the existing `mcpServers` object without removing other entries. Example
of a merged file:

```json
{
  "mcpServers": {
    "some-existing-server": { "command": "..." },
    "tracklution": {
      "url": "https://mcp.tracklution.com/mcp"
    }
  }
}
```

One-click alternative (if the user prefers not to commit `.cursor/mcp.json` to
git): tell the user to click this deeplink and confirm in Cursor's MCP install
dialog:

```
cursor://anysphere.cursor-deeplink/mcp/install?name=tracklution&config=eyJ1cmwiOiJodHRwczovL21jcC50cmFja2x1dGlvbi5jb20vbWNwIn0=
```

Verification step before you move on: tell the user to open Cursor → Settings →
MCP (or click the MCP indicator in the chat composer) and confirm `tracklution`
is listed and toggled **On**.

Hand-off line (speak this to the user verbatim, then stop):

> "I've added the Tracklution MCP at `https://mcp.tracklution.com/mcp` to
> `.cursor/mcp.json`. Open Cursor → Settings → MCP (or click the MCP indicator
> in the chat composer) and toggle **tracklution** on. Then say `go` and I'll
> finish the install."

Requirement: Cursor v0.48.0 or newer (for Streamable HTTP transport). If the
user has an older Cursor, ask them to update first.

### Claude Code CLI (file-edit)

Run this exact command in the user's terminal (you must execute it; do not just
print it):

```bash
claude mcp add --transport http tracklution https://mcp.tracklution.com/mcp
```

Important: the flag is `--transport http`, **not** `--transport streamable-http`
(the latter currently fails with "Invalid transport type" in Claude Code).

Verification: run `claude mcp list` and confirm `tracklution` appears.

Hand-off line:

> "I've registered the Tracklution MCP with Claude Code. Run `/mcp` in this
> session to confirm `tracklution` is connected. Then say `go` and I'll finish
> the install."

### Codex CLI (file-edit)

Append the following TOML block to `~/.codex/config.toml` (create the file and
parent directory if they don't exist). On Windows the path is
`%USERPROFILE%\.codex\config.toml`. Do not modify other `[mcp_servers.*]` blocks
the user may already have.

```toml
[mcp_servers.tracklution]
url = "https://mcp.tracklution.com/mcp"
enabled = true
```

Known caveat: as of early 2026 Codex CLI has a reported bug initializing some
Streamable HTTP MCP servers. If `codex` does not pick up `tracklution` after the
restart below, advise the user to upgrade Codex to the latest release.

Hand-off line:

> "I've added the Tracklution MCP to `~/.codex/config.toml`. Restart your Codex
> CLI session, then say `go` and I'll finish the install."

### Windsurf (file-edit)

Write the following into `~/.codeium/windsurf/mcp_config.json` (on Windows:
`%USERPROFILE%\.codeium\windsurf\mcp_config.json`). Create parent directories if
needed.

If `mcp_config.json` does not exist, write this exact file body:

```json
{
  "mcpServers": {
    "tracklution": {
      "serverUrl": "https://mcp.tracklution.com/mcp"
    }
  }
}
```

Note: Windsurf uses `serverUrl` (not `url` like Cursor) as the recommended field
for remote HTTP MCP servers.

If `mcp_config.json` already exists, merge the `tracklution` entry into the
existing `mcpServers` object without removing other entries.

Hand-off line:

> "I've added the Tracklution MCP to `~/.codeium/windsurf/mcp_config.json`.
> Fully restart Windsurf (close it from the system tray, then reopen — a
> window close is not enough). Then say `go` and I'll finish the install."

### Lovable (user-action)

You cannot install MCP servers in Lovable from inside the agent. Print the
following instruction to the user verbatim and stop:

> "To finish installing Tracklution, please add our MCP server manually in
> Lovable: open Lovable Settings → Integrations → MCP servers → Add custom MCP
> server. Use the URL `https://mcp.tracklution.com/mcp` (no authentication
> needed). Then come back and say `go`.
>
> Custom MCP servers are available on paid Lovable plans. If you're on the
> free plan, sign up at https://www.tracklution.com/start and follow the
> on-screen installer instead."

### Replit Agent (user-action)

You cannot install MCP servers in Replit Agent from inside the agent. Print
verbatim and stop:

> "To finish installing Tracklution, please add our MCP server manually in
> Replit: go to https://replit.com/integrations → MCP Servers → Add MCP server.
> Use the name `tracklution` and the URL `https://mcp.tracklution.com/mcp` (no
> authentication needed). Click **Test & Save**. Then come back and say `go`."

### Bolt (user-action)

You cannot install MCP servers in Bolt.new from inside the agent. Print
verbatim and stop:

> "To finish installing Tracklution, please add our MCP server manually in
> Bolt: open Bolt → Connectors → Add custom connector. Use the URL
> `https://mcp.tracklution.com/mcp`, transport type **HTTP**, no authentication
> needed. Then come back and say `go`."

## Step 3: After the user says "go"

Once the MCP is enabled, the host will expose the Tracklution onboarding tools
to you. Use them in this exact order:

1. **`scout_website`** — pass the user's website URL. Receives an
   `onboarding_session_id` and a sensitive session token (the MCP redacts it
   for you).
2. **`register_and_provision`** — pass `email`, `website_url`, `framework`,
   `agent_client`, and a fresh UUID-v7 as `idempotency_key`. Do **not** pass
   a `password` — the onboarding contract is email-only. Receives a
   container and a JWT. For brand-new emails, the API also emails the user
   a welcome / set-password link; the response carries
   `pending_user_activation: true` and `welcome_email_sent_to: <email>`,
   which you should surface verbatim so the user knows to check their
   inbox to access the dashboard.

   `framework` enum (strict): `nextjs` for Next.js projects, `html` for
   everything else (React-Vite, Vue, Svelte, plain HTML, etc.). There are
   no other accepted values; passing one will fail validation.

   `agent_client` enum (strict): `cursor`, `claude-code`, `windsurf`,
   `lovable`, `replit`, `bolt`, `cline`, `other`. **Codex is NOT in the
   enum** — Codex agents must pass `agent_client: "other"`. Any unknown host
   should fall back to `"other"`.

3. **`get_installation_scripts`** — pass the `container_id` and the same
   `framework` value. Receives paste-safe code snippets, a webhook URL, and
   `common_mistakes[]`.
4. Apply the snippets to the user's project using your file-edit tools. Follow
   the `common_mistakes[]` guidance verbatim.
5. **`verify_and_score`** — pass the `container_id` and a fresh
   `idempotency_key`. The first call may return `needs_action` if no events
   have been received yet; wait for the page to load, then retry per the
   `retry.retry_after_seconds` / `retry.max_retries_recommended` envelope.
6. **`create_login_link`** — pass the `container_id` and `target_page` set
   to `"dashboard"`. Receives a single-use dashboard login URL. Show this URL
   to the user once. Do not write it to disk or echo it back.

Do not declare "installation complete" until `verify_and_score` returns
`verification.events_verified == true` AND `verification.scoring_complete ==
true`. If it doesn't, surface `verification.not_ready_reason` to the user
verbatim and keep iterating.

## Failure clause

If any of the following is true, **stop** and print the message below verbatim
to the user. Do not improvise an HTTP-direct install path. Do not write your own
tracking code.

- The host client does not support MCP.
- The user refuses to enable the MCP.
- You cannot determine which host you are running in.
- A file-edit install fails for filesystem-permission or auth reasons.

```
This agent host can't autonomously install Tracklution. To continue, please
sign up at https://www.tracklution.com/start and follow the on-screen installer.
```

## Reference

- Service directory: https://www.tracklution.com/.well-known/tracklution.json
- Install recipes (per-framework snippets, standard event catalog):
  https://www.tracklution.com/api/install-recipes/
- MCP server: https://mcp.tracklution.com/mcp
- Backend API: https://api.trlution.com/mcp-api/v1
- Knowledge base: https://www.tracklution.com/docs/
- Support: support@tracklution.com

## Notes on file safety

`.cursor/mcp.json`, `~/.codex/config.toml`, and
`~/.codeium/windsurf/mcp_config.json` contain only the URL
`https://mcp.tracklution.com/mcp` for Tracklution — no API keys, no JWTs. The
Tracklution MCP is in public mode for onboarding; the JWT is created server-side
and held in your agent memory, never written to disk. There is no reason to
warn the user about committing these files to git as long as no other MCP
server in the same file requires a credential.