Configurare il server MCP per Craft CMS.

1. Installazione

Non ancora installabile. La scheda sul Craft Plugin Store è in preparazione e, finché non sarà online, il pacchetto non può essere risolto — i due comandi qui sotto non lo troveranno. Sono qui perché tu veda come sarà l'installazione.

composer require alphabridge/mcp
php craft plugin/install alphabridge-mcp

La migrazione crea due tabelle, alphabridge_tokens e alphabridge_audit. La disinstallazione le rimuove e non lascia nulla:

php craft plugin/uninstall alphabridge-mcp

Requisiti: Craft CMS 5.9+, PHP 8.2+, MySQL 8.0.17+ / MariaDB 10.4.6+ o PostgreSQL 13+.

2. Crea un token

Nel pannello di controllo, apri AlphaBridge MCP nella barra laterale. La pagina è accessibile solo agli amministratori. Scegli l'utente Craft a cui appartiene il token, un ambito, un'etichetta per riconoscerlo in seguito e una durata facoltativa in giorni.

Il token in chiaro viene mostrato una sola volta, subito dopo la creazione. Viene salvato solo il suo hash SHA-256, quindi non può essere mostrato di nuovo. Copialo prima di lasciare la pagina; se lo perdi, revocalo e creane uno nuovo.

Lo stesso funziona dalla console, utile per configurazioni tramite script:

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 limita la durata di un token; 0, il valore predefinito, significa nessuna scadenza.

Cosa significa un ambito

Un token è associato esattamente a un utente Craft e funziona con i permessi di quell'utente. L'ambito restringe ulteriormente; non allarga mai.

3. Collega un client

L'endpoint è POST https://your-site.example/alphabridge/mcp — JSON-RPC 2.0 su Streamable HTTP, versioni del protocollo 2025-03-26 e 2025-06-18. Il token viaggia in un header:

Funziona anche X-Api-Key: abmcp_…. Qualsiasi client MCP che parli Streamable HTTP e possa inviare un header personalizzato può collegarsi.

claude mcp add --transport http craft https://your-site.example/alphabridge/mcp \
  --header "Authorization: Bearer abmcp_…"

{ "mcpServers": { "craft": {
  "command": "npx",
  "args": ["mcp-remote", "https://your-site.example/alphabridge/mcp",
           "--header", "Authorization:${AUTH}"],
  "env": { "AUTH": "Bearer abmcp_YOUR_TOKEN" }
}}}

4. Impostazioni

Nel pannello di controllo, in Impostazioni → Plugin → AlphaBridge MCP.

• Read-only mode (modalità sola lettura) — finché è attiva, non viene eseguito nessuno strumento che modifica qualcosa. Sta sopra a ogni altro interruttore.
• Tools (strumenti) — ogni strumento è Default (on), Default (off), On o Off. Gli strumenti che modificano qualcosa sono disattivati di base. Default è uno stato a sé, non un sinonimo di on o off: una versione successiva può riclassificare uno strumento, e un sito che ha scelto Default segue quella riclassificazione invece di congelare una vecchia decisione.
• Calls per minute and token (chiamate al minuto per token) — un freno contro un modello che gira in loop. Non è una difesa contro un chiamante determinato che possiede un token valido.
• Allow the token in the URL path (token nel percorso dell'URL) — disattivato di base, vedi sopra.
• Additional allowed origins (origini consentite aggiuntive) — per i client basati su browser, vedi sotto.

Le stesse impostazioni si possono definire in config/alphabridge-mcp.php. Un valore impostato nel file prevale sul pannello di controllo, e la pagina delle impostazioni segnala ogni campo interessato e indica da dove proviene il suo valore.

return [
    'readOnly' => false,
    'rateLimit' => 120,
    'connectorUrlAuthEnabled' => false,
    'allowedOrigins' => ['https://client.example', '$MCP_ALLOWED_ORIGINS'],
    'toolState' => ['craft_create_entry' => true],
];

I token volutamente non fanno parte delle impostazioni: sono segreti, e le impostazioni dei plugin stanno nella project config, che viene salvata in Git. I token hanno invece una pagina propria.

Origini e DNS rebinding

Se un client invia un header Origin, deve essere nell'allowlist, altrimenti l'endpoint risponde HTTP 403. L'allowlist è formata dagli allowedOrigins configurati più l'URL del sito — ma solo dove questi si possono determinare staticamente: un URL fisso con schema e host, eventualmente contenuto in una variabile d'ambiente che contiene un URL di questo tipo. Viene risolto esattamente un livello.

Un URL del sito costruito da un alias di Craft come @web non conta, nemmeno dentro una variabile d'ambiente. Craft costruisce @web dall'header Host della richiesta in arrivo, quindi un attaccante verrebbe confrontato con sé stesso. In queste installazioni allowedOrigins è l'unica fonte; se è vuoto, ogni richiesta con un Origin viene rifiutata. I client server-to-server non inviano alcun Origin e non sono interessati.

5. Licenza e prova

Il plugin è venduto tramite il Craft Plugin Store con la Craft License: una licenza per ambiente di produzione. La scheda nello store è in preparazione; finché non sarà online, lì il plugin non si può acquistare. Gli ambienti di sviluppo e di staging si possono provare gratis — fa parte della Craft License, non è una prova concessa da noi.

6. Quando qualcosa non funziona

Il registro delle attività annota ogni chiamata con il suo esito. Leggilo con lo strumento craft_audit_log (ambito amministratore) per vedere cosa ha fatto davvero un client.

Prossimi passi: il riferimento completo degli strumenti, generato dall'elenco interno degli strumenti del plugin, e come funziona la catena di sicurezza.