Tracklution Agent Install Protocol

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:

{
  "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:

{
  "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):

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):

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:

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.

[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:

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:

{
  "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:

Lovable (user-action)

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

Replit Agent (user-action)

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

Bolt (user-action)

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

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.