Skip to content

getting-started.md

Latest commit

 

History

History
142 lines (104 loc) · 3.75 KB

getting-started.md

File metadata and controls

142 lines (104 loc) · 3.75 KB
Raw

Getting started

htmlbook is a hosted service. You connect your coding agent to its MCP server (or its REST API) with an API key, then your agent can publish documents to a shareable URL. There is nothing to self-host.

1. Get an API key

  1. Sign in at https://htmlbook.io (Google / GitHub).
  2. Open Settings → API keys.
  3. Generate a key for your workspace. It looks like hb_live_….

A key is bound to one workspace. Keep it in an environment variable:

export HTMLBOOK_API_KEY="hb_live_xxxxxxxxxxxxxxxxxxxx"

Keys are stored only as SHA-256 hashes on the server — htmlbook can never show you a key again after you generate it, so save it now. Generating a new key for a workspace rotates (revokes) the old one.

2. Connect your agent

Claude Code

Browser login — the simplest path, no key to manage:

claude mcp add --transport http htmlbook https://htmlbook.io/api/mcp
# then run `claude` and approve the htmlbook login in your browser

With an API key instead:

claude mcp add --transport http htmlbook https://htmlbook.io/api/mcp \
  --header "Authorization: Bearer $HTMLBOOK_API_KEY"

Share it with a repo via a project-scoped .mcp.json:

{
  "mcpServers": {
    "htmlbook": {
      "type": "http",
      "url": "https://htmlbook.io/api/mcp",
      "headers": { "Authorization": "Bearer ${HTMLBOOK_API_KEY}" }
    }
  }
}

Verify it connected:

claude mcp list
# htmlbook  ✓ connected

Cursor

~/.cursor/mcp.json (or .cursor/mcp.json in a project):

{
  "mcpServers": {
    "htmlbook": {
      "url": "https://htmlbook.io/api/mcp",
      "headers": { "Authorization": "Bearer hb_live_REPLACE_WITH_YOUR_KEY" }
    }
  }
}

Codex CLI

~/.codex/config.toml:

[mcp_servers.htmlbook]
url = "https://htmlbook.io/api/mcp"
bearer_token_env_var = "HTMLBOOK_API_KEY"

claude.ai & Claude Desktop

These clients require OAuth, not a static key. Add a custom connector:

Connector URL:  https://htmlbook.io/api/mcp

Approve the htmlbook login when prompted. htmlbook runs its own OAuth 2.1 server that bridges your existing htmlbook login — there is no second account to create.

Any other MCP client

Endpoint:   https://htmlbook.io/api/mcp
Transport:  streamable-http
Auth:       Authorization: Bearer <your key>     (CLI / config clients)
            or OAuth 2.1 with Dynamic Client Registration (claude.ai / Desktop)

3. Publish your first document

Ask your agent in plain language:

Summarize this folder's API as a one-page HTML doc and publish it to htmlbook
under project "acme".

The agent calls publish, and you get back a reader link immediately:

✓ shelved (hbdoc) · acme/api-overview · v1 · read: https://htmlbook.io/app/p/acme/api-overview
  private — set_access "public" for a share link

Make it shareable:

Make that doc public.
→ ✓ acme/api-overview is now public · https://htmlbook.io/d/a1b2c3

Troubleshooting

  • 401 Unauthorized on connect — the key is missing, wrong, or was rotated. Re-copy it from Settings and update your config.
  • Tool calls succeed but nothing appears in the library — check you're looking at the same workspace the key is bound to (the sidebar switcher).
  • A markdown push rendered as a sandboxed page — it was treated as a bundle. Send it via the markdown field (MCP) or with a .md content type / leading non-< body (REST). See publishing.md.
  • HTML lost its styling in the reader — an hb-doc must carry no CSS of its own and use only hb-* classes + --hb-* tokens. See hb-doc-contract.md.

Next: Publishing · MCP tools · REST API