AlphaBridge MCP for Craft CMS
From an empty Craft installation to a connected AI client, and every setting that decides what that client may do.
1. Install
Not installable yet. The Craft Plugin Store listing is being prepared, and until it is live the package cannot be resolved — the two commands below will not find it. They are here so you can see what installing will look like.
composer require alphabridge/mcp php craft plugin/install alphabridge-mcp
The migration creates two tables, alphabridge_tokens and alphabridge_audit. Uninstalling removes them again and leaves nothing behind:
php craft plugin/uninstall alphabridge-mcp
Requirements: Craft CMS 5.9+, PHP 8.2+, MySQL 8.0.17+ / MariaDB 10.4.6+ or PostgreSQL 13+.
2. Create a token
In the control panel, open AlphaBridge MCP in the sidebar. The page is open to administrators only. Choose the Craft user the token belongs to, a scope, a label so you recognise it later, and an optional lifetime in days.
The plain-text token is shown exactly once, right after you create it. Only its SHA-256 hash is stored, so it cannot be shown again. Copy it before you leave the page; if you lose it, revoke it and create a new one.
The same works from the console, which is useful for scripted setups:
php craft alphabridge-mcp/tokens/create --user=admin --scope=read --label="Claude Desktop" php craft alphabridge-mcp/tokens/list php craft alphabridge-mcp/tokens/revoke 1
--expires-in-days=30 limits a token's lifetime; 0, the default, means no expiry.
What a scope means
A token is mapped to exactly one Craft user and works with that user's permissions. The scope narrows further; it never widens.
| Scope | Allows |
|---|---|
read | The reading tools, without the administrator tools. Changes nothing. |
content | The reading tools, plus writing entries, drafts, categories and globals. Still without the administrator tools. |
full | Everything the mapped user may do, including the administrator tools: schema fields, system info, audit log, database, logs, caches, routes, queue, plugins, user groups. |
3. Connect a client
The endpoint is POST https://your-site.example/alphabridge/mcp — JSON-RPC 2.0 over Streamable HTTP, protocol versions 2025-03-26 and 2025-06-18. The token travels in a header:
X-Api-Key: abmcp_… works as well. Any MCP client that speaks Streamable HTTP and can send a custom header can connect.
Claude Code
One command:
claude mcp add --transport http craft https://your-site.example/alphabridge/mcp \ --header "Authorization: Bearer abmcp_…"
Claude Desktop · Cursor
Add this to the client's MCP configuration. The token sits in an environment variable so it does not end up in the file that gets shared:
{ "mcpServers": { "craft": {
"command": "npx",
"args": ["mcp-remote", "https://your-site.example/alphabridge/mcp",
"--header", "Authorization:${AUTH}"],
"env": { "AUTH": "Bearer abmcp_YOUR_TOKEN" }
}}}
Clients that can only put the token in the URL
Some clients accept a connector URL but no custom header. For those there is a second endpoint that carries the token in the path — switched off by default. Turn on Allow the token in the URL path in the settings first, and understand the trade: a token in a path lands in server logs, proxy logs and referer headers far more easily than one in a header.
4. Settings
In the control panel under Settings → Plugins → AlphaBridge MCP.
- Read-only mode — while this is on, no tool that changes anything will run. It sits above every other switch.
- Tools — every tool is Default (on), Default (off), On or Off. Tools that change state are off by default. Default is a state of its own, not a synonym for on or off: a later version may reclassify a tool, and a site that chose Default follows that reclassification instead of freezing an old decision.
- Calls per minute and token — a brake against a looping model. It is not a defence against a determined caller who holds a valid token.
- Allow the token in the URL path — off by default, see above.
- Additional allowed origins — for browser-based clients, see below.
The same settings can be set in config/alphabridge-mcp.php. A value set in the file wins over the control panel, and the settings page marks each affected field and says where its value comes from.
return [
'readOnly' => false,
'rateLimit' => 120,
'connectorUrlAuthEnabled' => false,
'allowedOrigins' => ['https://client.example', '$MCP_ALLOWED_ORIGINS'],
'toolState' => ['craft_create_entry' => true],
];
Tokens are deliberately not part of the settings: they are secrets, and plugin settings live in the project config, which is committed to Git. Tokens have their own page instead.
Origins and DNS rebinding
If a client sends an Origin header, it must be on the allowlist or the endpoint answers HTTP 403. The allowlist is the configured allowedOrigins plus the site URL — but only where those can be determined statically: a fixed URL with scheme and host, possibly held in an environment variable that contains such a URL. Exactly one level is resolved.
A site URL built from a Craft alias such as @web does not count, not even inside an environment variable. Craft builds @web from the Host header of the incoming request, so an attacker would be compared against themselves. In such installations allowedOrigins is the only source; if it is empty, every request carrying an Origin is refused. Server-to-server clients send no Origin and are unaffected.
5. Licence and trying it out
The plugin is sold through the Craft Plugin Store under the Craft License: one licence per production environment. The store listing is being prepared; until it is live the plugin is not purchasable there. Development and staging environments are free to try — that is part of the Craft License, not a trial we grant.
6. When something does not work
| What you see | What it means |
|---|---|
| 401 | The token is missing, unknown, expired or revoked. Check that the header really arrives — some proxies strip Authorization. Create a fresh token to rule out a typo; the plain text is shown only once, so a partial copy is a common cause. |
| 403 | An Origin header was sent that is not on the allowlist. See Origins. Server-to-server clients send no Origin at all. |
| Unknown tool | Either the name does not exist, or the token's scope does not cover it. These two are answered identically on purpose: the difference would tell a caller what else is there. |
| A refusal that names its reason | Read-only mode is on, the tool is switched off in the settings, or it is an administrator tool and the mapped user is not one. Here the answer says which, so you do not look for the fault on your own side. Such tools are also absent from the tool list. |
| Rate limit | More calls per minute than the setting allows, counted per token. Raise the limit or slow the client down. |
| Empty list | Not an error. The mapped user may not view that section or category group — an unknown or forbidden one yields an empty list rather than an error that would reveal it exists. A site handle that does not exist is reported as an error instead. |
The audit log records every call with its outcome. Read it with the craft_audit_log tool (administrator scope) to see what a client actually did.
Next: the full tool reference, generated from the plugin's own registry, and how the security chain works.