MCP server

Quick start

OAuth-capable clients (claude.ai, Claude Desktop, Claude Code, ChatGPT) need no API key and no paid plan: you sign in with your HTMLvault account when the client prompts you, on Free exactly as on a paid plan. For everything else, generate an API key (Pro, Teams or Enterprise) on the Settings → API keys screen and replace hv_YOUR_KEY in the snippets below.

claude.ai & Claude Desktop (OAuth, recommended)

In Settings → Connectors → Add custom connector, paste the endpoint URL, then click Connect and sign in. No terminal, no config file, no key.

https://htmlvault.com/api/mcp

Claude Code

Run once in your terminal. You’ll be prompted to sign in on first use, and HTMLvault is then available in every Claude Code session. Prefer a static key (e.g. CI)? Append --header "Authorization: Bearer hv_YOUR_KEY".

claude mcp add --transport http htmlvault https://htmlvault.com/api/mcp

Claude Desktop: static-key bridge (advanced)

Only needed if you’d rather authenticate with an API key than OAuth: use the mcp-remote bridge in claude_desktop_config.json:

{
  "mcpServers": {
    "htmlvault": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://htmlvault.com/api/mcp",
               "--header", "Authorization: Bearer hv_YOUR_KEY"]
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json (or the project-level .cursor/mcp.json):

{
  "mcpServers": {
    "htmlvault": {
      "url": "https://htmlvault.com/api/mcp",
      "headers": { "Authorization": "Bearer hv_YOUR_KEY" }
    }
  }
}

Anthropic API (MCP connector)

Pass the endpoint in the mcp_servers array of a Messages API request (requires the MCP connector beta header):

{
  "model": "claude-sonnet-4-6",
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://htmlvault.com/api/mcp",
      "name": "htmlvault",
      "authorization_token": "hv_YOUR_KEY"
    }
  ],
  "messages": [{ "role": "user", "content": "Vault this report and give me the link." }]
}

ChatGPT

ChatGPT (Plus/Pro/Team and up) connects over MCP: enable Developer Mode (Settings → Apps & Connectors → Advanced), add a custom connector pointing at the endpoint above, and sign in when prompted. Alternatively, a Custom GPT Action over the REST API works without Developer Mode. The import-ready OpenAPI schema and step-by-step setup live on the Settings → MCP screen.

Authentication

Every request carries a bearer token in the Authorization header, in one of two modes. OAuth 2.1: connector-style clients discover the authorization server via the RFC 9728 metadata at /.well-known/oauth-protected-resource/api/mcp and run a standard sign-in flow; access tokens are short-lived and refresh automatically. Static API keys: created and revoked on the Settings → API keys screen, shown once at generation time; the right choice for CI and server-side callers.

Authorization: Bearer hv_YOUR_KEY

Personal vs. org keys

OAuth sign-in works on every plan, Free included. Personal API keys require Pro, Teams or Enterprise. Either credential always acts as you, the signed-in user or key owner.

Org keys (Enterprise, created by an admin with api_keys.manage_org) instead act on behalf of the organization owner: every tool call is attributed to the owner’s account. Meant for server-to-server integrations with no logged-in user.

Either way, by default you only see your own (or, for an org key, the owner’s own) links. Pass scope: "all" on list_links, get_link, get_analytics, update_link, patch_link, or delete_link to widen to every org member’s links instead. This requires your role to hold the matching permission (links.view_any, links.edit_any, links.delete_any, or analytics.view_any); omitting scope falls back to your stored preference on Settings → Link defaults (default me). A role without the permission gets an explicit error, never a silent narrowing.

Auth errors

The 401 cases share a shape ({ "error": "...", "message": "..." }); the key-on-Free case is a distinct 403 so a client can tell “wrong key” from “upgrade needed.”

Plans & limits

The server itself is not gated. A Free account can add the connector, sign in and start publishing; what differs is the credential it can use and which tools answer. OAuth sign-in is available on every plan. Static API keys need Pro, Teams or Enterprise, so a Free account connects through a connector-style client (claude.ai, Claude Desktop, Claude Code, ChatGPT) rather than through a config file with a key in it.

Publishing limits are the same ones the web upload form applies, deliberately: a link created by an agent counts against the same monthly allowance as one created in the browser.

What a Free caller runs into

• Monthly cap. The 51st create_link in a calendar month returns link_limit_reached, and nothing is created. Append-mode drafts are charged at the same counter, but only on the append_html call that finalizes, so a draft you cannot finalize yet is still there to retry, until its 24-hour window runs out.
• Expiry ceiling. An expiresIn past 30 days (including never) is capped at 30 days rather than rejected, so the call succeeds with a nearer expiry than asked for. A draft takes no expiresIn at all: the 30 days are counted from create_draft_link, not from the finalize that published it.
• No custom domain. The domain parameter names an active custom domain, which is a paid feature, so on Free it returns unknown_domain. Links serve from the default share domain.
• Preview image stored, not shown. An og:image meta tag in the submitted HTML is parsed and stored on any plan, so preview_image echoes back the URL, but preview_image_active is false until the account is on a paid plan. It starts displaying on its own once the plan changes, with no republish needed either way.

Nothing about a Free connection is downgraded silently apart from the expiry cap. Every other limit surfaces as an explicit error naming the plan, so an agent can report it rather than guess. Plan is re-resolved on every request, so an upgrade takes effect on the next tool call, with no reconnect and no new token.

Tool reference

Twelve tools, ten of them available on Free (see Plans & limits). Read-only tools (list_links, get_link, get_analytics, scan_html) are annotated readOnlyHint: true; delete_link is annotated destructiveHint: true. Every tool returns its JSON result inside the MCP content envelope as a text block, and (for clients that read structured output) as structuredContent validated against the tool’s declared outputSchema.

Four of them publish content: create_link (one document), create_links (up to 100 from one template), update_link (replace a document), and patch_link (change parts of a document). Pick the narrowest one that fits: an agent that re-sends a whole document to change a heading, or calls create_link in a loop, pays for every byte twice. A fifth path publishes across several calls rather than one: create_draft_link plus append_html assemble a large document server-side, chunk by chunk, and publish it on the final call.

scan_report

Those four publishing tools accept an optional scan_report parameter controlling how much PII-scan detail comes back on success. It is a response-verbosity switch only: it never changes what is scanned, gated, or blocked.

Under scan_report: "none" the key is absent, not empty. On create_links, a present-and-empty rows_with_warnings means the batch ran and no row warned, while an absent one means reporting was suppressed. A blocked publish always returns its findings regardless of this parameter: scan_report can hide warnings, never the reason a publish was refused. append_html takes no scan_report: a finalize that publishes with non-blocking warnings always returns them.

list_links

List your links, newest first, with cursor pagination.

{
  "links": [
    {
      "slug": "a1b2c3d4e5f6g7h8",
      "title": "Q3 Proposal",
      "created_at": "2026-06-10T18:22:04.511Z",
      "expires_at": null,
      "view_count": 42,
      "is_public": true,
      "url": "https://htmlvault.io/a1b2c3d4e5f6g7h8"
    }
  ],
  "next_cursor": "MjAyNi0wNi0xMFQxODoyMjowNC41MTFafGExYjJjM2Q0",
  "has_more": true,
  "viewer_timezone": "America/Denver"
}

When has_more is true, call again with cursor set to next_cursor. When it is false, next_cursor is null and you have the last page. All timestamps are UTC; viewer_timezone is the IANA zone from the caller’s account settings (null if unset) so an agent can convert before showing a time to a person.

get_link

Fetch one link’s metadata and full stored HTML.

{
  "slug": "a1b2c3d4e5f6g7h8",
  "title": "Q3 Proposal",
  "html_content": "<!doctype html>…",
  "created_at": "2026-06-10T18:22:04.511Z",
  "expires_at": null,
  "view_count": 42,
  "is_public": true,
  "url": "https://htmlvault.io/a1b2c3d4e5f6g7h8",
  "viewer_timezone": "America/Denver"
}

Returns an error starting Link not found: if the slug is not owned by the caller (and scope wasn’t widened to all). The rest of it names the account that was searched, by its email address, and the slug, so a link created under a different HTMLvault account reads as exactly that. Every tool that takes a slug answers a miss the same way. Timestamps and viewer_timezone work the same as in list_links above.

get_analytics

View metrics for one link: totals, engagement, and breakdowns.

{
  "slug": "a1b2c3d4e5f6g7h8",
  "period": "30d",
  "totals": { "views": 318, "unique_views": 204, "repeat_views": 114, "bot_views": 27 },
  "engagement": { "avg_time_on_page_seconds": 47, "avg_scroll_depth_pct": 68 },
  "breakdowns": {
    "countries": [{ "value": "United States", "views": 190 }],
    "devices":   [{ "value": "desktop", "views": 240 }],
    "channels":  [{ "value": "clay-icp-ceos", "views": 35 }],
    "referrers": [{ "value": "https://mail.google.com/", "views": 60 }]
  }
}

Automated traffic is excluded from views, engagement, and every breakdown; bot hits are counted separately as bot_views so the number is visible without polluting the human totals. Metric definitions match the dashboard exactly. Returns an error starting Link not found:, naming the account searched and the slug, if the slug is not owned by the caller.

create_link

Publish HTML as a secure, shareable link. Every external link in it is checked against Google Web Risk, and the content against your account’s PII scan policy, before it goes live. Available on every plan: Free publishes up to 50 links a month with expiry capped at 30 days, paid plans are unlimited with any expiry. The link check only knows sites Google already flags, so it is not a guarantee: some unsafe sites may be missed, and some safe ones flagged in error.

{
  "slug": "k9m2p4q7r1s8t3v6",
  "url": "https://htmlvault.io/k9m2p4q7r1s8t3v6",
  "title": "Q3 Proposal"
}

If your account’s PII policy is set to warn (rather than block), the link still publishes and the response includes a warnings array describing the categories found. See Errors for the block cases. A successful MCP create_link fires the link.created webhook.

create_draft_link

Start an empty draft and get its slug: step one of append-mode publishing, for a document you intend to build up across several append_html calls instead of sending it in one. Nothing is checked, charged, or served yet: no publish gates run, a Free account’s monthly link allowance is untouched, the slug 404s publicly, and the draft is excluded from list_links. Available on every plan. Use it when a document is big enough that losing one 5 MB create_link call mid-transmit would hurt; for anything that fits comfortably in a single call, plain create_link is one round trip instead of several.

{
  "slug": "k9m2p4q7r1s8t3v6",
  "draft_expires_at": "2026-08-18T18:22:04.511Z"
}

A draft lives as long as your account’s data-retention window, with a floor of 24 hours (90 days on the default setting, and the org owner’s window for an Enterprise member). (auto_delete resolves to the 24-hour floor rather than to zero, or a draft would be swept out from under the appends building it.) draft_expires_at is that deadline, not the published link’s expiry. A draft still unfinalized when it passes is deleted outright by the daily retention sweep, content and all. Mid-build you can read it with get_link, which returns the accumulated HTML alongside is_draft: true and the same draft_expires_at. The draft tools take no expiresIn: once finalized, the link takes your account’s default expiry on Pro, Teams and Enterprise (accounts created since October 2026 start with 1 year; change it under Settings, Link defaults), and on Free it expires 30 days after it is published. Either way the clock starts at finalize, not here, so however long you spend assembling the document costs nothing against it.

append_html

Append a chunk to a draft’s stored HTML. The server does the concatenation, so content already sent is never re-transmitted. Call it as many times as the document needs, then once more with finalize: true. That last call is what checks and publishes. Available on every plan.

{
  "slug": "k9m2p4q7r1s8t3v6",
  "content_length": 412800,
  "content_hash": "9f2c1a…",
  "finalized": false
}

{
  "slug": "k9m2p4q7r1s8t3v6",
  "url": "https://htmlvault.io/k9m2p4q7r1s8t3v6",
  "title": "Q3 Proposal",
  "content_length": 498211,
  "content_hash": "4b7e02…",
  "changed": false,
  "transformations": [],
  "finalized": true
}

Every call reports content_length and content_hash (SHA-256) of the draft’s full accumulated content, not of the chunk, so an agent can confirm each piece landed before sending the next. Between calls the draft is allowed to be incomplete and not well-formed: a half-open <table> at a chunk boundary is normal and is not an error.

Nothing is gated until finalize. The finalize: true call runs the same tail create_link runs, against the whole assembled document: well-formedness, publish-time normalization, your account’s PII policy, and the Google Web Risk link check. Only after those pass does it charge a Free account’s monthly link slot, so a blocked publish never burns one. On success the draft state is cleared, the slug goes live, and the link.created webhook fires (the first and only link.created for that slug).

Append-specific rejections: chunk_too_large (over 200 KB), draft_too_large (this chunk would pass 5 MB), not_a_draft (the slug is already finalized: edit it with update_link or patch_link instead), and draft_expired (past the 24-hour window; start a new draft). None of them append anything. If the PII policy is set to warn rather than block, finalize publishes and adds a warnings array, exactly as create_link does; see Errors for the block cases.

create_links

Publish up to 100 links in one call from a single HTML template plus per-row variable substitution: the efficient way to produce many distinct pages (a personalized report per customer, a per-account one-pager) without re-sending the document each time. Paid plans only (Pro, Teams, Enterprise). For many tracked URLs of the same unchanged page, use create_recipient_links instead.

{
  "template_html": "<!doctype html><h1>{{customer}} — {{quarter}} review</h1>…",
  "links": [
    { "title": "Acme — Q3",   "vars": { "customer": "Acme Corp",  "quarter": "Q3" } },
    { "title": "Globex — Q3", "vars": { "customer": "Globex Inc", "quarter": "Q3" } }
  ]
}

{
  "created": [
    { "slug": "k9m2p4q7r1s8t3v6", "url": "https://htmlvault.io/k9m2p4q7r1s8t3v6", "title": "Acme — Q3" },
    { "slug": "b4n7x2c9d1e5f8g3", "url": "https://htmlvault.io/b4n7x2c9d1e5f8g3", "title": "Globex — Q3" }
  ],
  "count": 2,
  "rows_with_warnings": [1]
}

created is in the same order as the input rows. rows_with_warnings holds the zero-based indices of rows that published with non-blocking PII warnings (omitted under scan_report: "none").

Substitution rules. A {{token}} with no matching var in a row passes through untouched: templates containing Vue or Handlebars syntax are safe. The reverse is an error: a var with no matching token fails its row with unknown_var, so a typo like {{first_name}} vs firstName is caught instead of quietly publishing a page missing its personalization. Substituted values are never re-scanned for placeholders, so one row’s value cannot expand into another row’s token.

The gates run batched, not weakened: one Google Web Risk check covers the union of every row’s external URLs, each URL checked once however many rows link it, while the PII policy is evaluated per substituted document at full fidelity. Each created link fires its own link.created webhook. Batch creation draws on a per-account budget of 1,000 links per minute, counted in links rather than calls (see Limits & errors).

update_link

Replace the HTML of an existing link in place: the slug and public URL are unchanged, so a link you have already shared updates live. Re-runs the same Google Web Risk and PII policy gates as publishing, on every plan. For anything short of a full rewrite, prefer patch_link. It sends only the changed parts.

{
  "slug": "k9m2p4q7r1s8t3v6",
  "url": "https://htmlvault.io/k9m2p4q7r1s8t3v6",
  "updated_at": "2026-06-13T15:04:11.882Z"
}

Returns an error starting Link not found or not owned:, naming the account searched and the slug, if the slug isn’t yours (and scope wasn’t widened to all). Fires the link.updated webhook on success, against the link’s actual owner.

patch_link

Edit a published link by sending only the changed parts. Each patch replaces an exact substring of the stored HTML (the same find/replace semantics as an editor, or Claude Code’s Edit tool). Deliberately no regex: exact matching is the only contract an agent can reason about reliably. Same publish gates as update_link.

In the default unique mode, without replace_all, the find string must occur exactly once. Include enough surrounding context to make it unique. The whole batch is all-or-nothing: the first failing patch aborts the call and nothing is persisted.

{
  "slug": "k9m2p4q7r1s8t3v6",
  "patches": [
    { "find": "<h1>Q3 Proposal</h1>", "replace": "<h1>Q4 Proposal</h1>" },
    { "find": "Draft — do not circulate", "replace": "", "replace_all": true }
  ]
}

{
  "slug": "k9m2p4q7r1s8t3v6",
  "url": "https://htmlvault.io/k9m2p4q7r1s8t3v6",
  "updated_at": "2026-07-24T15:04:11.882Z",
  "patches_applied": 2,
  "replacements": 4
}

patches_applied counts the patches; replacements counts the substrings actually replaced across all of them (higher when replace_all matched more than once).

Two situations defeat uniqueness however much context you include, and both call for mode: "positional". Rebuilt, minified output, where identifier mangling makes short strings recur by construction. And several structurally identical blocks (repeated cards or rows), where a find string that was unique against the original document turns ambiguous mid-call, once an earlier patch has changed one of the copies. In positional mode each patch applies to the first occurrence of its find string in the running document, so order your patches to match the order the target text appears. not_found still fails the call, and replace_all still replaces every occurrence.

{
  "slug": "k9m2p4q7r1s8t3v6",
  "mode": "positional",
  "patches": [
    { "find": "<span class=\"price\">$10</span>", "replace": "<span class=\"price\">$12</span>" },
    { "find": "<span class=\"price\">$10</span>", "replace": "<span class=\"price\">$15</span>" }
  ]
}

A patch that can’t apply returns enough detail to repair the request without guessing:

{
  "error": "patch_failed",
  "failed_patch": 1,
  "reason": "ambiguous",
  "occurrences": 3,
  "message": "Patch at index 1: the find string occurs 3 times — include more surrounding context to make it unique, or set replace_all: true to replace every occurrence."
}

reason is not_found (occurrences: 0) or ambiguous (more than one occurrence without replace_all, unique mode only), and failed_patch is the zero-based index into your patches array. A link whose content has been purged by your retention policy returns content_unavailable: there is nothing stored to patch against, so use update_link with the full document instead. On success, fires the link.updated webhook, same as update_link.

delete_link

Delete one of your links.

{ "deleted": "k9m2p4q7r1s8t3v6" }

A link under legal hold returns { "error": "legal_hold", "message": "This link is under a legal hold and cannot be deleted." }. A slug you don’t own (or already deleted) returns an error starting Link not found or already deleted:, naming the account searched and the slug.

scan_html

Run the regex PII & secret scanner against HTML without publishing, for content you are not (yet) publishing. You do not need to call this before a publish: the four publishing tools run this same scan plus the Google Web Risk link check server-side and reject blocked content with the findings in the error, so pre-scanning doubles the work for no added safety.

{
  "hasSensitiveData": true,
  "findings": [
    { "type": "api_key", "label": "API Key", "count": 1 },
    { "type": "email",   "label": "Email Address", "count": 3 }
  ]
}

This is the zero-token regex scanner only: it reports findings but never blocks. The publish gates on create_link, create_links, update_link, and patch_link are what enforce your policy.

create_recipient_links

Mint per-recipient tracked URLs for a link you own. Batch up to 500 in one call. Each recipient gets a unique slug that resolves to the parent link’s HTML and stamps individual attribution into view records. A supplied email is never stored: it is kept only as a keyed HMAC-SHA256 hash. Paid plans only (Pro, Teams, Enterprise); Free accounts are refused.

{
  "recipients": [
    { "recipient_ref": "crm-4471", "url": "https://htmlvault.io/k9m2p4q7-a1b2" }
  ]
}

Returns { "error": "..." } on a Free-plan account, on an org role lacking recipient permissions, or when the parent slug isn’t owned by the caller. A successful call fires the recipient.created webhook once per call (not once per recipient).

Workflow recipes

Publish straight from a chat

Ask the agent to generate an HTML artifact (a proposal, dashboard, or one-pager), then “vault this.” The agent calls create_link with the HTML and a short title and returns the URL. Because the publish gates run server-side, anything that trips your PII policy or links to a site Google Web Risk flags is caught before the link exists.

Living dashboards

Publish a status page once with create_link, share the URL, then have the agent refresh it on a schedule with patch_link, swapping just the numbers rather than re-uploading the page every time (update_link is there for the occasional full rewrite). The slug never changes, so recipients always see current data at the same link, and get_analytics tells you who’s actually opening it.

Personalized runs

Building the same report for 80 accounts? Write the page once with {{account}}-style placeholders and hand it to create_links with one row per account: the template crosses the wire once instead of 80 times, and you get 80 slugs back in a single response. If the page content is identical for everyone and you only need to know who opened it, publish once and mint tracked URLs with create_recipient_links instead.

Documents too big for one call

A 4 MB report is one create_link call that either lands or is lost. Instead, open a draft with create_draft_link, stream it in with append_html a section at a time (checking content_length as you go), and publish with finalize: true on the last chunk. A dropped connection costs one chunk, not the document, and the gates still see the whole page at the end. The draft is not reachable by anyone until they pass.

Agent pipelines with notifications

When an automated pipeline creates links via MCP, subscribe your stack to the matching webhook events: link.created to log the new URL, link.viewed to react to engagement. The agent publishes; your systems are notified out-of-band without polling.

Limits & errors

Rate limit

Requests are rate-limited per credential to 100 requests per minute (fixed one-minute window): per API key, or per signed-in user across all their OAuth clients. Over the limit returns 429 with a Retry-After header:

{ "error": "rate_limited", "message": "Too many requests. Please slow down and retry after the window resets." }

The exact ceiling may be tuned over time; clients should honor Retry-After rather than hard-code the value.

Batch budget

create_links carries a second, row-weighted limit on top of the per-key request limit: 1,000 links per minute per account. It counts links, not calls (ten calls of 100 rows exhaust it just as one call of 1,000 would), and it is keyed per account, so issuing extra API keys does not widen it. Over budget returns a rate_limited tool result carrying retryAfterSeconds, and nothing is created.

Error catalog

Tool-level errors are returned as a JSON object in the content envelope (transport status 200); auth and rate-limit errors are returned at the HTTP layer with the status shown. Publish-gate blocks (pii_detected, pii_blocked, unsafe_content, too_many_urls, unverifiable_content, safety_check_unavailable, policy_unavailable, document_too_large, and the Free plan’s link-check rate_limited) additionally set the MCP isError flag on the result.