MCP Server

Last updated: 2026-10-29

brewpage-mcp 1.16.7 provides twenty tools to publish and manage HTML, Markdown, JSON, KV, files, and multi-file sites from compatible MCP clients. It runs locally over stdio (Node.js 20 or newer) or remotely without install, and calls the BrewPage API.

Installation

Remote (no install)

Add https://brewpage.app/mcp as a custom connector / remote MCP server by URL in Claude.ai, ChatGPT or any Streamable HTTP client. No auth; same 20 tools.

Claude Code: claude mcp add --transport http brewpage https://brewpage.app/mcp, or in .mcp.json:

{
  "mcpServers": {
    "brewpage": {
      "type": "http",
      "url": "https://brewpage.app/mcp"
    }
  }
}

Claude Desktop

Open Claude Desktop’s Settings > Developer > Edit Config and add to claude_desktop_config.json (official setup):

{
  "mcpServers": {
    "brewpage": {
      "command": "npx",
      "args": ["-y", "brewpage-mcp@1.16.7"]
    }
  }
}

Claude Code

Register a project-scoped stdio server:

claude mcp add --transport stdio --scope project brewpage -- npx -y brewpage-mcp@1.16.7

This writes .mcp.json in the project root; user-scoped registration uses --scope user. See the official Claude Code MCP guide.

One-liner

npx -y brewpage-mcp@1.16.7

This starts a stdio server for an MCP client, not an interactive publishing shell. Other clients can use the same npx command and pinned arguments.

Available Tools

Visibility and Delivery

All five publish tools accept optional deliveryMode: "path" | "subdomain"; it is sent as X-Delivery-Mode, without changing content bodies. Omitted namespace is private (a generated priv-<random> namespace): unlisted and not indexed; anyone with the link can still open it. public lists HTML, sites and files in the gallery and sitemap, so Google, Bing and AI search can find and index them; public pages are served on the brewpage.app domain for the strongest reach (a site always gets its own subdomain). Never put secrets in a public publication. Password-protected publications, JSON and KV are never listed.

These tools wrap a subset of the backend-generated public REST contract. MCP TTL inputs take days or a string such as 2w (default 15); the server rounds to whole days and clamps to 1–30 (up to 90 with a profile token), and owner-specific caps and eligible automatic extensions can affect actual expiry. Use returned expiresAt. Tolerated-input adjustments come back in the response notices array, printed as Notice (code): message; secret-detected prints as WARNING (code): message; a live BrewPage token or manage link in public content prints first as SECURITY ALERT (credential-published): … (remove it and reset it). A minted manageUrl prints as MANAGE LINK (private): …: give it to the user privately, never publish it. Set BREWPAGE_OWNER_TOKEN (local server only) for a default owner token; outputs name it instead of printing it. Secrets allowed; likely ones are flagged in notices. For a secret: private namespace + password. get_page reads stored rendered HTML or format-specific code/text, rather than owner-only original source or a browser viewer.

For a fresh publication, sites and HTML pages of format HTML outside public (including the generated unlisted namespace) always use Dedicated subdomain; omit deliveryMode there. An explicit path there is not rejected: the publication is created on its subdomain and the result reports deliveryModeMatched: false, deliveryModeReason: "policy:subdomain-required" and a Delivery notice: line. Everything else in any namespace (Markdown, code/text, files, JSON, KV, public HTML) defaults to Promotion (path) and may choose Dedicated subdomain (subdomain), including when password-protected. Markdown raw HTML is rendered through an allowlist (no scripts, styles, event handlers, forms or embeds; links http/https/mailto/tel/relative); earlier pages change only when republished. Promotion has stricter active-document restrictions. Each NEW site gets one publication-specific host for its complete bundle, preserving relative/root-relative paths; missing assets return 404 with no SPA fallback. Third-party widgets may need provider configuration.

Use the server’s primary link exactly, including the root slash. Never reconstruct a host from namespace or ID. Responses expose routingCohort, deliveryMode, requestedDeliveryMode, effectiveDeliveryMode, deliveryModeMatched, modeLocked, hostingVersion, access, and the trusted-apex managementLink when supplied. NEW password links are clean URLs: do not append ?p=; browser readers unlock through the trusted gateway. API calls and owner tokens stay on the configured apex API origin.

When deliveryMode is omitted for a public HTML or Markdown page, the server may publish it on its own subdomain if the page needs browser features a BrewPage link does not provide. publish_html then prints deliveryModeReason: "auto:<codes>" and a Delivery notice: line; pass deliveryMode: "path" to keep a BrewPage link, or change it later with update_hosting. advisory:<codes> (from publish_html or update_html) means the address was not changed but such features were found. Neither line appears when nothing applies.

When creation returns an existing publication, it keeps its actual link, cohort, and mode even when another mode was requested. OLD publications show Existing link with null mode metadata and retain their legacy links and behavior. Content updates and site republishing preserve hosting.

Publish and Update

Ask your assistant to publish the content, save the returned owner token, and share the returned primary link. publish_html, publish_site, publish_json, and publish_kv accept password and ttlDays (days or a string such as 2w; default 15; clamped to 1–30, up to 90 with a profile token). publish_file accepts a source url, optional namespace, filename, and deliveryMode; it does not expose base64, password, or TTL inputs.

publish_html(content="<h1>Report</h1>", format="HTML", ttlDays=15)
publish_site(files=[{"path":"index.html","content":"<link rel='stylesheet' href='/style.css'><h1>Site</h1>"},{"path":"style.css","content":"body{font-family:sans-serif}"}])

For sites, provide exactly one of entryContent or a non-empty files array of {path, content}. entry defaults to index.html. republish_site requires namespace, id, and ownerToken; it replaces the full file set, removing files absent from the new bundle. It also accepts entry, ttlDays, and tags (replace the stored tags, [] clears, omitted keeps them); its TTL input is ignored (existing expiry is kept; a ttl-ignored notice is returned).

Call get_limits before publishing a large or multi-file site. A request is at most 25 MiB; a site at most 200 files, 5 MiB per file and 20 MiB in total; each path at most 380 characters. System files such as .DS_Store and __MACOSX/ are skipped and never count; files with an unsupported extension or a too-long path are skipped and reported in notices. Without entry, the root index.html is the entry, else the shallowest HTML file. A site limit hit answers 400 with a message naming the limit, as does a PDF/Office file that is unreadable or password-protected; 413 means the request is over 25 MiB, has too many files and form fields, or a file name/path is too long; 422 means no servable file is left; 503 means busy: retry after Retry-After seconds (failed publish tools print it).

Change Hosting

update_hosting changes an eligible NEW publication (not a site, not a non-public html-format HTML page) between Promotion and Dedicated subdomain. Required inputs: type (html, file, json, or kv), namespace, id, ownerToken, and deliveryMode; expectedVersion (current hostingVersion, integer ≥1) is optional, pass it when known.

It calls owner-only PATCH /api/{html|files|json|kv}/{namespace}/{id}/hosting with {deliveryMode} plus expectedVersion when given, and X-Owner-Token. Mismatches are reported, not rejected: a stale or omitted version still applies the choice (a stale one adds deliveryModeReason: "policy:version-stale"); sites and non-public html-format HTML pages stay on their subdomain (policy:mode-locked) and OLD links stay unchanged (policy:classic-link), each answered 200 with deliveryModeMatched: false and a Delivery notice: line. Wrong owner returns 403, a malformed version (not a positive integer) 400, and a paused real change 503. Selecting the current mode returns 200 without incrementing the version. Always use the returned primary link; the reserved publication host survives both directions.

update_hosting(type="html", namespace="public", id="aBcDeFgHiJ", ownerToken="tok_...", deliveryMode="subdomain", expectedVersion=1)

Delete a Resource

delete_resource takes namespace, id, type (html, site, kv, json or file) and ownerToken (default BREWPAGE_OWNER_TOKEN, local server only); path segments are URL-encoded.

Owner Token Reminder

Every publish response includes your owner token. You need it to update or delete your content later. Save it somewhere safe — it cannot be recovered if lost.

Optional: sign in free (Google or any email) at https://account.brewpage.app to never lose your pages or tokens and to mint tokens that never expire. Not needed to publish.

Pass it to owner-only tools and to search_gallery(mine=true, ownerToken="tok_...") to list your resources. The publish_site, publish_json, and publish_kv tools accept an existing ownerToken to group new content under the same owner.

Configuration

BREWPAGE_URL defaults to https://brewpage.app. Set it to an authorized BrewPage apex API origin, never a publication host.

Source Code

See the full implementation: mcp-server/