Configurar o servidor MCP para Craft CMS.

1. Instalar

Ainda não é possível instalar. A ficha na Craft Plugin Store está em preparação e, até estar publicada, o pacote não pode ser resolvido — os dois comandos abaixo não o vão encontrar. Estão aqui para que veja como será a instalação.

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

A migração cria duas tabelas, alphabridge_tokens e alphabridge_audit. A desinstalação remove-as de novo e não deixa nada para trás:

php craft plugin/uninstall alphabridge-mcp

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

2. Criar um token

No painel de controlo, abra AlphaBridge MCP na barra lateral. A página só está aberta a administradores. Escolha o utilizador do Craft a que o token pertence, um âmbito, um rótulo para o reconhecer mais tarde e, opcionalmente, uma validade em dias.

O token em texto simples é mostrado uma única vez, logo após a criação. Só é guardado o seu hash SHA-256, por isso não pode ser mostrado de novo. Copie-o antes de sair da página; se o perder, revogue-o e crie um novo.

O mesmo funciona a partir da consola, o que é útil para configurações automatizadas:

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 a validade de um token; 0, o valor predefinido, significa sem expiração.

O que significa um âmbito

Um token está associado exatamente a um utilizador do Craft e trabalha com as permissões desse utilizador. O âmbito restringe ainda mais; nunca alarga.

3. Ligar um cliente

O endpoint é POST https://your-site.example/alphabridge/mcp — JSON-RPC 2.0 por Streamable HTTP, versões do protocolo 2025-03-26 e 2025-06-18. O token segue num cabeçalho:

X-Api-Key: abmcp_… também funciona. Qualquer cliente MCP que fale Streamable HTTP e consiga enviar um cabeçalho personalizado pode ligar-se.

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. Definições

No painel de controlo, em Settings → Plugins → AlphaBridge MCP.

• Read-only mode (modo só de leitura) — enquanto estiver ativo, nenhuma ferramenta que altere algo será executada. Está acima de todos os outros interruptores.
• Tools (ferramentas) — cada ferramenta está em Default (on), Default (off), On ou Off. As ferramentas que alteram o estado estão desligadas por predefinição. Default é um estado próprio, não um sinónimo de ligado ou desligado: uma versão futura pode reclassificar uma ferramenta, e um site que escolheu Default segue essa reclassificação em vez de congelar uma decisão antiga.
• Calls per minute and token (chamadas por minuto e por token) — um travão contra um modelo em ciclo. Não é uma defesa contra alguém determinado que tenha um token válido.
• Allow the token in the URL path (token no URL) — desligado por predefinição, ver acima.
• Additional allowed origins (origens permitidas adicionais) — para clientes baseados no navegador, ver abaixo.

As mesmas definições podem ser feitas em config/alphabridge-mcp.php. Um valor definido no ficheiro prevalece sobre o painel de controlo, e a página de definições assinala cada campo afetado e diz de onde vem o seu valor.

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

Os tokens não fazem parte das definições, de propósito: são segredos, e as definições dos plugins ficam na configuração do projeto, que é enviada para o Git. Em vez disso, os tokens têm a sua própria página.

Origens e DNS rebinding

Se um cliente enviar um cabeçalho Origin, este tem de estar na lista de permissões, ou o endpoint responde HTTP 403. A lista de permissões é formada pelas allowedOrigins configuradas mais o URL do site — mas só quando estes podem ser determinados estaticamente: um URL fixo com esquema e anfitrião, eventualmente guardado numa variável de ambiente que contenha esse URL. É resolvido exatamente um nível.

Um URL do site construído a partir de um alias do Craft como @web não conta, nem mesmo dentro de uma variável de ambiente. O Craft constrói @web a partir do cabeçalho Host do pedido recebido, por isso um atacante seria comparado consigo próprio. Nestas instalações, allowedOrigins é a única fonte; se estiver vazia, todos os pedidos com um Origin são recusados. Os clientes servidor-a-servidor não enviam Origin e não são afetados.

5. Licença e experimentação

O plugin é vendido através da Craft Plugin Store sob a Craft License: uma licença por ambiente de produção. A ficha na loja está em preparação; até estar publicada, o plugin não pode ser comprado lá. Os ambientes de desenvolvimento e de staging podem ser experimentados gratuitamente — isso faz parte da Craft License, não é um período experimental concedido por nós.

6. Quando algo não funciona

O registo de auditoria regista cada chamada com o respetivo resultado. Leia-o com a ferramenta craft_audit_log (âmbito de administrador) para ver o que um cliente realmente fez.

A seguir: a referência completa de ferramentas, gerada a partir do catálogo interno do próprio plugin, e como funciona a cadeia de segurança.