07-ai-assistant.md
AI assistant support
Mason can describe itself to an AI assistant — Claude Code, Claude Desktop, Cursor, Codex or anything else that speaks the Model Context Protocol (MCP).
This matters because of where Mason keeps things. Your bricks are defined in the database, not in files, so an assistant reading your templates has no way to know that {brick:heading} is valid for one brick and meaningless for another. It will guess, and guesses look plausible. With these tools it reads your actual brick library instead.
There are two ways to connect, and which you want depends on whether the site is on your machine or someone else's server.
Locally — via ExpressionEngine's MCP Server
- Install ExpressionEngine's MCP Server add-on. Mason's tools are discovered automatically once it's present — there is nothing to configure in Mason.
- Start the server:
php system/ee/eecli.php mcp:serve - Point your assistant at it. The MCP add-on's
mcp:installcommand writes the configuration for common editors.
This needs shell access and a long-running process, so it suits local development.
Note: ExpressionEngine's MCP Server is currently in beta. Mason's tools are read-only and cannot change your content, but the server itself is young.
Remotely — via Mason's own HTTP endpoint
Plenty of hosting gives you no SSH, a different PHP CLI, or no way to keep a process running — so the above simply isn't available on a lot of client sites. Mason therefore serves the same tools over an ordinary authenticated web request. No terminal, and ExpressionEngine's MCP Server add-on isn't required at all.
It is off until you give it a token. Until then the endpoint returns 404 and is indistinguishable from an add-on without the feature.
-
Add a long random token to
system/user/config/config.php:$config['mason_mcp_token'] = 'a-long-random-string';The
MASON_MCP_TOKENenvironment variable works too, and is used if the config value is absent. -
Open Mason → AI Access in the control panel. It shows the endpoint URL for this site (an
?ACT=address) and confirms the endpoint is live. -
Point your assistant at that URL, sending your token as
Authorization: Bearer <token>.
The token is kept out of the database deliberately, so a database dump cannot leak it. Remove it to switch the endpoint off again.
Use HTTPS. The token is sent with every request. On a site without TLS it crosses the network in clear text, and anyone who captures it gains everything below. The AI Access screen warns you if the site isn't on HTTPS.
What it exposes
Everything is read-only — nothing can change content, bricks or settings, so a leaked token cannot be used to alter the site. It can still read:
- your brick and field definitions (structure, not content)
- via
mason_render_preview, the rendered content of an entry you name
Treat the token as you would a database password. If you only need structure, the endpoint is far less sensitive than a CMS login; but it is not nothing.
What the assistant can do
| Tool | What it answers |
|---|---|
mason_list_bricks |
Which bricks exist, their fields and kinds |
mason_get_brick |
One brick in full — every field, including those from a bound binder, and the exact tokens each produces |
mason_validate_template |
Whether markup matches a brick's real schema |
mason_list_fields |
Which channel fields use Mason, their editor mode, toolbar and assigned bricks |
mason_render_preview |
The HTML an entry's field actually outputs |
Mason also exposes its documentation at mason://docs, and a mason_write_brick_partial prompt that drafts a partial from a brick's real fields.
Everything is read-only. Nothing here can edit content, bricks or settings.
Where it helps most
A brick renders as nothing. Mason fails quietly by design — a token naming a field that doesn't exist renders as empty, and an unclosed loop swallows the rest of the partial. Neither produces an error anywhere, so the symptom is usually "part of my template just isn't there". Ask the assistant to run mason_validate_template on the brick; it will name the exact token.
Writing a new partial. mason_get_brick gives the real token list up front — including sub-variables like {brick:image:url} and the row variables available inside Grid and Listing loops — so the markup is written against the schema rather than against a guess.
A brick is missing from a page. mason_list_fields shows which bricks each field offers, and flags assignments pointing at bricks that no longer exist. Those resolve to nothing with no sign on the page.
Telling a template bug from a data problem. mason_render_preview renders one entry's field without loading a page. If the partial looks right but the output is empty, the content is the cause.
Example
"Why is the testimonials brick not showing quotes on entry 1084?"
A capable assistant will call mason_get_brick for the field names, mason_validate_template to check the partial's tokens against them, and mason_render_preview to see what that entry actually produces — then tell you which of the three is wrong.