Giving Craft CMS Content Managers MCP Access, Safely

Craft CMS 5.12 added a built-in MCP server. That means staff can connect Claude (or any other MCP client) to the control panel and ask it to do things: “update the hours on these five listings”, “find every event missing an image”, “draft a page for the summer fest”.

The client’s staff wanted to have it, but this is a non-profit site where the public writes a good chunk of the content, so it had to be clear that an agent couldn’t break anything before anyone was invited to connect.

Below is what Craft protects out of the box, what it leaves open, and the small module that closes the gap.

Table of Contents

Start with the threat model

The most important thing to understand about Craft’s MCP server is this: an agent gets no extra powers. Every tool runs as the signed-in user, and Craft checks that user’s normal permissions on every call. If a person can’t delete an entry in the control panel, their agent can’t either.

That leaves three ways an agent could break the site:

  1. A mistake made fast and many times over. A bulk edit run on a misread instruction can do in seconds what would take a person an afternoon.
  2. Prompt injection. Business listings, form submissions and other text written by the public get read by the agent. Some of it could be written to look like instructions.
  3. A stolen token. Whoever holds it can do what the staff member can.

In each of these, the agent does something the person could do but wouldn’t. The useful question to ask is which of the things staff can do should an agent be allowed to do.

What Craft already protects

Craft already handles a fair amount on its own:

  • Only control panel users can connect. The endpoint lives at /admin/mcp and goes through the normal control panel checks. Front-end users can’t use it.
  • Public MCP is off by default. The publicEnabled setting stays off unless you turn it on.
  • Admin-only tools are hidden from everyone else. Project config, plugins, fields, sections, settings and system status need an admin account and the mcp:admin token scope, which non-admins can never get.
  • allowAdminChanges still applies. It’s off in production on any sensibly configured site, so schema and plugin changes are off the table even for admins.
  • People can’t hand out permissions they don’t have. The permission tools reject anything the assigning user lacks.
  • Staff can pick “Read only” on the consent screen. That’s their choice, though. You can’t force it.

What’s still open

The catch is that a person can often do a lot. The site’s Managers group has around 330 permissions (Managers run the site day to day), so an agent acting for a Manager could reach these tools:

Tool Risk
elements_delete with hardDelete: true Permanently deletes entries, assets or users (users are elements too), skipping the trash.
queue_release_all Removes waiting and failed jobs without running them. Search indexing or payment sync could silently drop.
queue_run, queue_retry_all Lower risk, but an agent can loop on them.
caches_clear with no keys Clears every cache. Nothing is lost, but the server takes a load spike while they rebuild.
user_permissions_user_set / _update Can grant other users anything the Manager has, which makes it the obvious target for prompt injection.

Craft also has no setting for who may use MCP, so anyone with accessCp can authorize a client.

What Craft does give you is a hook. Setting $event->allowed = false on Mcp::EVENT_DISCOVERING_CAPABILITY hides a tool, resource or prompt from the current user, since Craft fires the event once for each of them. Everything else is built on that event.

Rule 1: decide who sees which tools

Three rules decide who sees what:

  • Admins get everything Craft offers them.
  • Managers get everything in development, and only content tools in production.
  • Everyone else gets nothing.

The rules live in a small class with no Craft dependencies, which makes them easy to unit-test:

final class McpAccess
{
    public const MANAGERS = 'managers';

    /** Content tools Managers keep in production. An allowlist, so tools added by updates stay hidden. */
    public const CONTENT_TOOLS = [
        'info_get', // Craft's server instructions tell agents to call it first
        'elements_schema', 'elements_field_schema', 'elements_list', 'elements_get', 'elements_validate',
        'elements_create', 'elements_update', 'elements_duplicate', 'elements_delete', 'elements_restore',
        'drafts_list', 'drafts_create', 'drafts_apply', 'drafts_delete',
        'revisions_list', 'revisions_get', 'revisions_apply',
        'assets_create', 'assets_replace', 'assets_upload_url', 'assets_transform_url',
        'asset_folders_list', 'asset_folders_get', 'asset_folders_create', 'asset_folders_update', 'asset_folders_delete',
        'structures_move_element', 'search_query',
        'navigation.menus.list', 'navigation.menus.tree', 'navigation.nodes.move',
    ];

    /** Resources and resource templates the content tools link to. */
    public const CONTENT_RESOURCES = [
        'craft-element-types', 'craft-element-types-get', 'craft-entries-get', 'craft-assets-get',
    ];

    public static function allows(bool $admin, bool $manager, bool $production, string $name): bool
    {
        if ($admin || ($manager && !$production)) {
            return true;
        }

        return $manager && in_array($name, [...self::CONTENT_TOOLS, ...self::CONTENT_RESOURCES], true);
    }
}

The most important choice here is using an allowlist. Craft and its plugins will keep adding MCP tools (Navigation already registers its own), and a blocklist would let any of those updates quietly hand Managers a new tool. With the allowlist, a new tool stays hidden in production until someone adds it on purpose.

The listener in the module’s init() pulls the name off whatever Craft is discovering and asks McpAccess about it:

Event::on(
    Mcp::class,
    Mcp::EVENT_DISCOVERING_CAPABILITY,
    function (DiscoveringCapability $e) {
        $ref = $e->reference;
        $name = match (true) {
            $ref instanceof ToolReference => $ref->tool->name,
            $ref instanceof ResourceReference => $ref->resource->name,
            $ref instanceof ResourceTemplateReference => $ref->resourceTemplate->name,
            $ref instanceof PromptReference => $ref->prompt->name,
            default => '',
        };
        $e->allowed = $e->allowed && McpAccess::allows(
            (bool) $e->user?->admin,
            (bool) $e->user?->isInGroup(McpAccess::MANAGERS),
            Craft::$app->env === 'production',
            $name,
        );
    }
);

The $e->allowed && … means the listener can only take tools away and never overrides Craft’s own decision to hide something.

Rule 2: no hard deletes over MCP

elements_delete stays on the allowlist, since deleting content is a normal content task. It also takes a hardDelete flag that skips the trash and can’t be undone, so in production only admins can do that through MCP. Everyone else can still soft-delete, and anything an agent removes by mistake can be restored from the trash.

/** Hard deletes skip the trash, so in production only admins may make them through MCP. */
public static function allowsHardDelete(bool $admin, bool $production): bool
{
    return $admin || !$production;
}

The listener enforces it:

// Element's own event, because Elements::EVENT_BEFORE_DELETE_ELEMENT ignores isValid.
Event::on(
    Element::class,
    Element::EVENT_BEFORE_DELETE,
    function (ModelEvent $e) {
        $element = $e->sender;
        // tokenScopes is set only on requests an MCP access token authenticated. Craft
        // hard-deletes drafts and revisions itself (applying a draft does), so those pass.
        if ($element->hardDelete && !$element->getIsDraft() && !$element->getIsRevision() && Craft::$app->get('mcp')->tokenScopes !== null) {
            $user = Craft::$app->getUser()->getIdentity();
            $e->isValid = $e->isValid && McpAccess::allowsHardDelete((bool) $user?->admin, Craft::$app->env === 'production');
        }
    }
);

Two details in that listener are worth calling out:

  • tokenScopes !== null marks an MCP request. Craft only sets it when an MCP access token authenticated the request, so normal control panel use is untouched.
  • Drafts and revisions have to pass through. Craft hard-deletes the draft itself when you apply one, so blocking those deletes would leave every draft an agent applies behind as a ghost.

The comment on the listener’s first line has a story behind it.

The bug the test caught

The first version (built with Claude Code) listened on Elements::EVENT_BEFORE_DELETE_ELEMENT, the service-level event, which has an isValid property and looks like exactly the right one. The unit tests for McpAccess passed, the full suite passed and PHPStan reported no errors.

A review then flagged the draft problem above (the listener would block Craft’s own draft cleanup), which was a fair catch. The fix came with a functional test that acts as a Manager on a production MCP request and checks three things:

it('refuses a Manager hard-deleting an entry over MCP', function () {
    $entry = Entry::factory()->section('pages')->create();

    expect(Craft::$app->getElements()->deleteElement($entry, true))->toBeFalse()
        ->and(EntryElement::find()->id($entry->id)->status(null)->exists())->toBeTrue();
});

it('still lets a Manager soft-delete an entry over MCP', function () {
    $entry = Entry::factory()->section('pages')->create();

    expect(Craft::$app->getElements()->deleteElement($entry))->toBeTrue();
});

it('removes the draft when a Manager applies it over MCP', function () {
    $entry = Entry::factory()->section('pages')->create();
    $draft = Craft::$app->getDrafts()->createDraft($entry, Craft::$app->getUser()->getId());

    Craft::$app->getDrafts()->applyDraft($draft);

    expect(EntryElement::find()->draftId($draft->draftId)->status(null)->exists())->toBeFalse();
});

The hard-delete test failed, and the draft test passed even with the draft fix removed.

It turns out Elements::EVENT_BEFORE_DELETE_ELEMENT ignores isValid, so the delete goes ahead whatever the listener sets. The hard-delete block had never worked, which is also why the draft bug from the review couldn’t happen. Moving to Element::EVENT_BEFORE_DELETE (which does respect isValid) made the block work, and from then on the draft test failed whenever the draft exception was removed.

A security rule needs a test that drives the real framework. The unit test checked the yes/no logic perfectly, but it had no way to show that Craft never asked for an answer. Each new test also had to fail once (with the code it guards removed) before it was trusted.

Rule 3: hands off other people’s accounts

Users are elements in Craft, so the content tools work on user accounts too. A Manager’s agent could edit, create or soft-delete any user (including the business owners in the members directory), and an injected prompt could ask it to. Managers can already do all of that by hand, but none of it needs to happen at agent speed.

In production, a non-admin’s MCP request can now change only their own account:

/** In production, non-admins may change only their own account through MCP, not create or edit others. */
public static function allowsUserChange(bool $admin, bool $production, ?int $actorId, ?int $userId): bool
{
    return $admin || !$production || ($actorId !== null && $actorId === $userId);
}

The listener runs before every save and delete of a user, and of an address too, since addresses are separate elements that belong to a user’s account:

// Users, and the addresses on their accounts, can't be changed over MCP by anyone else.
$guardUsers = function (ModelEvent $e) {
    $element = $e->sender;
    $target = $element instanceof Address ? $element->getOwner() : $element;
    if (!$target instanceof User || Craft::$app->get('mcp')->tokenScopes === null) {
        return;
    }
    $actor = Craft::$app->getUser()->getIdentity();
    if (!McpAccess::allowsUserChange((bool) $actor?->admin, Craft::$app->env === 'production', $actor?->id, $target->id)) {
        $element->addError('id', 'Only admins can change other users through MCP.');
        $e->isValid = false;
    }
};
foreach ([User::class, Address::class] as $class) {
    Event::on($class, Element::EVENT_BEFORE_SAVE, $guardUsers);
    Event::on($class, Element::EVENT_BEFORE_DELETE, $guardUsers);
}

A new user has no ID yet, so $actorId === $userId is false and creating users is refused as well. The addError() call gives the agent a reason it can report back to the person, instead of a save that silently fails.

This rule got the same treatment as the delete rule: functional tests for changing another user, creating a user, adding an address to someone else’s account and editing your own. Each refusal test was run once with the guard switched off, to prove it fails for the right reason and not because of some unrelated validation error.

Connecting staff

With the rules in place, connecting is the easy part. Staff add the site as a custom connector in Claude Desktop (Settings → Connectors → Add custom connector) pointing at https://your-site.com/admin/mcp. They then sign in with their normal control panel account and approve the connection on Craft’s consent screen, which defaults to Read only. Anyone who wants to cut off a connection later can revoke its token under My Account → Tokens.

Before sending the instructions out, connect once with a real Manager account. Tools like caches_clear, queue_release_all and user_permissions_user_set should be missing, and content tools like elements_list should be there. An admin account shows every tool either way, so it can’t confirm anything.

What’s still not covered

A few known gaps are acceptable for now. Craft may keep each person’s tool list for the length of their MCP session, so changing someone’s group probably won’t take effect until their client reconnects (that hasn’t been tested yet). The functional tests also fake the token scopes and the signed-in user in-process, which proves the listeners work but leaves the full OAuth flow untested.

Backups matter too, since the trash only helps with deletes. Before inviting staff, check that your host runs scheduled database backups on top of the one that runs on deploy.

The whole change is three listeners, one small class and their tests. If you’re about to turn on Craft’s MCP server for your team, start by asking which of the things each person can do should happen at agent speed. Craft already makes sure the agent can’t do more than the person.