Use html.surf with pages and agents.

Core Concepts

Account Home

New accounts receive a random snake_case account ID. You can change it from the Account page if the new ID is available, and you can add a short bio that appears on your public home page.

• Your public home page is /p/:account_id.
• It shows your bio and a searchable list of your public pages.
• Changing your account ID changes the canonical URLs shown in the app.

Writing Pages

Pages are authored as HTML, not Markdown. Use /new to create a page, then edit it at /p/:account_id/:slug/edit.

The AI editor

The editor is an interactive, AI-assisted surface: a live preview of your page next to a chat panel. Click any element to select it, then ask in plain language — "reword this paragraph", "make this section dark themed", "add a pricing table", "make THIS chart like THAT". Edits stream in and apply live to the preview; nothing is saved until you hit Save, and an Undo button reverts the last turn. Behind the scenes the assistant makes targeted changes — editing the selected element, restyling via page CSS, or rewriting the page — rather than forcing you to hand-write HTML. A Source view is still there when you want to edit the raw markup directly.

Internal links

Link to another page with a normal relative path or account-scoped URL. These links become graph edges and appear in the page sidebar.

<article>
  <h1>Project Notes</h1>
  <p>See <a href="research-plan">the research plan</a>.</p>
  <p>Or link directly to <a href="/p/alex_notes/research-plan">Alex's plan</a>.</p>
</article>

Styling

• Choose Stored style to save the page with a reusable theme import and an article wrapper.
• Choose Custom layout when the HTML provides its own full-page style and structure.
• MCP writes must provide style_mode as theme or custom.

Visibility

• Public listed — readable by anyone; appears in public search, Explore, and your public profile.
• Public unlisted — readable by anyone with the URL; hidden from public search, Explore, and your public profile. Useful for pages you want to share but not broadly advertise.
• Private — readable only by the owner and explicit collaborators or via a guest share link.
• Owners can share a page with another signed-in user as a reader or editor.
• Owners can create expiring private guest links for people who do not have an account.
• Owners can change visibility from the page sidebar.
• Owners can delete a page from the page sidebar after confirming.

Version history

• Every save creates a new version. The latest is automatically the active version.
• The History panel in the page sidebar lists each version with timestamp and editor — visible only to the owner and explicit editors.
• Restoring an older version makes it the active version and replaces the live page content with that version's snapshot.
• You can delete any non-active version to remove clutter. The active version can't be deleted — restore another one first.
• MCP tools: list_versions, read_version, restore_version, delete_version.

Viewing Pages

Page content is displayed inside its own frame so page-level HTML and CSS can render without being flattened into the app shell. Use the width controls to inspect narrow, normal, wide, or full-width layouts.

• The breadcrumb starts at the account home and follows each slug segment.
• If a route has child pages but no page of its own, it shows the child pages you can read.
• Use the Download panel to export a readable page as HTML, Markdown, DOCX, or a styled print-to-PDF view.
• Links lists every internal link found in the page.
• References lists readable pages that link back to the current page.

Asking Questions

Use the Ask panel on any page to query the current page or the wider graph. Page scope starts with the current page and follows relevant links. Anywhere scope can search across pages you are allowed to read.

• The answer includes a short trace of pages read when available.
• Private pages are only used when you are signed in and have access.
• The navigator can use linked pages for context instead of only matching text.

MCP Server

html.surf exposes the same graph over MCP at /mcp. Hosted Claude connects with OAuth. Desktop and local MCP clients can use an API key from the Account page. Authenticated agents can read private pages you can access and can write pages when asked.

Claude connector

Connect Claude to https://html.surf/mcp, complete the OAuth flow, and allow https://html.surfas the link URI. For review, use a test account with sample public and private pages so read, search, link traversal, validation, and private writes can be checked.

• Search and summarize: "Search html.surf for my product planning pages and summarize the release risks."
• Read and traverse links: "Read my architecture overview on html.surf, follow its linked pages, and explain the data flow."
• Validate and save privately: "Draft a private html.surf page for my launch checklist, validate the HTML, and save it as private."

Desktop client config

{
  "mcpServers": {
    "html-surf": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://html.surf/mcp", "--header", "Authorization: Bearer hs_your_key_here"]
    }
  }
}

Core MCP tools

• search finds accessible pages with fast D1 search first, then semantic fallback.
• read returns a page title, text, HTML, visibility, and URL.
• links returns outbound links and backlinks.
• list lists public pages or your own pages when authenticated.
• validate checks generated HTML before writing.
• write creates or updates pages when authenticated.
• edit makes targeted find/replace edits to an existing page without resending the whole document — cheaper and safer than write for small changes, and it preserves the page's current styling.
• move relocates a page to a new slug (rename, or move between folders) without rewriting its HTML, and automatically repoints links that pointed at the old slug.
• delete moves a page you own to the trash — recoverable, and no longer viewable, listed, or searchable while trashed.
• list_trash / restore / purge list trashed pages, restore one to live, or permanently delete a trashed page.
• list_bookmarks retrieves your saved research bookmarks by folder.

Troubleshooting

• If Claude cannot connect, confirm the server URL is exactly https://html.surf/mcp.
• If OAuth does not start, disconnect the custom connector in Claude and add it again so Claude can rediscover the authorization metadata.
• If the magic link does not arrive, check spam and request a new link from the html.surf sign-in page. Magic links expire after 15 minutes.
• If private pages are missing, confirm you signed in with the same email that owns or has access to those pages.
• If a write fails, call validate first and include style_mode as theme or custom.
• For local desktop clients, create an API key from the Account page and restart the client after editing its MCP config.