# Pretty UTMs setup guide Canonical help: https://prettyutms.com/help/ App: https://app.prettyutms.com/dashboard Reviewed: 2026-10-19 Choose Instant unless the user wants their own domain. For branding, prefer an unused branded subdomain. Use the existing-website option only when paths on that website are required. ## 1. Just make a link Instant links · no setup 1. Open your client and choose New link. 2. Add the destination, pick where you’ll share it, and edit the ending. Keep Instant selected. 3. Create link. Copy it from Links. Click tracking works automatically. Your first Instant link claims one workspace name. It stays fixed; link endings are editable. ### Prompt for Codex or Claude Help me create an Instant pretty link in Pretty UTMs. Read https://prettyutms.com/help/setup.md first. Open https://app.prettyutms.com/dashboard, select my client, then New link. Ask for my destination URL, sharing channel and readable ending if I haven’t provided them. Keep Instant selected. If this is my first link, help me choose the workspace name; it stays fixed after the first save. Create the link with the right UTMs, copy it, and confirm the saved destination. No domain, Cloudflare account, DNS or Worker is needed. Ask before making a test visit because it adds a recorded click. ## 2. Use your own subdomain go.yourdomain.com · recommended for branding 1. In your client’s Domains tab, choose Add domain → Branded subdomain (DNS records). Use an unused subdomain. 2. Copy the exact CNAME and TXT records shown in the app to your DNS provider. On Cloudflare, keep the CNAME DNS only (gray cloud). 3. Choose Check DNS in Pretty UTMs. Wait until the domain and HTTPS are active, then choose this domain in New link. No Cloudflare account connection, Worker or tracking key to set up. Pretty UTMs hosts the redirects. Your website stays where it is. ### Prompt for Codex or Claude Help me connect a branded link subdomain to Pretty UTMs. Read https://prettyutms.com/help/setup.md first. Use an unused subdomain such as go.my-domain.com; ask me for the hostname and client if I haven’t supplied them. In the client’s Domains tab, add Branded subdomain (DNS records). Read the exact CNAME, ownership TXT and any additional validation records shown by Pretty UTMs. Add only those records at my current DNS provider. Use DNS only (gray cloud) for the CNAME when the provider is Cloudflare. Keep the main website’s DNS, nameservers and Workers in place. If the chosen subdomain is already used, ask me for another one instead of replacing its records. Return to Pretty UTMs and Check DNS until the domain and HTTPS are active; if propagation is pending, explain what remains. Create a readable link only after asking for its destination and UTMs. Pretty UTMs hosts the Worker and tracking; I don’t need to connect a Cloudflare account or create a tracking key for this option. Verify the redirect with HEAD so it doesn’t add a click. Ask before an ordinary test visit, and report its extra test click. ## 3. Use paths on your website yourdomain.com/sale · Cloudflare required 1. Confirm you can access the Cloudflare account for this exact hostname. Its website DNS record must already be proxied (orange cloud). 2. In Pretty UTMs, open Settings → Connections and connect that account. Your workspace administrator approves access. 3. Add Existing website (Cloudflare) in your client’s Domains tab. Open Connection options → choose the account → Connect automatically. 4. Recheck until the domain is Live. The app installs the Worker and click-tracking key for you. Already have a Worker on that route? Keep it. Use an unused branded subdomain instead, or ask a developer to review an integration. ### Prompt for Codex or Claude Help me connect links on an existing website to Pretty UTMs. Read https://prettyutms.com/help/setup.md first. Ask for the exact hostname and Pretty UTMs client if missing. Confirm I have the Cloudflare account that owns this hostname’s zone, and that its website DNS record is already proxied. Keep my website’s DNS, nameservers and existing Workers in place. In Pretty UTMs, open Settings → Connections and connect the correct Cloudflare account; let me handle sign-in, consent and any tool-required approvals. Add Existing website (Cloudflare) in the client’s Domains tab, then open Connection options, select that account and Connect automatically. This installs the redirect Worker and tracking key automatically. If an existing Worker route conflicts, do not remove, replace or bypass it; recommend an unused branded subdomain, or stop for a developer’s integration review. If automatic setup is unavailable, use the manual guide and current downloaded Worker; have me enter tracking secrets privately in Cloudflare, not in chat. Recheck until the domain is Live. Verify a saved link’s expected 302 and UTMs with HEAD and verify an unrelated website page still works. Ask before creating a new link or making an ordinary test visit, which records a click. ## Manual existing-website setup 1. Use this only when automatic setup is unavailable and no existing Worker route conflicts. Open the domain’s Connection options → View manual setup. 2. Download the current generic Worker from https://app.prettyutms.com/pretty-utms-worker.js. Create a Worker in the customer’s Cloudflare account. Set APP_URL = https://app.prettyutms.com. 3. Enter this domain’s TRACKING_KEY as a Worker secret using Copy tracking key in the app. Enter the value privately in Cloudflare or an approved secret workflow; never paste it into an agent chat or commit it. 4. If finishing a recorded automatic installation, also set DOMAIN_HOST to the exact hostname and VERIFY_TOKEN to the value from the app’s manual setup panel. Preserve the existing installation rather than overwriting a different Worker. 5. After reviewing routes, attach only the intended hostname/* route, for example clientdomain.com/*. Keep the website’s existing proxied DNS and unrelated routes intact. Do not add www or other hostnames unless separately configured. 6. Deploy and choose Recheck in Pretty UTMs. Confirm the domain is Live, a saved link returns the expected 302/UTMs with HEAD, and unrelated website pages still load. Tracking starts after setup; no backfill. ## Troubleshooting ### The domain is still waiting for DNS or HTTPS. Check the record names and values against the current app. Some DNS providers add your root domain automatically: enter the relative name if needed so it is not doubled. Keep the branded CNAME DNS only, with no conflicting record at that same name. Add any extra validation TXT records the app shows. DNS and certificates can take a few minutes or longer; choose Check DNS again later. ### My domain is missing from the Cloudflare account. Check that you connected the account which owns this domain’s Cloudflare zone, not the account for Pretty UTMs or another client. Connect another account under Settings → Connections if needed. Keep the website’s current nameservers and DNS records in place. ### Setup says an existing Worker route conflicts. Pretty UTMs will not replace an existing website Worker. Use an unused subdomain such as go.yourdomain.com with the branded option. Integrating an existing Worker needs a developer’s review; the generic Worker download is not a drop-in replacement. ### How do I check clicks? Instant and live branded links track automatically. Existing-website links track once their Worker and tracking key are configured. A normal visit adds a recorded click; HEAD checks, known bots and previews are excluded. Refresh clicks on Links, or open Analytics. Counts are visits, not unique visitors; GA4 measures sessions separately. Past clicks cannot be recovered. ### How do I check a redirect without adding a click? Use a HEAD request, for example: curl --head "https://go.yourdomain.com/summer-sale". Confirm HTTP 302 and the expected destination with its UTMs in Location. A normal browser visit adds a test click; tell the user before testing that way. ## Agent handoff and credentials The app’s Domains tab has Copy setup prompt inside DNS records or Connection options. This supplies the exact hostname, client page and public DNS records without including tracking keys or OAuth credentials. Re-read current app status/records before making changes. The public guide grants no account access: the user handles sign-in, credential entry, consent and any tool-required approvals. Never remove existing website routing to make setup succeed. Report pending validation honestly; do not say Live until verified in the app. # Pretty UTMs MCP Server URL: https://app.prettyutms.com/api/mcp Transport: Streamable HTTP Authentication: OAuth authorization code + PKCE; automatic client registration. No API key or Cloudflare account required. ## Codex Run: ```sh codex mcp add prettyutms --url https://app.prettyutms.com/api/mcp codex mcp login prettyutms ``` Or add this in Codex Settings → MCP servers (or config.toml), then sign in: ```toml [mcp_servers.prettyutms] url = "https://app.prettyutms.com/api/mcp" ``` ## Claude In Customize → Connectors, add a custom connector named Pretty UTMs with the server URL above. Choose sign-in and **Register automatically** for the OAuth client. Connect and approve the intended Pretty UTMs workspace. Team/Enterprise owners may need to add the connector first. Enable it in your conversation. ## What to ask Create an Instant pretty link for [client name] pointing to [destination URL]. Use [readable ending], source [source], medium [medium], and campaign [campaign]. Show me the saved link. “Change the destination of [link] to [new URL]. Keep its tracking tags and click history.” “Show clicks for my [client] links.” ## Tools and limits - get_workspace: current workspace, Instant namespace and UTM presets. - list_clients, list_domains: find existing clients and ready domains. - list_links, get_link: links, targets, exact update revisions and recorded click counts. - create_link: Instant by default, or an existing live domain; readable path and utm_source required. - update_link: patch fields while retaining the link ID, omitted UTM tags and all clicks. Pass the exact latest expected_revision. Empty optional tags remove them. Changing the path stops the old URL. Create the client in the app first. If no Instant namespace exists, agree on the permanent workspace name before creating the first link. Tools do not delete data, configure DNS, install Workers or expose keys. Domain setup stays in the app/help guide. Listing is paginated with limit (1–50) and after / next_after. Repeating an identical create returns the existing link; a different link at that path is never overwritten. Re-read after a concurrent-update error. The connection is fixed to the workspace selected at consent, even if you later switch workspaces in the browser. Each request checks the authorizing user’s current membership. Disconnect in Settings → Agents to revoke access immediately. Access tokens expire after an hour; refresh tokens rotate and expire after 30 days without use. Removing a connector in your AI client may not revoke the server grant, so use Pretty UTMs to disconnect it. Counts are visits, not unique visitors or GA4 sessions. A normal test click changes the count; use HEAD to check a redirect without recording a visit. ## Connection troubleshooting Use the full /api/mcp URL, choose Register automatically in Claude, and finish sign-in/consent. If authorization expired or your workspace membership changed, reconnect. If a workspace is missing, join it in Pretty UTMs first. For Cloudflare setup use https://prettyutms.com/help/setup.md. Official client references: - https://developers.openai.com/codex/mcp - https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp ## Official Cloudflare reference - [Cloudflare DNS proxy status](https://developers.cloudflare.com/dns/proxy-status/) - [Cloudflare Worker routes](https://developers.cloudflare.com/workers/configuration/routing/routes/) - [Cloudflare hostname validation](https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/domain-support/hostname-validation/)