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 /u/: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 /u/:account_id/:slug/edit. The preview tab renders the HTML in an isolated frame so you can check the page as it will appear.

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="/u/alex_notes/research-plan">Alex's plan</a>.</p>
</article>

Visibility

• Public pages can be read by anyone and appear on your public home page.
• Private pages are readable by their owner and explicit collaborators.
• 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.

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. Create an API key from the Account page, then add it to your MCP client. Authenticated agents can read private pages you can access and can write pages when asked.

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

Available 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.
• delete deletes a page you own.