Notes → report or brief
“Turn these notes into a decision brief. Show the recommendation, evidence, tradeoffs, and open questions.”
Recipe: visual-report
SHARE/ARTIFACTS · MCP REFERENCE
MCP tools for
AI-made artifacts.
Your agent creates the work.
These tools give it a place to go.
Publish a reviewed HTML page, update the same link, choose who can open it, or reuse your saved style—all through one agent connection.
THE SHORT ANSWER
What can an agent do with share/artifacts MCP?
It can discover content recipes, publish static HTML documents and presentations, find and update your artifacts, manage access, and read or save an artifact style. You provide the task and approve publishing. Your agent handles the tool calls.
Model Context Protocol (MCP) lets your agent use tools from a connected service. There is one hosted MCP endpoint, not a separate HTTP URL for each tool. An MCP client discovers tool names and arguments with tools/list and invokes them with tools/call.
START WITH THE OUTCOME
What would you like to make?
The recipe helps your agent shape the content. Publishing comes after you review the result.
Research → visual explainer
“Explain this idea for a nontechnical reader. Use a concrete example and a visual that makes the mechanism clear.”
Recipe: infographic-explainer
Content → presentation
“Build a presentation for this audience. Give it a clear argument, supporting evidence, and a useful next step.”
Recipe: presentation-deck
THE CONNECTION
One address to add to your agent.
Add the hosted URL in a compatible MCP client and complete browser authorization. Verify the connection with list_pages—there is no need to publish a test artifact.
HOSTED MCP · OAUTH
https://shareartifacts.dev/api/mcpThe URL is selectable text. Copy it into your client’s MCP server settings.
- Human reference
/mcp· this page- Agent setup
- Connection instructions
- Token-based fallback
- Local stdio package →
/api/v1
Hosted GET, POST, and DELETE are transport methods, not instructions to create or delete an artifact. Older servers or installed packages may expose fewer tools; check your connection’s tool list.
TOOL REFERENCE · 01
Create
Find a starting point and publish reviewed HTML.
Choose a starting point
get_recipe
Find content recipes or retrieve the prompt, HTML starter, and checks for one format.
Arguments, example, and result
Required arguments
None.
Optional arguments
recipeId- A catalog ID such as visual-report or presentation-deck. Omit to list recipes. Guide names such as weekly-status-report are not recipe IDs.
version- A positive integer for a specific recipe version; requires recipeId. Omit to get the latest version.
Example arguments
Illustrative JSON, not a live request. Replace example IDs and content with your own; do not paste credentials here.
{
"recipeId": "visual-report"
}What comes back
kind- recipe_catalog when listing, or recipe when retrieving one.
recipes- Catalog entries include recipeId, title, summary, availableVersions, latestVersion, and latestContentSha256.
prompt- A retrieved recipe includes prompt, starterHtml, rules, and qualityChecklist, plus its version and contentSha256.
Before you call it
This does not publish anything. Hosted MCP still requires an authenticated connection, even though reading recipes needs no page or style scope.
If something goes wrong
If an ID or version is unavailable, call get_recipe with no arguments and choose from the returned catalog. Do not invent a recipe ID.
Publish a static HTML artifact
publish_html
Host a reviewed HTML page and get a stable link to it.
Arguments, example, and result
Required arguments
html- The complete static HTML document as a string, not a filename, URL, or patch. The current input limit is 1,000,000 UTF-8 bytes.
Optional arguments
title- A distinctive title, up to 120 characters. On update, omission keeps the current title.
sharing- Omit for owner-only access, or explicitly choose private, public, or restricted. Restricted methods can include recipients, emailDomain, or a password with action set. Optional future ISO 8601 expiresAt ends recipient access; the owner can still review the page. Null or omission means no expiration.
styleRef- Optional exact active styleVersionId, revision, and contentSha256 from get_artifact_style. Requires styles:read as well as pages:write. This records the requested style, not verified visual fidelity; omission declares no style for this revision.
Example arguments
Illustrative JSON, not a live request. Replace example IDs and content with your own; do not paste credentials here.
{
"title": "Reviewed brief",
"html": "<!doctype html><html lang=\"en\"><head><meta charset=\"utf-8\"><meta name=\"viewport\" content=\"width=device-width, initial-scale=1\"><title>Reviewed brief</title><style>body{max-width:48rem;margin:2rem auto;padding:1rem;font:18px/1.6 system-ui;color:#171714;background:#fff}h1{line-height:1.2}</style></head><body><main><h1>Reviewed brief</h1><p>Replace this sample with your approved content.</p></main></body></html>",
"sharing": {
"mode": "private"
}
}What comes back
pageId- The new artifact ID. Save it for later updates.
publicUrl- The stable viewer URL. This field name does not mean public access.
status- The lifecycle status, separate from who can open the page.
version- The content version, starting at 1.
contentSha256- A fingerprint of the saved, sanitized HTML—not the raw source you submitted.
artifactType- document or presentation.
artifactSchemaVersion- The artifact structure version.
artifactMetadata- For a presentation, includes aspectRatio and slideCount.
sanitizerSummary- A summary of removed active content. Still inspect the published result.
sharing- The effective access mode, revision, expiration, and restricted methods.
Before you call it
Publish only after approval. Omitted sharing is owner-only. Submitted scripts, forms, and embeds are removed; external images and fonts may still load. A style reference is returned only when the connection can read styles.
If something goes wrong
On publication_state_unknown, inspect recent list_pages results by title and time before retrying. Creating again can duplicate an artifact. A not_published result means the reported attempt did not publish.
Publish an HTML slide deck
publish_presentation
Create an HTML presentation with its own slide viewer, using the presentation-deck recipe.
Arguments, example, and result
Required arguments
html- The complete static HTML document as a string, not a filename, URL, or patch. The current input limit is 1,000,000 UTF-8 bytes.
Optional arguments
title- A distinctive title, up to 120 characters. On update, omission keeps the current title.
sharing- Omit for owner-only access, or explicitly choose private, public, or restricted. Restricted methods can include recipients, emailDomain, or a password with action set. Optional future ISO 8601 expiresAt ends recipient access; the owner can still review the page. Null or omission means no expiration.
presentation- Defaults to schemaVersion 1 and aspectRatio 16:9. The other supported ratio is 4:3. The complete document must contain 1–100 slides and follow the presentation-deck structure.
Example arguments
Illustrative JSON, not a live request. Replace example IDs and content with your own; do not paste credentials here.
{
"title": "Reviewed deck",
"html": "<!doctype html><html lang=\"en\"><head><meta charset=\"utf-8\"><meta name=\"viewport\" content=\"width=device-width, initial-scale=1\"><title>Reviewed deck</title><style>*{box-sizing:border-box}body{margin:0;color:#171714;background:#fff;font:20px/1.5 system-ui}.share-slide{min-height:100vh;padding:8vw}h1{font-size:clamp(2rem,6vw,4rem);line-height:1.15}@media print{@page{size:13.333in 7.5in;margin:0}.share-slide{height:7.5in;min-height:0;break-after:page}}</style></head><body><main class=\"share-presentation\"><section class=\"share-slide\" id=\"slide-1\" aria-labelledby=\"slide-1-title\"><h1 id=\"slide-1-title\">Reviewed deck</h1><p>Replace this sample with your approved slide content.</p></section></main></body></html>",
"presentation": {
"schemaVersion": 1,
"aspectRatio": "16:9"
},
"sharing": {
"mode": "private"
}
}What comes back
pageId- The new artifact ID. Save it for later updates.
publicUrl- The stable viewer URL. This field name does not mean public access.
status- The lifecycle status, separate from who can open the page.
version- The content version, starting at 1.
contentSha256- A fingerprint of the saved, sanitized HTML—not the raw source you submitted.
artifactType- document or presentation.
artifactSchemaVersion- The artifact structure version.
artifactMetadata- For a presentation, includes aspectRatio and slideCount.
sanitizerSummary- A summary of removed active content. Still inspect the published result.
sharing- The effective access mode, revision, expiration, and restricted methods.
Before you call it
Get presentation-deck first. Inspect every slide at desktop, narrow, and print sizes when rendering is available; report any missing visual QA. This tool does not accept styleRef. A document cannot be converted into a presentation by updating it.
If something goes wrong
Fix invalid_presentation structure in the source, then review again. For an uncertain publication, inspect recent pages before retrying. Do not fall back to a less restricted publish to bypass an access error.
TOOL REFERENCE · 02
Find and maintain
Find the right artifact, revise it, or take it offline.
Find the right artifact
list_pages
Search your own artifact library and continue through paginated results.
Arguments, example, and result
Required arguments
None.
Optional arguments
query- Case-insensitive title or page-ID search, up to 120 characters.
status- Filter by published or unpublished. Unpublished means Offline; platform-taken-down items can appear in results as taken_down.
limit- 1 to 100 results per page; defaults to 25.
cursor- An opaque nextCursor or previousCursor from an earlier result. Keep its query, status, and limit unchanged.
Example arguments
Illustrative JSON, not a live request. Replace example IDs and content with your own; do not paste credentials here.
{
"query": "Reviewed brief",
"limit": 25
}What comes back
pages- Each match includes pageId, title, status, publicUrl, dates, artifactType, artifactSchemaVersion, and artifactMetadata.
pageInfo- Includes resultCount, matchingCount, totalLibraryCount, limit, nextCursor, and previousCursor.
Before you call it
A matching title is not proof that it is the artifact the user meant. Resolve ambiguous results before updating, sharing, or deleting. The list never makes an artifact public.
If something goes wrong
For invalid_cursor, restart with the intended filters and no cursor. Follow nextCursor when results remain; the first page is not necessarily the whole library.
Check an artifact's current state
get_page
Read the current status, content version, and stable URL for one artifact you own.
Arguments, example, and result
Required arguments
pageId- The exact ID returned when the artifact was published or found with list_pages. Pass the ID, not the whole share URL.
Example arguments
Illustrative JSON, not a live request. Replace example IDs and content with your own; do not paste credentials here.
{
"pageId": "p_REPLACE_WITH_SAVED_PAGE_ID"
}What comes back
pageId- The requested artifact's ID.
title- Its current title.
status- published, unpublished, or taken_down. This is not an access mode.
publicUrl- The stable viewer URL, even when access is private.
version- The current content version.
contentSha256- A fingerprint of the saved sanitized HTML.
artifactType- document or presentation.
artifactSchemaVersion- The artifact structure version.
artifactMetadata- Stored format information; presentations include ratio and slide count.
createdAt- When the artifact was created.
updatedAt- When its stored record was last updated.
Before you call it
This returns metadata, not source HTML. Keep the complete source outside the service for future editing. Connections with styles:read may also receive declaredStyleRef.
If something goes wrong
If the artifact cannot be found, check the saved ID, owner, and library. Do not create a replacement solely because a lookup failed.
Revise the page, keep the link
update_page
Replace the full HTML of an existing artifact without sending a new URL.
Arguments, example, and result
Required arguments
pageId- The exact ID returned when the artifact was published or found with list_pages. Pass the ID, not the whole share URL.
html- The complete static HTML document as a string, not a filename, URL, or patch. The current input limit is 1,000,000 UTF-8 bytes.
Optional arguments
title- A distinctive title, up to 120 characters. On update, omission keeps the current title.
styleRef- Optional exact active styleVersionId, revision, and contentSha256 from get_artifact_style. Requires styles:read as well as pages:write. This records the requested style, not verified visual fidelity; omission declares no style for this revision.
Example arguments
Illustrative JSON, not a live request. Replace example IDs and content with your own; do not paste credentials here.
{
"pageId": "p_REPLACE_WITH_SAVED_PAGE_ID",
"html": "<!doctype html><html lang=\"en\"><head><meta charset=\"utf-8\"><meta name=\"viewport\" content=\"width=device-width, initial-scale=1\"><title>Reviewed brief</title><style>body{max-width:48rem;margin:2rem auto;padding:1rem;font:18px/1.6 system-ui;color:#171714;background:#fff}h1{line-height:1.2}</style></head><body><main><h1>Reviewed brief</h1><p>Replace this sample with your approved content.</p></main></body></html>"
}What comes back
pageId- The existing artifact ID, unchanged.
publicUrl- The stable viewer URL. This field name does not mean public access.
status- The lifecycle status, separate from who can open the page.
version- The new content version after a successful replacement.
contentSha256- A fingerprint of the saved, sanitized HTML—not the raw source you submitted.
artifactType- document or presentation.
artifactSchemaVersion- The artifact structure version.
artifactMetadata- For a presentation, includes aspectRatio and slideCount.
sanitizerSummary- A summary of removed active content. Still inspect the published result.
Before you call it
This is not a partial patch. Access, expiration, offline status, and artifact type stay unchanged. A successful update counts as a publishing action. Serialize updates to the same page; there is no expected-version argument to prevent an older run from overwriting newer content.
If something goes wrong
For update_state_unknown, use get_page to inspect the version and sanitized-content hash, then verify the result before retrying. Do not compare the hash with raw unsanitized source or assume a timeout means nothing was saved.
Bring an offline artifact back
publish_page
Republish an existing offline artifact at its current URL. This tool does not create a new page.
Arguments, example, and result
Required arguments
pageId- The exact ID returned when the artifact was published or found with list_pages. Pass the ID, not the whole share URL.
Example arguments
Illustrative JSON, not a live request. Replace example IDs and content with your own; do not paste credentials here.
{
"pageId": "p_REPLACE_WITH_SAVED_PAGE_ID"
}What comes back
ok- true on success.
status- published on success.
Before you call it
Republishing does not make access public or remove expiration. Bringing an offline page back counts as a publishing action; an already-published page is a no-op. Platform takedowns cannot be overridden.
If something goes wrong
For an uncertain result, check get_page and get_page_sharing. A published status does not guarantee that an intended reader is authorized or that the link has not expired.
Take an artifact offline
unpublish_page
Stop serving an artifact without deleting its source record or changing its URL.
Arguments, example, and result
Required arguments
pageId- The exact ID returned when the artifact was published or found with list_pages. Pass the ID, not the whole share URL.
Example arguments
Illustrative JSON, not a live request. Replace example IDs and content with your own; do not paste credentials here.
{
"pageId": "p_REPLACE_WITH_SAVED_PAGE_ID"
}What comes back
ok- true on success.
status- unpublished on success.
Before you call it
Confirm the exact artifact before taking it offline. This does not recall saved copies or screenshots. The artifact remains available in its owner's library for later review or republishing.
If something goes wrong
Check get_page before repeating an uncertain request. Repeating unpublish leaves the page offline but also advances its access revision; reload sharing before a later access change.
Delete an artifact permanently
delete_page
Remove an artifact from your library. Use unpublish_page instead if you may need it again.
Arguments, example, and result
Required arguments
pageId- The exact ID returned when the artifact was published or found with list_pages. Pass the ID, not the whole share URL.
Example arguments
Illustrative JSON, not a live request. Replace example IDs and content with your own; do not paste credentials here.
{
"pageId": "p_REPLACE_WITH_SAVED_PAGE_ID"
}What comes back
ok- true when deletion succeeds.
Before you call it
Deletion is permanent and requires an explicit choice of the exact artifact. It cannot recall copies already saved by readers. A documentation example is not authorization to delete.
If something goes wrong
After an uncertain response, check the library before retrying. A repeated delete may return page_not_found; do not interpret that as a reason to create a replacement.
TOOL REFERENCE · 03
Control access
Choose who can open an artifact and manage viewing sessions.
Read the current access settings
get_page_sharing
See who can open an artifact and retrieve the revision needed to change its sharing.
Arguments, example, and result
Required arguments
pageId- The exact ID returned when the artifact was published or found with list_pages. Pass the ID, not the whole share URL.
Example arguments
Illustrative JSON, not a live request. Replace example IDs and content with your own; do not paste credentials here.
{
"pageId": "p_REPLACE_WITH_SAVED_PAGE_ID"
}What comes back
pageId- The artifact whose access was read or changed.
publicUrl- Its stable viewer URL.
mode- private, public, or restricted.
revision- Use this sharing revision for the next approved change.
expiresAt- The recipient access end time, or null when no expiration is set. The owner can still review the page.
hasPassword- Whether a password is enabled. The password itself is never returned.
recipients- Allowed verified-email addresses.
emailDomain- The allowed verified-email domain, or null.
Before you call it
Read access separately from lifecycle status. A page can be published but owner-only, restricted, or expired. Password values are never returned.
If something goes wrong
Read this again after another access change or session reset. Use the latest sharing revision, not a content version copied from get_page.
Choose who can open it
set_page_sharing
Replace an artifact's access policy after the owner chooses the audience.
Arguments, example, and result
Required arguments
pageId- The exact ID returned when the artifact was published or found with list_pages. Pass the ID, not the whole share URL.
expectedRevision- The latest sharing revision from get_page_sharing. This is not the artifact's content version or its style revision.
policy- The complete private, public, or restricted policy. Restricted methods are OR alternatives: emailDomain, up to 100 recipients, or password. A password set value must be 10–128 characters; action keep retains an existing password. Include the expiry you want to retain; omission or null removes it.
Example arguments
Illustrative JSON, not a live request. Replace example IDs and content with your own; do not paste credentials here.
{
"pageId": "p_REPLACE_WITH_SAVED_PAGE_ID",
"expectedRevision": 1,
"policy": {
"mode": "restricted",
"methods": {
"recipients": [
"reader@example.com"
],
"emailDomain": "example.org"
},
"expiresAt": null
}
}What comes back
pageId- The artifact whose access was read or changed.
publicUrl- Its stable viewer URL.
mode- private, public, or restricted.
revision- Use this sharing revision for the next approved change.
expiresAt- The recipient access end time, or null when no expiration is set. The owner can still review the page.
hasPassword- Whether a password is enabled. The password itself is never returned.
recipients- Allowed verified-email addresses.
emailDomain- The allowed verified-email domain, or null.
Before you call it
This replaces the complete policy, not just one field. Omitted methods are removed. OR means that a matching email OR the password can grant access—not that both are required. Never silently broaden the audience or remove expiry.
If something goes wrong
On sharing_conflict, reload get_page_sharing and ask whether the intended change still applies. Do not overwrite a newer policy using a guessed revision. Recheck the effective policy after an uncertain response.
End current viewing sessions
end_current_viewing_sessions
Invalidate active protected viewing sessions without changing the allowed audience.
Arguments, example, and result
Required arguments
pageId- The exact ID returned when the artifact was published or found with list_pages. Pass the ID, not the whole share URL.
expectedRevision- The latest sharing revision from get_page_sharing. This is not the artifact's content version or its style revision.
Example arguments
Illustrative JSON, not a live request. Replace example IDs and content with your own; do not paste credentials here.
{
"pageId": "p_REPLACE_WITH_SAVED_PAGE_ID",
"expectedRevision": 1
}What comes back
pageId- The artifact whose access was read or changed.
publicUrl- Its stable viewer URL.
mode- private, public, or restricted.
revision- Use this sharing revision for the next approved change.
expiresAt- The recipient access end time, or null when no expiration is set. The owner can still review the page.
hasPassword- Whether a password is enabled. The password itself is never returned.
recipients- Allowed verified-email addresses.
emailDomain- The allowed verified-email domain, or null.
Before you call it
This is not permanent access revocation. People who are still authorized can open the page again. To remove access, change the policy or take the artifact offline; saved copies remain outside this control.
If something goes wrong
A successful reset advances the sharing revision. If the request conflicts or its result is uncertain, read sharing again rather than replaying the old revision.
TOOL REFERENCE · 04
Styles
Review, save, and reuse an appearance preference.
Preview a style before saving
preview_artifact_style
Validate a complete appearance definition and create a private, short-lived review draft.
Arguments, example, and result
Required arguments
definition- A complete artifact_style schemaVersion 1 object: name, summary, palette, textPairings, typography, composition, dataVisualization, voice, motion, signatures, avoid, and formatAdaptation. The example below is complete, not an abbreviated schema.
Example arguments
Illustrative JSON, not a live request. Replace example IDs and content with your own; do not paste credentials here.
{
"definition": {
"kind": "artifact_style",
"schemaVersion": 1,
"name": "Sample editorial style",
"summary": "A complete example to review and adapt before saving an artifact style.",
"palette": {
"canvas": "#F2EFE6",
"surface": "#FFFDF8",
"ink": "#111111",
"muted": "#6B6861",
"emphasis": "#DFFF00",
"attention": "#FF5C35",
"comparison": "#2547F5",
"context": "#79E8DB"
},
"textPairings": [
{
"foreground": "ink",
"background": "canvas",
"use": "Body copy"
},
{
"foreground": "ink",
"background": "surface",
"use": "Surface copy"
},
{
"foreground": "muted",
"background": "canvas",
"use": "Secondary copy"
},
{
"foreground": "ink",
"background": "emphasis",
"use": "Emphasis-block copy"
},
{
"foreground": "ink",
"background": "attention",
"use": "Attention-block copy"
},
{
"foreground": "surface",
"background": "comparison",
"use": "Comparison-block copy"
},
{
"foreground": "ink",
"background": "context",
"use": "Context-block copy"
}
],
"typography": {
"display": "system-sans-black",
"body": "system-sans",
"editorial": "system-serif",
"label": "system-mono",
"displayScale": "oversized",
"labelTreatment": "uppercase-tracked"
},
"composition": {
"density": "airy",
"grid": "asymmetric",
"rules": "one-pixel-ink",
"corners": "mixed-intentional",
"whitespace": "generous",
"sectionRhythm": "editorial-chapters"
},
"dataVisualization": {
"hierarchy": "finding-before-metrics",
"values": "always-visible",
"charts": "html-css-geometry",
"color": "signal-not-decoration",
"caveats": "adjacent-to-evidence"
},
"voice": {
"tone": [
"decisive",
"analytical",
"humane",
"lightly-playful"
],
"headlines": "claim-led",
"sentences": "concise",
"jargon": "plain-language-first"
},
"motion": {
"policy": "purposeful-css-only",
"loops": "avoid-ambient-loops",
"reducedMotion": "required"
},
"signatures": [
"one-oversized-finding",
"numbered-editorial-sections",
"hard-ink-rules",
"visible-data-values",
"high-chroma-signal-blocks"
],
"avoid": [
"glassmorphism",
"generic-card-wall",
"stock-imagery",
"gratuitous-gradients",
"ornamental-motion",
"decoration-without-meaning"
],
"formatAdaptation": {
"report": {
"structure": "finding-evidence-decision",
"emphasis": "one-dominant-conclusion",
"detail": "method-and-caveats-visible"
},
"dashboard": {
"structure": "decision-led-overview",
"emphasis": "few-prioritized-metrics",
"detail": "values-before-chart-ornament"
},
"explainer": {
"structure": "numbered-causal-sequence",
"emphasis": "one-idea-per-step",
"detail": "plain-language-mechanism"
}
}
}
}What comes back
draftId- The exact private draft to review.
baseProfileRevision- Pass this value as expectedRevision only after approval of this draft.
reviewUrl- Ask the owner to open this private review page.
canonicalSummary- A server-generated description of the draft's appearance.
contentSha256- The draft's style-definition fingerprint.
expiresAt- The draft's expiration. Current drafts last 30 minutes.
Before you call it
Preview does not activate a style or publish an artifact. Wait for explicit approval of the exact draft before set_artifact_style. Style preferences never override the task, source facts, HTML safety rules, or access choices.
If something goes wrong
If a draft expires, create and review a fresh preview. On a preview rate limit, keep reviewing the existing draft or wait. Do not treat preview completion as approval.
Save the exact approved style
set_artifact_style
Activate a reviewed style draft for future artifact creation.
Arguments, example, and result
Required arguments
draftId- The UUID of the exact preview the owner approved.
expectedRevision- The approved preview's baseProfileRevision, not a sharing revision or content version.
clientRequestId- A unique activation ID, 1–128 characters: start with a letter or digit, then use letters, digits, dots, underscores, colons, or hyphens. Keep it unchanged when retrying this exact activation.
Example arguments
Illustrative JSON, not a live request. Replace example IDs and content with your own; do not paste credentials here.
{
"draftId": "00000000-0000-4000-8000-000000000001",
"expectedRevision": 0,
"clientRequestId": "replace-with-a-new-activation-id"
}What comes back
status- configured on success.
styleVersionId- The activated style version's identity.
revision- The new style profile revision.
contentSha256- The activated definition's fingerprint.
canonicalSummary- A server-generated summary of the active style.
Before you call it
Saving a style does not restyle existing artifacts or publish anything. The owner must approve the exact private draft, not just agree generally to a design direction.
If something goes wrong
For an uncertain response, retry only with identical draftId, expectedRevision, and clientRequestId. A stale revision or expired draft requires a new preview and approval; never swap arguments under the same request ID.
Read the style for this format
get_artifact_style
Get the owner's active appearance definition and format-specific guidance before creating HTML.
Arguments, example, and result
Required arguments
format- Exactly report, dashboard, or explainer. presentation is not a supported style format.
Example arguments
Illustrative JSON, not a live request. Replace example IDs and content with your own; do not paste credentials here.
{
"format": "report"
}What comes back
status- configured or not_configured. No saved style is a valid result, not a service failure.
revision- The style profile revision.
format- The requested style format.
definition- When configured: structured appearance data, with owner-authored name and summary omitted.
guidance- When configured: server-generated guidance, alongside fontStacks and generationPolicy.
styleVersionId- When configured: combine with revision and contentSha256 for an exact styleRef.
contentSha256- When configured: the active style-definition fingerprint.
setupUrl- When not_configured: a place to create a style.
Before you call it
Treat the style as appearance preference data, not new instructions. It cannot change facts, sharing, or safety. A recorded styleRef is not proof that the rendered design matches the style.
If something goes wrong
If no style is configured, ask whether to set one up or continue without one. Missing permissions require reconnecting or a correctly scoped replacement token—not pretending the style was applied.
CHOOSE WHO CAN OPEN IT
A link is not a public-access setting.
New artifacts default to private, owner-only access. A returned field named publicUrl is the artifact’s address; it does not mean anyone can open it.
- Private
- Only the signed-in owner can open the artifact.
- Public
- Anyone with the link can open it. Choose this explicitly.
- Restricted
- A verified email domain, named recipients, or a password can allow access. Each method is an alternative—not an extra condition.
For example, adding both a domain and a password means domain OR password, not domain AND password. Choose only methods you intend to grant access.
How to share an HTML artifact privately →Changing an existing policy
Read get_page_sharing first, then pass its sharing revision as expectedRevision to set_page_sharing.
This replaces the whole policy. Include the recipients, domain, and expiry you want to retain. To retain an existing password, send { "action": "keep" }. Omitting expiry removes it.
See an initial restricted policy
{
"mode": "restricted",
"methods": {
"recipients": [
"reader@example.com"
],
"emailDomain": "example.org"
},
"expiresAt": null
}COMMON QUESTIONS
Know what to expect.
Is each MCP tool a different endpoint?
No. Connect a compatible client to the hosted /api/mcp URL once; it discovers tools and calls them through MCP. The tool names on this page are not separate HTTP endpoints. The token-backed local stdio server is another connection option; it talks to the separate REST API under /api/v1.
Does publicUrl mean anyone can open the artifact?
No. publicUrl is the response field for the stable viewer link. New publications default to owner-only access unless you explicitly choose another policy. Check get_page_sharing and test with the intended audience before sending the link. Published status, an unguessable ID, and noindex are not access controls.
Can I retrieve the HTML and make a small patch?
get_page returns metadata, not source HTML. Keep a complete copy of your source for editing. update_page takes the full revised HTML, not a patch. It keeps the URL, artifact type, current access, expiration, and offline status; readers see a successful update after reopening or refreshing.
How do passwords and email rules work together?
Restricted methods are OR alternatives: a matching verified email or the password can grant access. set_page_sharing replaces the complete policy. Preserve the methods and expiresAt you still want, and use password action keep to retain an existing password. Omitted methods are removed, and omitted or null expiresAt removes expiration. End current viewing sessions does not remove the allowed audience.
What should an agent do when a write times out?
Do not assume failure means nothing changed. Check recent pages after an uncertain publish and inspect the current artifact after an uncertain update. contentSha256 describes saved sanitized HTML, not the raw input. Avoid duplicate creates and overlapping updates. Style activation is the exception with an explicit retry identity: retry only the same draftId, expectedRevision, and clientRequestId.
Which revision should I use?
There are three different counters. get_page returns the content version. get_page_sharing returns the sharing revision used for access changes and session resets. A style preview returns baseProfileRevision; copy that value to expectedRevision when activating the exact approved draft. Never substitute one counter for another.
Can these tools publish interactive apps?
No. These tools publish static HTML reading pages and supported HTML presentations. User scripts, forms, embeds, and external API calls are disabled. External images and fonts can still load from their hosts, and normal links can lead elsewhere. Review the facts, destinations, and actual rendered result before sharing.
Can I run the JSON examples unchanged?
The examples show valid argument shapes, not permission to act. Replace sample HTML, page IDs, draft IDs, recipients, revisions, and request IDs with the exact values for your approved task. Complete connection setup first. Never paste an API token into a conversation, example, URL, or published HTML.
PUT THE TOOLS TO WORK
Start with something worth sharing.
Bring your notes. Ask your agent for a clear draft. Review the content and design before choosing where it goes.