Prismic

Fetch a shared slice's full model (all variations with their primary/items fields) and an `emptyVariations` lookup of ready-to-push slice bodies keyed by variation id. To add a slice to a document: pick an entry from `emptyVariations`, fill in the variation's primary/items fields, and push onto the target slice zone's `value` array via update_document / create_document.

get_shared_slice

List the tags already in use in the repository's asset library, with how many assets carry each. Call this before tagging assets with update_asset_tags or upload_asset, and reuse these names so you extend the repository's existing conventions instead of inventing near-duplicates. Covers asset tags only, not document tags.

list_asset_tags

List all custom types (content models) in the repository. Returns id/label/repeatable/format for each — no field definitions. Call get_custom_type to see the full schema of a specific type.

list_custom_types

List committed live-document changes, newest first, one row per document-publication mapping. Omit documentId for recent changes across the repository. publicationId selects one committed transaction; releaseId selects every publication linked to that release. Bulk jobs can publish one document per transaction and are grouped by bulkJobId. q matches a substring of the release title, case-insensitive, within the last 90 days unless from is set; use it to find a published release, which list_releases no longer shows. authorId filters by the publishing actor. Use get_document_publication with a publicationId and documentId from this list to read the before/after content. Date filters are inclusive ISO-8601 timestamps.

list_document_publications

List a document's current versions (drafts, published, archived, and release versions) plus its history timeline: published versions that went live, and the in-flight draft chain. Use history to pick a previously published versionId for get_document or restore_document_version.

list_document_versions

List all locales configured in the repository. Returns id/label/isMaster for each. Use a locale id when creating a document.

list_locales

List all non-migration releases in the repository, newest first by scheduled timestamp. Use a release id for read/write operations scoped to that release, or create a new one with create_release.

list_releases

List the Prismic repositories this session can access. Returns each repository's name and domain. A signed-in user gets every repository they can access. If a repository domain was already given, pass it to other tools — do not call this first. Use this only to discover repositories when none was given. No parameters needed.

list_repositories

List all shared slices in the repository with their variation names. Light payload — use get_shared_slice for field definitions of a specific slice.

list_shared_slices

Show a publication card for a release you created in this conversation, after you have finished writing documents into it. Call this once writes are done — do not wait for the user to ask, and do not call it for a release you did not create. Do not call publish_release unless the user asks you to. Requires `publicationIntent`: why this release is being published and what should be true afterwards. That intent is recorded if the user publishes.

present_release

Publish a pending release, applying every document version in it to the repository's published content immediately. There is no undo: a later rollback is a new release a human must review and publish. Prefer directing the human to publish from the Prismic dashboard after reviewing the staged changes. Never call this tool on your own — only if the human explicitly asks you to publish via MCP. Summarize the release and confirm before calling. Permissions are enforced server-side — a Publisher (Manager) role is required. Migration releases are not supported via MCP. Requires `publicationIntent`: why this release is being published and what should be true afterwards. The intent is recorded with every published-version change in this publication.

publish_release

Find every document matching structured filters — custom type, locales, statuses, releaseIds, tags, dates, and field values. Unlike `search_documents`, results are exhaustive, not a ranked sample. Reach for this whenever the user asks for documents by a field's value or which documents use an asset. A complete query is the answer — do not follow it with `search_documents` to list or count the type. REQUIRE `where` FOR FIELD VALUES: Most field types are queryable — Select, Text, Color, Boolean, UID, IntegrationFields, Image, Embed, Link, Number, Range, Date, Timestamp and GeoPoint — top-level, inside a group, or inside a slice (its primary or items). Rich Text, Table and Separator support only `has`/`missing`. An Image field path and IntegrationFields match an opaque id (the origin asset id / the integration item id), never a URL. Image alt and credits, and Link labels and variants, are the leaf's `property` member, not part of the path; named thumbnails use the selector below. Number/Range collapse spellings via JS `Number` (`"10"` and `"10.0"` match); Date/Timestamp collapse via `Date` parse to ISO, and Date `eq` needs a full `YYYY-MM-DD` — a year or year-month is INVALID_SHAPE (there is no range operator yet); GeoPoint atoms are `lat,lng` (latitude first, JS `String` of each coord) so `"48.8, 2.3"` matches `"48.8,2.3"` — GeoJSON is longitude-first and will miss. Setting only `scope` and skipping `where` returns every document of that type, which is the wrong answer to a field-value question. BUILDING A PATH (model ids only — never a document's instance keys): 1. Call get_custom_type to find the slice zone's API id (often `slices`, but can be anything) and the slice type id you need. Shared slices appear there as `{type:"SharedSlice"}` stubs. 2. Call get_shared_slice for that slice type to find the field's API id under a variation's `primary` or `items`. 3. Compose the path, dropping `primary`, `items`, and the variation id entirely: - top-level field → `fieldId` - field inside a group → `groupId[].fieldId` - field inside a slice (primary or items) → `zoneId[sliceType].fieldId` - field inside a group that is itself inside a slice → `zoneId[sliceType].groupId[].fieldId` - a nestable LegacySlice that is itself a field → `zoneId[sliceType]` - nested image/embed/link inside Rich Text → append `{image}`, `{embed}`, or `{link}` to the Rich Text path (`body{image}`, `slices[hero].description{image}`, `slices[hero].description{embed}`, `body{link}`, `slices[hero].description{link}`, `slices[rich_text]{link}`) - nested hyperlinks inside a Table → append `{link}` to the Table path (`pricing{link}`, `slices[pricing]{link}`). `{image}`/`{embed}` are invalid on Table. Standalone Image and Link fields do not take a nested selector (`hero_image{link}` and `cta_link{link}` are INVALID_MODEL_PATH). - a named thumbnail on a standalone Image field → `{name}` from that field's `config.thumbnails` (`hero_image{mobile}`). A name that is not `[A-Za-z0-9_-]+` is quoted, which is how whitespace is written: `hero_image{"Mobile 2x"}`. There is no any-thumbnail path — OR the names from the model. Rich Text images have no thumbnails. - image alt and credits, and link labels and variants, are NOT path steps. Keep the Image or Link path and set the leaf's `property` to `alt`, `credits`, `label`, or `variant`: `{ eq: { path: "hero_image", property: "alt", value: "A cat" } }`, `{ missing: { path: "body{image}", property: "credits" } }`, `{ has: { path: "slices[hero].image{mobile}", property: "alt" } }`. - `alt` and `credits` need an Image path, `label` a Link path (standalone or nested), and `variant` a standalone Link field whose model declares `variants`. Nested links have no variant. A property the path cannot carry is PROPERTY_UNSUPPORTED; a variant value outside the declared list is INVALID_SHAPE. - an empty alt, credits, label, or variant is omitted, including on a thumbnail. `has` on `{ path: "hero_image" }` and `missing` on `{ path: "hero_image", property: "alt" }` means the image is set and its alt is empty. A set alt, credits, label, or variant stays queryable when the asset or link target is empty. See WHERE for repeated paths. - there is no star path. To find an asset anywhere, OR every Image field with every Rich Text `{image}` path from get_custom_type and get_shared_slice. A slice that has both an Image field and a Rich Text field needs both: `slices[hero].image` and `slices[hero].description{image}` (real API ids). Querying only the Image field misses documents that embed the asset in that Rich Text. The same OR pattern applies to every Embed field plus every Rich Text `{embed}` path, and every Link field plus every Rich Text/Table `{link}` path. Thumbnails are not included in that asset OR unless you add each `{name}` from the model. EXAMPLES: - top-level Select `theme` → `theme` - group Select `target` in group `nav_items` → `nav_items[].target` - Select `alignment` on shared slice `hero` in zone `slices` → `slices[hero].alignment` - the same field if the zone's API id were `body` instead → `body[hero].alignment` - Select `item_style` in that slice's repeatable items → `slices[hero].item_style` (`items` never appears in the path) - Select `category` in group `questions` on slice `faq` → `slices[faq].questions[].category` - LegacySlice group field `target` on `legacy_nav` → `slices[legacy_nav].target` - nestable LegacySlice Select `color_pick` → `slices[color_pick]` - top-level Boolean `is_featured` → `is_featured` - Link `cta_link` → `cta_link`, matched by target document id, asset id, or external url - asset usage on slice `hero`: OR `slices[hero].image` with `slices[hero].description{image}`. Omitting the `{image}` path misses embeds in that Rich Text. Common mistakes — nested fields ARE queryable, these are syntax errors, not proof otherwise: - `alignment` for a field that actually lives on a slice → PATH_NOT_FOUND (missing `zoneId[sliceType]`) - `slices[hero].primary.alignment` → INVALID_MODEL_PATH (`primary` is never written) - `slices[hero].items.item_style` → INVALID_MODEL_PATH (`items` is never written) - `slices[hero$3f2a].alignment` → INSTANCE_PATH_NOT_ALLOWED (that's a document instance key; use the slice type id) - `body[hero].alignment` when the zone's real API id is `slices` → PATH_NOT_FOUND (wrong zone id) ON ERROR: - PATH_NOT_FOUND, INVALID_MODEL_PATH, INSTANCE_PATH_NOT_ALLOWED mean the path is malformed. Re-check the model and retry with a corrected path — never treat this as proof the field can't be queried, and never fall back to enumerating every document instead. - OPERATOR_UNSUPPORTED means the field type does not accept that operator, and the message lists the ones it does. Rich Text, Table and Separator accept only `has`/`missing` on the field itself — `eq` on `body` is wrong. Nested image/embed/link inside Rich Text uses `{image}`/`{embed}`/`{link}` on that path (`body{image}`), which accept eq/in/has/missing like standalone Image, Embed, and Link. - FIELD_TYPE_UNSUPPORTED means the path resolved to a container (Group, Slices, Choice) rather than a leaf field. Re-check the path — do not treat this as proof the field value cannot be queried. - PROPERTY_UNSUPPORTED means the path is fine but the field there does not carry that property — `alt`/`credits` off an Image, `label`/`variant` off a Link, or `variant` on a nested link or a Link whose model declares no variants. Fix or drop the `property`; do not change the path. - INVALID_SHAPE means the value itself is not a valid form for that field type — a Boolean that is not `"true"`/`"false"`, a Date that is not a full `YYYY-MM-DD` (year or year-month is not a range), a GeoPoint that is not `lat,lng` (latitude first), a `variant` that is not in the model's variant list, an empty string, or a value too long to match exactly. Fix the value, do not change strategy. WHERE: Leaves are `eq`, `in`, `has`, `missing`; each takes a `path` and an optional `property`, and you combine them with `and`/`or` (2+ children each). Requires `scope.customType`. Values are matched exactly after type-specific canonicalize, with no case folding, so `#FFF` and `#ffffff` are different colors. Leading and trailing whitespace is trimmed on Text, Color, Select, Number, Range, Date, Timestamp and GeoPoint. Booleans are `"true"` or `"false"`. Numbers collapse `"10"`/`"10.0"`/`"1e1"` via JS `Number`. Date is a full `YYYY-MM-DD`; `"2026"` or `"2026-08"` is INVALID_SHAPE, not every document in that year/month. GeoPoint is `lat,lng` (latitude first, JS `String` form); a longitude-first GeoJSON pair will not match. An empty value is omitted. On one field, `missing` means that value is empty and `has` means it is set. On a repeated path (a group, slice items, or several values in one Rich Text or Table), `has` means at least one instance is set and `missing` means every instance is empty. One empty instance among filled ones does not match `missing`. Text, the `alt`/`credits`/`label`/`variant` properties, Select, Color, Number, Range, Date, Timestamp, UID, Integration Fields, Embed, an Image id, and a Link target use that rule. `has` on `{ path: "hero_image" }` and `missing` on `{ path: "hero_image", property: "alt" }` means the image is set and its alt is empty. On a repeated image, that matches only when every alt is empty. The same applies to a thumbnail (`{ path: "hero_image{mobile}", property: "alt" }`). A Boolean set to `false` is `has`, not `missing`, and matches `eq` with `"false"`. Rich Text and Table count as filled only when they have visible content, not leftover empty blocks or blank cells. SCOPE: Narrow by `customType`, `locales`, `statuses`, `releaseIds`, `tags`, and date bounds — the tighter the scope, the cheaper the query. `customType` is required whenever `where` is set. `tags` is a catalogue filter, not a field predicate: a document matches when it carries any listed tag. Tags match exactly and are case sensitive, so `launch` does not match `Launch`. The filter combines with `where`. PAGINATION: One HTTP call per invocation — pass the previous response's `page.nextCursor` back as `page.cursor` until `nextCursor` comes back null. `page.limit` is 1–1000 (default 100). A page can hold fewer than `limit` results and still carry a `nextCursor`, including an empty `results` array when every row on the page was stale, so keep paging until `nextCursor` is null. A repository with no ECQ index built yet returns an empty page whose `nextCursor` is null and no error, so retry after indexing rather than concluding there are no matches.

query_documents

Replace a document's entire content in a release with a complete editor-shape DocumentContent. The saved version is exactly what you send — no default-filling — so any field you omit is cleared. `baseVersionId` can point to any version (published, draft, archived, or from any release); the new version lands in the target release branched from that base. Use this when you're writing the document's entire content at once. To change specific fields without rebuilding the whole document, use update_document instead. For a field's exact editor shape, copy it from get_document's `content` or call get_field_shapes. Translation links are fixed at creation: no Prismic API can attach an existing document to a translation group. To link a standalone document, re-create it via create_document with `translationOfDocumentId` (copying its content) and have a human delete the original — the document id changes, so inbound links and history don't follow. If the base version changed, re-read the document and rebuild your content from it before retrying, so the newer change is kept. Recommend human review of the staged changes. When you created the release in this conversation and have finished writing documents into it, call present_release — do not wait for the user to ask, and do not call it for a release you did not create. Do not call publish_release unless the user asks you to.

replace_document

Copy a previously published version's content into a release. Nothing goes live until a human publishes the release. Pass versionId from list_document_versions history (a wentLive item). Rolling back a document's first publication (taking it offline) is not supported yet: tell the human to unpublish it from the Prismic dashboard. By default a document that went live again after versionId is refused, since restoring it would undo those later changes. When rolling back several documents, restore the rest, then list every refused one to the human at once and retry those with hardRollback: true only if they approve. When you created the release in this conversation and have finished writing documents into it, call present_release — do not wait for the user to ask, and do not call it for a release you did not create. Do not call publish_release unless the user asks you to.

restore_document_version

Search the repository's asset library by filename, alt text, notes, and credits, or list the assets carrying given asset tags. Pass both to search within tagged assets. Returns candidates with metadata, asset tags, search highlights showing why each matched, and inline previews — plug `{id, url, width, height}` into `ImageContent.origin` when setting an image field via create_document / update_document. Pass `nextCursor` from a previous call to page through more results.

search_assets

Find documents by meaning, text, UID, or document metadata. Results contain lightweight metadata (id, uid, title, custom_type_id, locale, status, releaseId, tags), not full document content. CHOOSE THE RIGHT TOOL: - Use `search_documents` for semantic discovery ("find documents about pricing"), text or UID lookup, and metadata filters such as custom type, locale, status, tags, or release. - Use `query_documents` whenever the user asks about a field's value, which documents use an asset, or whether a field is filled. It applies exhaustive structured `where` filters to most field types, including nested group and slice fields. - After `query_documents` returns, do not call `search_documents` to list a custom type or to count the repository. The query result is already exhaustive. - Use `get_document` when you need a document's full content or when `query_documents` reports that the requested field operation is unsupported. SEARCH MODES IN THIS TOOL: - `searchMode: "semantic"` finds documents by meaning. It is the default when `term` is set. Results are relevance-ranked samples, never complete lists: there is no `total`, no pagination, and at most `limit` results. - `searchMode: "exact"` matches text or a UID literally, or lists documents selected by metadata filters. Despite its name, it does not filter document field values; use `query_documents` for those. RELIABLE — exact mode with filters gives a COMPLETE, deterministic list: - `searchMode: "exact"` with any combination of `customType`, `locale`, `statuses`, `tags`, `releaseId` (and an empty `term`) lists every document matching those filters. It is a metadata filter, not relevance ranking. - It returns `total` plus `nextCursor`. Page through by passing `nextCursor` back as `cursor` until no `nextCursor` comes back, then check your collected count against `total`. Only then can you claim you have them all. - Looking up one document: exact mode with an id or uid as `term`. - Limit: at most `cap` (1000) documents per query. If `capped` is true there are more matches than you can page through — narrow with filters (e.g. one locale at a time) and say so rather than reporting a partial count as the total. LISTING ONE RELEASE'S CONTENTS: - Pass `releaseId` (from list_releases) to scope results to the documents staged in that release. It overrides `statuses` — you get release-staged documents only. Use exact mode and page through every `nextCursor`, comparing your collected count against `total`. RESULTS ARE PER DOCUMENT VERSION, NOT PER DOCUMENT: - A document can appear more than once — once per status and once per release — so an `id` may repeat and `total` counts versions, not distinct documents. To count or list distinct documents, filter to a single status (e.g. `statuses: ["published"]`) and/or dedupe by `id`. FRESHNESS — the index is eventually consistent, with no guaranteed upper bound: - Writes reach the index through a batching pipeline whose configured windows alone allow ~40s (change capture up to 30s, indexing up to 7s) before embedding and write time. Under load or during a re-index it can be longer — never assume a write is immediately searchable. - So right after a batch (e.g. a localization run staging many documents into a release), a listing may be incomplete. If `total` is lower than expected, wait and retry before concluding documents are missing or failed. VERIFY BEFORE PRESENTING: - Nothing is post-filtered for you: a result only means the index matched your query, not that the document satisfies the user's criteria. Read each result's metadata and, when that is not enough to judge, call get_document before drawing conclusions.

search_documents

Send feedback (bug, feature request, or other) about THIS Prismic MCP server to the Prismic team. Every call requires explicit human approval — the gate is non-negotiable, but you may be the one who spots the issue. SCOPE — only call about: - This MCP server's tools, schemas, errors, or behavior - Prismic itself (custom types, slices, documents, releases, locales, assets) as surfaced through this server - Missing capabilities you needed to complete a Prismic task Do NOT call about: the LLM/Claude itself, the user's own application code, third-party tools, general programming questions, or anything not specifically about Prismic or this MCP server. If the issue is out of scope, just answer the user normally — do not invent a feedback channel. WORKFLOW (both paths require the same human validation): Path A — user-initiated: the user complains about a Prismic / MCP issue. Path B — model-initiated: while doing the user's actual task you notice a concrete problem (a tool returns confusing output, a needed field is missing, an operation fails repeatedly with the same error). You may proactively propose feedback in this case. Then in BOTH paths: 1. Surface a one-paragraph summary in chat: "I noticed / you reported <problem>. I'd send this to the Prismic team as a {bug|feature_request|other}: '<summary>'. OK to report?" 2. Only after the user explicitly confirms ("yes", "send it", "report it", or equivalent) do you call this tool with userConfirmed=true. 3. If the user says no or ignores the suggestion, drop it — do not ask again in the same session, and do not bundle it into a later confirmation. Quote the user's own words in `details` when they reported it; otherwise describe the problem concretely (which tool, which input, what unexpected outcome). Always set `toolContext` to the tool / repository / step the issue relates to when you have it. Returns a short acknowledgement. The team triages internally; no ticket id is exposed to the agent.

submit_feedback

Add or remove tags on assets in the repository's asset library. Covers asset tags only. Document tags are set with the `tags` argument of update_document. Each name uses the tag with exactly that name, or else the one tag that differs only in case, so "hero" adds an existing "Hero" tag. An added name that matches no tag becomes a new tag. Call list_asset_tags first to reuse the repository's names. Pass at most 10 names across `add` and `remove` in one call. To tag an image while uploading it, pass `tags` to upload_asset instead. Repeating a call is safe. Tags cannot be deleted or renamed here, so a tag removed from every asset stays in list_asset_tags with a count of 0.

update_asset_tags

Update a document by changing only the parts you name — you never rebuild the whole document. Everything you don't touch is preserved from `baseVersionId`; the new version lands in the target release branched from that base. `updates` — a map of path → editor-shape value. Use the exact paths get_document returns in its `paths` list rather than composing them by hand — the names below are each field's API id in the type (which varies; don't assume any particular name). Path shapes: - a top-level field: `<field>` - a field inside a slice: `<sliceZone>[<sliceKey>].<field>` - a field inside a group item: `<group>[<itemKey>].<field>` - a whole slice `<sliceZone>[<sliceKey>]` or a whole group item `<group>[<itemKey>]` (replaces it, keeping its position) The value replaces what's at the path; a field allowed by the type but not yet on the document is added. Never target a container that holds items: a slice zone (`<sliceZone>`) or a group field (`<group>`, or `<sliceZone>[<sliceKey>].<group>`). Assigning to one replaces the entire list and drops every item you did not re-send, so it is rejected while the container has items. Removing one slice from a zone, or one item from a group, is a `deletes` call on that item's own path, never a rewrite of the container around it. Reach for the narrowest path that covers your change, and prefer several small ops over one large value. Repeatable Link/Image/Select fields and Table fields work the other way: get_document lists the field but not paths for its individual entries, so there is nothing to address with `deletes` and you do change one entry by sending the whole field in `updates`. If `paths` has no entry for the thing you want to remove, replacing its parent field is the intended route. `deletes` — a list of paths to clear (same path forms). Clearing a field removes it — the only way to clear fields with no empty value, such as images and links. A slice path removes that slice; a group-item path removes that item from its group. Slice keys are the `<sliceId>$<uuid>` strings and group-item keys the `<uuid>` strings shown by get_document; copy the exact editor-shape value get_document returns at a path and change only what you need (the `__TYPE__`/`type` discriminators are easy to get wrong). For a field/slice not yet on the document, get its shape from get_field_shapes / get_shared_slice. Items are added and reordered structurally (paths can't express insert/reorder). A `container` is a slice zone (`<sliceZone>`), a group field (`<group>`, or `<sliceZone>[<sliceKey>].<group>` inside a slice), or a slice's repeatable zone (`<sliceZone>[<sliceKey>]`) — each named by its API id from get_document: - `inserts` [{container, item, afterKey?, beforeKey?}] — add an `item` to a container: a slice item `{name, widget}` for a slice zone (clone get_shared_slice's emptyVariations), or a group item for a group. Omit both anchors to append at the end. The server assigns the new key and returns it. - `reorders` [{container, keys}] — `keys` lists all of the container's current item keys in the new order. Within one call: `updates` then `deletes` apply first, then `inserts`, then `reorders` — so a reorder's keys must match the container's items after any deletes, and don't reorder a container in the same call you insert into it. If the base version changed, re-read the document and retry. Recommend human review of the staged changes. When you created the release in this conversation and have finished writing documents into it, call present_release — do not wait for the user to ask, and do not call it for a release you did not create. Do not call publish_release unless the user asks you to. Every rejection names what was wrong and whether retrying can help. A rejected payload is rejected deterministically: resubmitting it unchanged fails identically, so change the payload (or re-read the document) first — the rejection says so when it applies. Before applying one change shape across many documents, prove it on a single document with `dryRun: true`, which runs every check a real call runs and writes nothing. To make an existing document a translation of another, you can't do it here — translation links are fixed at creation. Re-create it via create_document with `translationOfDocumentId` (copying its content) and have a human delete the original; the document id changes, so inbound links and history don't follow. To replace a document's entire content in one payload (e.g. a regenerated or externally-sourced document), use replace_document instead.

update_document

Fetch an asset from a public URL and upload it to the repo's asset library; returns `{id, url, width, height}` for `ImageContent.origin` in create_document / update_document. Before uploading, use search_assets to check whether the given asset already exists to prevent duplication. `url` is fetched server-side over HTTPS, so inline/pasted images, local files, and data/blob URIs won't work — host those first (don't ask the user). Upload to a temp file host that returns a direct file URL (e.g. tmpfiles.org), then pass that URL. When your client auto-fills `file` from a user upload, use it as-is — no hosting needed; don't construct `file` yourself.

upload_asset