This server lets you publish HTML documents as tracked HTMLRadar links, manage those links, and read recipient engagement data.
Publish HTML as a tracked recipient link (share_html), with optional custom slug, title, password, email requirement, lock-deck, expiry, and allowed email domains.
Create additional tracked links for existing documents with per-recipient labels and gates (create_share).
List tracked links, newest first, including opened status, labels, titles, ids, and paging (list_shares).
Check who read a link: per-viewer reading time, scroll depth, top sections, and optional location/device/referrer detail (get_share_activity).
Revoke or re-enable a link without deleting history; attempts notify the sender (revoke_share).
Replace a document's HTML while keeping every link and the reading history (replace_document).
Show the account plan and remaining free tracked links (whoami).
Read tracking for the decks, reports and proposals you now send as HTML.
HTMLRadar is an open-source tool for sharing an HTML deck, brief, or proposal as a tracked link, and seeing who opened it, which sections they read, and for how long. Not just that it was opened — dwell time, section by section. You know who a reader is when the share's email gate collected an address; otherwise the reader is an anonymous row with the same reading detail.
htmlradar.com · free for 2 tracked links, $15/mo or $150/yr for unlimited, $20 per person a month for a team of five or more · or self-host the whole thing.
Try the public demo, no sign-up — a live tracked link you can open in a browser.
Using Claude? Add HTMLRadar as a connector by pasting one address —
https://mcp.htmlradar.com/mcp. Nothing to install and no API key to make first;
how it works.
Issues and PRs · roadmap · changelog documents v1.2; latest published tag is v1.1.2.
Walkthrough uses synthetic sample data in the real sender dashboard.
The documents that matter — decks, client reports, proposals, board updates — are becoming HTML, because an HTML page can be interactive, reflows to whatever screen opens it, and can be changed after it has been sent. A PDF you have sent is fixed. More of them are written with AI tools now, and ChatGPT, Claude, v0, Lovable and Anthropic Artifacts all produce HTML. The format is what makes these documents better; who typed them is beside the point.
The tracking tooling never followed. When I went looking, I could not find an open-source tool that reported reading at section level for an HTML document. The document-tracking products I did find grew up around uploading a file and tracking that file.
HTMLRadar tracks the document people actually send now, and reports reading at section level rather than a single "opened" flag.
Related MCP server: Artifacts
Send-side analytics for HTML documents. Upload an HTML file (or paste a URL you already host), send a tracked link htmlradar.page/r/{slug}, see who opened it, which sections they dwelled on, and when they bounced. Section-level dwell, not "opened."
Starting from a PDF instead? htmlradar.com/convert turns a landscape PDF deck — 2 to 60 pages, up to 30 MB — into one HTML page in the browser, with each slide as an image and a heading per slide. The download is free and needs no account; sign in to share the result as a tracked link.
Section-level dwell. At least half a section must stay visible for one continuous second before its dwell starts qualifying; the read signal fires after three qualified seconds. The tracker auto-detects sections from your HTML: explicit anchored headings → bare h1/h2/h3 (slugged from text) → slide/page containers (section, .slide, .page) → paragraph buckets on plain prose. Dashboard tells you a recipient spent 2m 41s on §03 The Ask, 12s on Problem, and skipped Market sizing.
Per-viewer dashboard, aggregated across every share. One row per person who actually opened the doc, with email + country + device + referrer + total time + scroll depth + visits + first/last seen. Updates live every 30 seconds while the tab is in focus.
Per-recipient share links. One document, many shares. Each share carries its own email gate, password, expiry, revocation, and email-domain or per-email allow-list.
Files alongside the deck. Attach PDFs, financial models, images, and ZIPs to any share. Recipients see a small corner pill that opens a side drawer; files are always available when present (the per-share "Lock the deck" toggle controls deck save/print only, never attachments). Every download is logged per session and per filename, and tied to the viewer record when one exists.
Version history. Replace the HTML after partner feedback. Every existing share keeps the same link and serves the new version on next open. The v{n} chip on the doc page is a popover with every upload's original local filename, byte size, and timestamp.
Retroactive share access. Change a share's password, expiry, or allow-list without revoking. The proxy re-checks the allow-list on every request — removing an email kicks them out immediately on their next click, not their next browser session.
Edit + preview without leaving the dashboard. Preview the doc as the recipient sees it before sending (short-lived HMAC token, no gate). Both "Preview document" and "Preview as you" open in a new tab so your dashboard stays where you left it.
Branded first-open email. When a recipient creates their first real session, HTMLRadar requests an HTML notification — viewer email + doc title + a single "See the read →" CTA back to the dashboard. Tease, not report.
Estimated reading time, not tab-open time. Time counts while the document is visible and the reader has shown a sign of presence — a key, a click, a touch, a wheel notch, a mouse movement — within the last 30 seconds. People read a deck with their hands still, so the allowance is generous; a tab parked while the reader walked away stops counting 30 seconds later. Only genuine human input renews it: events created by a script, a playing video and a carousel that advances itself do not. Scrolling tells us where the reader is, not that they are there. Section dwell is spent out of that same clock, so section times can never add up to more than the session's. We cannot confirm attention, and we do not claim to.
Bot / accidental-tap filter. After the document loads, HTMLRadar waits through a 5-second warm-up before creating the session. If the recipient backgrounds the tab or bounces during that wait, there is no session, notification request, or inflated viewer count.
Data collected. A recipient record holds an email address when a share's gate collects one, otherwise a random identifier (on documents HTMLRadar serves, a __Host-hr_rid cookie that lasts 90 days and that page scripts cannot read, with the page given only a per-document value derived from it; in localStorage when the tracker is embedded directly); first-seen and last-seen times; visit count; the browser identification string; referrer; country and city; device type; operating system; browser. A session record holds the document version seen, start and last-heartbeat times, active seconds, and maximum scroll depth. A section record holds dwell per section. These records are kept until the owner deletes them, or for the retention period the owner chooses in Settings (forever, 1 year, 90 days or 30 days), enforced by a daily sweep. Not stored in recipient records: raw IP address, cursor positions, keystrokes, page snapshots, session replay. An ungated document shows no tracking notice; the email-gate page shows one sentence ("Reading activity on this document is shared with the sender") and a link to the privacy page. Opt-out is a developer-console call, window.HTMLRadar.optOut(), followed by a confirmation page — documented, but not something an ordinary recipient will discover. Audit for comparison: what each of seven tools loads in a recipient's browser, HTMLRadar included.
A sender-side analytics tool for one document at a time. Not a CMS, deck builder, static-site host, PDF viewer, or website analytics platform. You bring the HTML.
Six packages, two storage backends. Three of the six are Cloudflare Workers, one is the Next.js app on Cloudflare Pages, and two are libraries that ship as bundles.
htmlradar/
├── packages/
│ ├── tracker/ # 8.5 KB gzipped browser IIFE — embedded in the recipient's view
│ ├── proxy/ # Cloudflare Worker at htmlradar.page/r/{slug} — gates + HTML fetch + tracker inject + attachment serving
│ ├── app/ # Next.js 14 on Cloudflare Pages — sender's dashboard
│ ├── monitor/ # Cloudflare cron Worker — checks Supabase every 5 min, alerts the operator on regressions and runs the scheduled jobs
│ ├── connector/ # Cloudflare Worker at mcp.htmlradar.com — the remote MCP server, so Claude can be connected by pasting one address
│ └── mcp/ # stdio MCP server on npm — lets an agent publish HTML and read back who opened it
├── schema/ # Ordered idempotent SQL migrations — tables, RLS, SECURITY DEFINER RPCs, triggers
├── examples/ # Demo HTML for trying it locally
└── docs/ # Architecture, privacy, quickstart, self-hostingDocument HTML + attachment bytes live in Cloudflare R2. Everything else (sessions, sections, viewers, shares, attachments metadata, version history) lives in Supabase Postgres.
Recipient links live on a second domain, htmlradar.page, while the dashboard and the marketing site stay on htmlradar.com. A recipient document is HTML somebody else wrote, and serving it on the application's own domain would put a stranger's markup on the same origin as a signed-in session, and would let anyone who uploaded a convincing fake sign-in page have it served under our certificate and our reputation. A separate registrable domain removes both problems at once: the document's origin carries no application cookies, and if the content domain ever ends up on a phishing blocklist, the application domain does not. Links sent before the split still work — the worker answers htmlradar.com/r/… with a permanent redirect. Self-hosters choose their own two hosts, or run both roles on one; see docs/self-hosting.md.
The architecture decisions — why a Cloudflare Worker proxy, why hand-rolled PostgREST instead of @supabase/supabase-js, why per-session bearer tokens instead of HMAC, the engagement-time methodology, the retroactive allow-list — are in docs/architecture.md.
Frontend: Next.js 14 (App Router, Server Components), Tailwind CSS, Newsreader + Geist (self-hosted via next/font)
Backend: Supabase Postgres — RLS + SECURITY DEFINER RPCs + pg_net triggers for email
Proxy: Cloudflare Worker, HTMLRewriter for tracker injection
Remote MCP connector: Cloudflare Worker on mcp.htmlradar.com, OAuth on top of ordinary API keys, one KV namespace for grants and tokens
Storage: Cloudflare R2 for uploaded HTML
Auth: Supabase Auth (Google OAuth + magic-link)
Email: Resend, invoked from Postgres via pg_net
Payments: Polar.sh — checkout, subscriptions and seat-based team billing, applied by a webhook
Core hosting runs on Cloudflare and Supabase. Resend is optional for notification email, and Polar handles billing for the hosted Pro and Team plans.
Sign in at htmlradar.com with Google or magic link.
Upload an HTML file or paste a URL.
Create a per-recipient share. Email gate / password / expiry / allow-list optional per share.
Send the tracked link.
Watch the dashboard. HTMLRadar requests a first-read email when the recipient creates their first real session.
Free tier: 2 tracked links lifetime across unlimited documents, 20 attachments per doc up to 25 MB each and 100 MB total per doc. Pro tier ($15/month, or $150/year — two months free): unlimited tracked links, your own link names (htmlradar.page/r/acme-proposal rather than a generated one), no "Powered by HTMLRadar" footer on the recipient view, and your own domain on share URLs (decks.acme.com/r/acme-proposal rather than htmlradar.page — one CNAME record, no extra charge; see custom domains). Team plan ($20 per person a month, minimum 5 people, self-serve at htmlradar.com/pricing): everything in Pro for each person, plus an admin who sees every colleague's documents, links and reading records, and keeps a leaver's documents visible. Coming soon on Pro: dynamic per-viewer watermark, repeat-open alerts. What's next is on the public roadmap.
You'll need:
A Cloudflare account (Workers + R2 + Pages)
A Supabase project (free tier is enough)
A domain on Cloudflare DNS
Node ≥22.13, PNPM ≥10
A Resend account for outbound email (optional — without it, the first-read trigger writes a skipped row to notifications_log and the rest of the product still works)
Then:
git clone https://github.com/htmlradar/htmlradar
cd htmlradar
pnpm install
cp .env.example .env.local # then fill it in, see the note below
pnpm typecheck && pnpm test # sanity check
pnpm build # builds app, tracker and mcp — the three packages that have a build scriptpnpm build needs two variables filled in before it will finish. Copying .env.example is not
enough on its own: several marketing pages are pre-rendered at build time and they create a Supabase
client while doing it, so NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_ANON_KEY have to hold
real values in .env.local first. Leave them blank and the build stops on /, /pricing,
/privacy, /terms and /why with Your project's URL and Key are required to create a Supabase client!, which does not say which file it wanted. Everything else in .env.example can wait until
you deploy.
Schema setup: apply every numbered SQL file directly under schema/, in order, via the Supabase SQL
editor — and nothing in schema/tests/. There is no last file to stop at; the folder grows, so apply
whatever is in it, from 001 upwards, and add each new one as you pull it. The files in
schema/tests/ are destructive test programs for a scratch database (they create auth users and
sample rows) and must never run against a real install. Each migration is idempotent
(CREATE TABLE IF NOT EXISTS, CREATE OR REPLACE FUNCTION, DO $$ ... IF NOT EXISTS ... $$), so
re-running any of them is safe, and so is re-running the whole chain.
Two Postgres extensions have to be available, and both are on every Supabase tier: pgcrypto, for
gen_random_uuid and the hashing the schema does, and pg_net, for the asynchronous HTTP call the
notification triggers make. 001_init.sql creates both itself. A third, pg_cron, is optional:
migrations 044 and 045 use it to schedule the notification reconciler and the expired-handle
sweep, and where it is missing they log a notice, skip the scheduling and carry on, leaving both
functions callable by hand or by any scheduler you already run.
Every migration opens with a header saying what it does and whether anything must happen before or after it. schema/README.md summarises the tables and functions they create, and CHANGELOG.md lists which migrations each release needs.
One migration wants editing before you run it: 032_comped_accounts.sql carries a placeholder list
of internal addresses that are never billed. Put your own addresses in it, or none.
Resend secrets go in Supabase Vault (works on free tier — no ALTER DATABASE SET required):
select vault.create_secret('re_your_resend_api_key', 'resend_api_key');
select vault.create_secret('hello@yourdomain.com', 'resend_from');Full guide with deployment commands in docs/self-hosting.md.
HTMLRadar ships an MCP server, so the agent that wrote the HTML can publish it as a tracked link — and ask, the next day, whether anyone read it.
Claude Desktop and claude.ai — one address, no install
Settings → Connectors → Add custom connector, and paste:
https://mcp.htmlradar.com/mcpNothing to install and no API key to make first. The first time Claude reaches for a tool it shows a Connect card; you sign in to HTMLRadar, choose read-only or read-and-publish, and the key is minted for that connection. Revoke it any time under Connected apps in Settings — access ends on the next tool call.
Every other client — run the package
Create an API key at htmlradar.com/settings under API keys — the same key also calls the HTTP API directly, if you would rather script it than run an agent — then export it, so the key never becomes a command-line argument that lands in your shell history:
export HTMLRADAR_API_KEY=hr_live_xxxClaude Code
claude mcp add htmlradar -e HTMLRADAR_API_KEY=$HTMLRADAR_API_KEY -- npx -y htmlradar-mcpOr install the plugin, which wires up the same server and adds a skill that knows when to offer a tracked link and when to stay quiet:
/plugin marketplace add htmlradar/htmlradar
/plugin install htmlradar@htmlradarCursor — put this in .cursor/mcp.json in your project, or ~/.cursor/mcp.json to make it
global. Cursor expands ${env:NAME} inside env, which keeps the key out of a file you might
commit:
{
"mcpServers": {
"htmlradar": {
"command": "npx",
"args": ["-y", "htmlradar-mcp"],
"env": { "HTMLRADAR_API_KEY": "${env:HTMLRADAR_API_KEY}" }
}
}
}There is a one-click Add to Cursor button on htmlradar.com/mcp. It installs the server with a placeholder key, which you then replace with your own.
Codex CLI
codex mcp add htmlradar --env HTMLRADAR_API_KEY=$HTMLRADAR_API_KEY -- npx -y htmlradar-mcpEight tools: whoami, list_shares, list_documents and get_share_activity read; share_html,
create_share, replace_document and revoke_share write. Every option, the self-hosting variable
and the privacy notes are in packages/mcp/README.md. The connector at
mcp.htmlradar.com serves the same eight, imported from this package rather than copied — see
packages/connector/README.md.
If you modify the source and run a network service from it, AGPL-3.0 requires you to make your modifications available. See LICENSE.
pnpm dev # runs app, monitor, proxy, connector, tracker in parallel (mcp has no dev script)
pnpm typecheck # tsc --noEmit across all six packages
pnpm lint # eslint + prettier
pnpm test # vitest across app, mcp, monitor, proxy, connector, trackerLocal URLs after pnpm dev:
Web app: http://localhost:3000
Proxy worker: http://localhost:8787
Tracker bundle: packages/tracker/dist/tracker.js (after pnpm --filter @htmlradar/tracker build)
Tracker bundle size budget: ≤14 KB gzipped. Build will warn if you cross it.
Embedding the tracker by hand in your own page? Use the fixed address, /v1/tracker.js. It serves
the current script and always will, on a five-minute cache lifetime. Documents HTMLRadar serves are
pointed at a versioned address instead (/v1/tracker.<hash>.js, the hash being the bundle's own),
so that a cache between us and the reader can never answer a freshly served page with a stale
script — see docs/self-hosting.md.
PRs welcome. DCO sign-off is required — just git commit -s. No CLA.
Big features: open an issue first to discuss scope.
Bug fixes + small improvements: PR directly.
Style is enforced by pnpm lint. CI runs the full suite on every push.
See CONTRIBUTING.md for the full guide.
Found a vulnerability? Email security@htmlradar.com. Please don't open a public issue. See SECURITY.md for the disclosure policy.
AGPL-3.0-or-later. See LICENSE.
Want to run a hosted service from a closed-source modified version, or embed the tracker in a closed-source product? A commercial license is available — see COMMERCIAL-LICENSE.md, or email hello@htmlradar.com.
Engineering deep-dive: htmlradar.com/blog/how-we-built-htmlradar
Replaces the contents of a document already on HTMLRadar. Every existing link stays exactly as it is — same address, same settings, same reading history — and serves the new contents from the next time it is opened, so nobody is sent a second link. The new HTML is screened for phishing signals as every upload is, and the previous version is kept in the document's history. Recipients may already have read the old contents, and there is no partial update: the markup supplied replaces the document.
| Name | Required | Description | Default |
|---|---|---|---|
| html | Yes | The new HTML markup, in full. It replaces the document; there is no partial update. | |
| document_id | Yes | The document whose contents are being replaced. Every link to it keeps working. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds meaningful behavioral context: links and reading history remain intact, new content is served on next open (so no second link is sent), the upload is screened for phishing, the previous version is kept in history, and there is no partial update. These details exceed what annotations alone provide and accurately reflect the destructive nature of the operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, each serving a distinct purpose: core action and link preservation, security screening and history, and the no-partial-update caveat. It is well-structured, front-loads the primary behavior, and avoids redundancy with the schema. A slightly tighter phrasing might earn a 5, but the current length is justified by the important behavioral nuances.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a two-parameter tool with no output schema, the description covers the essential outcomes: content replacement, link stability, phishing screening, history retention, and the lack of partial updates. It does not mention error conditions or idempotency, but annotations already convey idempotentHint=false. The description is sufficiently complete for an agent to call the tool correctly without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are already documented. The description reinforces the semantics (e.g., html is a full replacement, document_id retains links) but does not introduce new information beyond the schema. Since the schema does the heavy lifting, a baseline score of 3 is appropriate; the description adds minimal extra meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Replaces the contents of a document already on HTMLRadar.' It clearly distinguishes the tool's purpose from the sibling tools (which are all share-related) and states the key differentiator: links are preserved. No ambiguity remains about what action this tool performs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly guides usage by stating it targets existing documents ('already on HTMLRadar') and emphasizes the link-preserving behavior. It does not explicitly name alternative tools for creation or sharing, but given the sibling list contains no other document-manipulation tools, the context is sufficient. A clear when-to-use is implied but not spelled out as an exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reports the plan the HTMLRadar API key's account is on and how many of its free tracked links remain. It returns no account identifier and no email address.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is consistent with the readOnlyHint annotation, using 'Reports' to indicate a non-mutating operation. It also proactively notes the absence of identity data, providing transparency beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two clear, compact sentences convey all required information without redundancy. The structure is front-loaded with the primary purpose and includes a helpful explicit exclusion.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately describes the return content (plan and free links left) and explicitly states what is not included. This fully covers the necessary context for a simple read-only tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, so the description adds no parameter-specific meaning. The baseline of 4 applies since there are no parameters to document.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the specific verb 'Reports' and the resource: the account's plan and remaining free tracked links. It distinguishes itself from sibling tools focused on share management by focusing on account-level information.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states what the tool does and, more importantly, what it does not return ('no account identifier and no email address'), setting clear expectations for when not to use it. Sibling tools provide alternative context, making the use case evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.3.1create_shareget_share_activitylist_sharesreplace_documentrevoke_shareshare_htmlwhoamiScored across 7 tools
Most tools are distinct, but 'share_html' and 'create_share' both create tracked links and could be confused by an agent, especially since one is initial and one is additional. 'revoke_share' also has toggle semantics ('revoked: false' switches it back on) that the name does not clearly convey.
The naming pattern is mostly consistent lowercase snake_case verb_noun, e.g. list_shares, get_share_activity, replace_document. The exceptions are 'whoami' and the slightly inconsistent pairing of 'share_html' vs 'create_share'.
Seven tools is well-scoped for this domain, covering account info, initial sharing, additional shares, listing, activity, revocation, and document replacement without being overwhelming.
The surface covers create, read, update, and soft-disable operations, but there is no permanent delete for shares or documents, and no way to update share settings like recipient label, password, or expiry. This leaves notable lifecycle gaps.
Track agent ROI and enrich companies via MCP. Remote, OAuth 2.1, no install or keys.
Publish and manage HTML pages in your agents-first Outbox library from any MCP client.
One wiki for all your agents: pages read and written over MCP, a link graph, and broken-link checks.
Publish HTML, files, or a URL to a permanent public URL, then update it — from any MCP agent.
