AI Knowledge & Logic

Custom portal pages

Authoring entry point for standalone HTML and JavaScript portal pages through MCP.

Customer portal documentation now has a dedicated section. This page remains available for existing links and MCP authoring instructions.

Authoring checklist

  1. Read get_portal_configuration and inspect existing pages with list_portal_pages and get_portal_page. The portal must be enabled.
  2. Upload supported files with upload_portal_asset. Reference returned literal relative paths in HTML and include all used IDs in save_portal_page.assetIds. MCP does not infer asset references from HTML.
  3. Use save_portal_page to save a complete HTML draft at an exact path. The published version stays live. Keep CSS and JavaScript inline.
  4. Use preview_portal_page to inspect the saved draft. Its private bearer link lasts 30 minutes; a new preview replaces the previous link.
  5. Use publish_portal_page to make the saved draft and asset manifest public together. Publishing, unpublishing and deleting revoke previews.

Built-in home, article and category paths take precedence when Help center is on. Disable Help center to use custom pages at those paths; the master portal switch still needs to be on. HTML is limited to 512 KiB and assets to 2 MiB each. Custom pages run with their portal origin: local storage, the microphone and the camera work, but cookies must not be used (the built-in address clears them on every page load). Public API fetches must use credentials: "omit". Keep secrets out of public HTML.

For complete guidance, read these pages through read_octocom_docs using the path shown below:

GuideDocumentation path
Enablement and overviewcustomer-portal
Help center and public article APIscustomer-portal/help-center
Drafts, publication, paths and browser rulescustomer-portal/custom-pages
Uploads, references and deletioncustomer-portal/assets
DNS setup and connection checkscustomer-portal/custom-domains
MCP tool reference and examplescustomer-portal/mcp
Review page for outside decisionsai-knowledge-and-logic/external-decisions

Reading and editing large pages

get_portal_page returns the draft only by default. Set version: "published" to inspect the live copy instead. The response includes html, that version's assetIds, and htmlRevision for the complete HTML. An unpublished page returns html: null for the published version.

HTML is capped at 12,000 characters by default. Use htmlSelection with inclusive startLine/endLine, literal find plus contextLines, or zero-based character offset. Set maxChars (up to 50,000) to control response size. htmlRead reports total characters/lines, returned boundaries, truncated, and nextOffset. Continue with htmlSelection: { "offset": <nextOffset> }; do not combine offset with a search or line range. Check that the revision remains unchanged while paging.

For small edits call patch_portal_page:

{
  "businessId": "business-uuid",
  "id": "page-uuid",
  "expectedHtmlRevision": "htmlRevision-from-draft-read",
  "htmlEdits": [
    { "oldText": "<h2>Old heading</h2>", "newText": "<h2>New heading</h2>" }
  ]
}

Each old text must match exactly once. Edits run in order and succeed together or not at all. Empty replacement text deletes the match. A stale revision, missing match, ambiguous match, invalid asset or oversized result rejects the entire change. The patch preserves title, path and draft assets; optionally supply the full assetIds manifest when changing asset references. It never changes published content.

save_portal_page remains the create/full-replacement tool: never send it a truncated read. Save, patch and publish return compact metadata rather than echoing both HTML copies. Patch additionally returns a bounded diff and new revision. Preview and publish are still separate explicit actions.

On this page