MCP + AGENT SKILL

Give your agent
a safe way to publish.

Connect once and ask your agent to share a file. Send HTML or Markdown directly—no base64 conversion, local server, account, or API key is required for Free publishing.

No accountNo API key1-hour default

Last updated

QUICK START

Connect once. Then ask for a link.

Checking endpoint
  1. 01ConnectAdd the remote tools
  2. 02PublishAsk your agent to share the file
STREAMABLE HTTPhttps://html2web.iill.dev/mcp
STEP 01

Connect your agent

Choose the app you already use. Cursor and VS Code open the reviewed connection inside the app; terminal clients use one copyable command.

TERMINAL

Connect in Codex

Runs once · available globally

Paste this in a terminal, then restart the current Codex session if the tools do not appear immediately.

codex mcp add html2web --url https://html2web.iill.dev/mcp
STEP 02

Publish your first page

Attach or point your agent to an HTML or Markdown file, then send this prompt. The agent reads the source locally; HTML2WEB does not access your filesystem.

FIRST PROMPT

Share this file as a browser link for 1 hour.

Done looks like: public URL, expiry time, password status, and what was actually checked. Private ownership keys stay out of ordinary chat.

Writing your own client? One tool call is enough

Call publish_share with the original UTF-8 source. The filename selects the format. Generate a random request key once and keep it for retries; do not reuse this example key.

{
  "content": "# Review notes\n\nReady to share.",
  "filename": "review-notes.md",
  "idempotencyKey": "replace-with-one-random-request-key"
}

Return url to the recipient. Keep manageToken, manageUrl and creatorPreviewUrl private. A retry with the same key returns the same URL without recovering those keys.

Retry protection applies to the same caller identity while its request record remains valid, for up to 24 hours. Anonymous IP or UTC-day changes can change that identity. Do not assume a delayed retry or a changed network will be deduplicated.

OPTIONAL WORKFLOW

Install the Agent Skill

MCP works without this extra installation. Add the skill if you want compatible agents to follow the same source-checking, retry, verification, and private-link workflow.

EXECUTIONMCP

Publishes and manages the link.

WORKFLOWAgent Skill

Guides safe, consistent tool use.

npx skills add https://html2web.iill.dev --skill publish-html2web --global --yes
Only want it in the current project?
npx skills add https://html2web.iill.dev --skill publish-html2web --yes

Available tools

publish_share
Recommended: share HTML or Markdown source directly. A filename selects the format; no base64 is needed.
get_publish_limits
Check this connection’s file-size and active-link limits, expiry choices, and availability without using publishing quota.
publish_html
Compatibility: publish an HTML string.
publish_markdown
Compatibility: render and publish a Markdown string.
publish_html_file
Compatibility: publish base64-encoded UTF-8 HTML or Markdown.
update_share
Replace content on the same URL. Pass the current contentVersion as expectedContentVersion to avoid overwriting newer changes.
delete_share
Delete the share immediately.
set_password
Add, change, or remove viewer protection.
set_expiry
Change the expiry within the current plan.
get_share_status
Read status and contentVersion without retrieving source or recording an open.

Management tools accept the public URL in slug. For links owned by the connected Pro account, no manage token is needed. Anonymous links still require their private ownership key.

Free limits

Up to 1 MiB (1,048,576 UTF-8 bytes) per file, with 30-minute, one-hour, or 24-hour expiry. Temporary operating restrictions can narrow these choices; get_publish_limits reports the current policy.

Quota errors include a reset time or retry delay. Other errors explain the next action. Never silently truncate a file, retry with a new key to bypass limits, or recreate an expired link without asking.

Reconnect with Pro OAuth

Pro uses a separate protected endpoint. Your MCP client handles OAuth; you never create, copy, or paste an API key.

https://html2web.iill.dev/mcp/pro
  1. Open the HTTPS upgrade URL returned with the Free quota error.
  2. Sign in with Google or GitHub, then complete checkout in the browser.
  3. Wait until the verified subscription is active on your HTML2WEB account.
  4. Add or reconnect the Pro endpoint above and finish the browser authorization prompt.

Publishing receives Pro quota only after the subscription webhook is verified and the MCP connection is authorized for that account.

If checkout is unavailable, keep using Free or contact@iill.dev. Signing in alone does not activate Pro, and a link-credit pack alone does not unlock the Pro MCP endpoint.

If your client cannot open upgrade links

Copy the upgradeUrl from the tool result into a normal browser. Complete sign-in and checkout there, then add the Pro endpoint as a new Streamable HTTP connection. If the client still uses the public Free endpoint, remove that stale connection and reconnect—do not paste a bearer token or checkout URL into the MCP configuration.

Manage tokens are ownership keys

A first publish response contains a manage token for later changes. Your MCP client and agent receive this private key; it is not an API key and is never needed to view the page. Keep it out of public channels, ordinary chat and analytics. Only save it when the user requests private storage in an appropriate secret store.

Inspect source for passwords, API keys, personal data, or tokens before publishing. The viewer is isolated, but the shared page is reachable by anyone who has its URL unless you set a password.