Aem MCP Author Onboarding

AEM MCP Assistive Controls

Source: "Rolling Out MCP on AEM: Lessons from Early Production" — Pranay Rajput (Pitney Bowes) & Divanshu Goyal (TechX), adaptTo() 2026, and Adobe's own MCP docs (Using MCP with AEM as a Cloud Service). MCP does not add permissions — it operates under the author's existing ACLs — but it acts on those permissions literally, at machine speed, with none of the judgment a human author brings. This skill is the assistive layer that goes with the access: shared starting point, same baseline every time, instead of five authors improvising five different approaches (some unsafe).

1. Narrate every action in plain language

Authors think about their work differently from developers — a tool name and a status code don't tell them what actually happened. Before and after every AEM MCP action, say what you're doing in the author's terms, not the API's:

• Before a write: "I'm about to update <page/path> — this will replace the current content on that path." Not just "calling patch_fragment."
• After success: confirm what changed, in one line, in plain language.
• After any failure: explain what the error means for them (see the 412 handling below), not just the raw error text.

Never let an author be left staring at a raw tool error with no interpretation. If you don't know what an error means, say that plainly and escalate rather than guessing.

2. Safe tool sequence — always read before you write

AEM's MCP tools are built around a read-then-write pattern; never skip the read to save a step. For pages: get-aem-page-content before any patch. For fragments: resolve_fragment_path → get_fragment (this is also where the current ETag comes from) → build the change → patch_fragment with that ETag. For a new fragment, check list_models / get_model first so the content actually matches the model's schema instead of failing (or worse, partially writing) on a mismatch.

Skipping straight to a write tool without the matching read tool first is never correct — you won't have a valid ETag, and you're guessing at the current state instead of confirming it.

3. ETag / HTTP 412 handling — never retry blindly

AEM uses ETags for optimistic concurrency control. Every write carries the ETag captured in step 2, in If-Match. HTTP 412 means someone else changed that content since it was last read.

• Never automatically retry a failed write after a 412. Re-reading a new ETag and resubmitting the same payload silently overwrites whatever the other change was — there is no warning banner, the later write just wins. Automated retry on a version conflict is how silent data loss happens.
• On 412: stop immediately, tell the author in plain terms ("this content changed since we last looked at it — I stopped before overwriting anything"), and if possible show them what the current content looks like now versus what they intended.
• Let the author decide next: redo the edit against the current content, drop it, or go find out who else is editing that path. That decision is always theirs, never a default you pick for them.

4. Read-only on production, ACL check before any write

• Default to read-only tools on production (aem-content-read-only, or the read-only scope of the unified server). Only reach for a write tool (patch_fragment, create_fragment, put/delete page operations) when the author has explicitly asked for that specific change — never chain an unrequested write off the back of a read, and never use write access on production "since it's available" during exploration or debugging.
• ACL check before write, every first touch. The first time in a session you're about to write to a given content path — especially one that looks old, unfamiliar, or outside what this author normally touches — pause and confirm scope with the author before writing: "this path doesn't look like one you've touched before, do you want me to proceed?" Permission debt is real (stale group memberships from finished projects stay active for years) and MCP will use every permission it's handed without judging whether it should. This one check is what catches that before it becomes an incident.
• Never invoke aem-cloud-manager, aem-quickstart, or aem-dispatcher on an author's behalf — those are operator/developer tools, not part of an author's job regardless of what the credential technically allows. If a task seems to need one, tell the author this looks like it needs a developer/operator, don't reach for the tool because it happens to be reachable.
• If a call against an out-of-scope server, an unexpected path, or a production write succeeds when it shouldn't have, don't treat that as a green light — flag it to the author as a likely permissions/ACL issue rather than using it.

The one-line test

Before any write: have I read this path first in this session, do I have a current ETag, and would the author understand right now what I'm about to change and why? If any answer is no, stop and do that first. Before any retry: am I about to resubmit a write after a 412? If yes, stop instead.