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
- Read
get_portal_configurationand inspect existing pages withlist_portal_pagesandget_portal_page. The portal must be enabled. - Upload supported files with
upload_portal_asset. Reference returned literal relative paths in HTML and include all used IDs insave_portal_page.assetIds. MCP does not infer asset references from HTML. - Use
save_portal_pageto save a complete HTML draft at an exact path. The published version stays live. Keep CSS and JavaScript inline. - Use
preview_portal_pageto inspect the saved draft. Its private bearer link lasts 30 minutes; a new preview replaces the previous link. - Use
publish_portal_pageto 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:
| Guide | Documentation path |
|---|---|
| Enablement and overview | customer-portal |
| Help center and public article APIs | customer-portal/help-center |
| Drafts, publication, paths and browser rules | customer-portal/custom-pages |
| Uploads, references and deletion | customer-portal/assets |
| DNS setup and connection checks | customer-portal/custom-domains |
| MCP tool reference and examples | customer-portal/mcp |
| Review page for outside decisions | ai-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.