Collegare un assistente AI (MCP)

L'app esegue un server MCP, in modo che un assistente AI possa verificare la Sua configurazione, creare e tradurre i layout delle e-mail, gestire le Sue richieste HTTP e riordinare direttamente la Sua libreria multimediale, evitandoLe di dover copiare e incollare le impostazioni più volte.

Funzionalità utili: redigere un layout di marketing con i testi del piè di pagina, tradurre un layout in tutte le lingue in cui vendete, verificare quali layout di e-mail fanno riferimento a un codice segreto in procinto di cambiare, individuare tutte le immagini caricate che non vengono più utilizzate, spiegare perché gli invii di ieri non sono andati a buon fine o creare una nuova richiesta HTTP sulla base della documentazione di un'API di terze parti.

Endpoint

POST https://shopify.workflow-transactional-email.app/api/mcp

Il protocollo di trasporto è Streamable HTTP. L'autenticazione avviene tramite la stessa chiave bearer utilizzata per l'API REST - si veda Autenticazione e chiavi API.

Connessione

La scheda "MCP" nella pagina "Sviluppatori" dell'app genera un comando pronto per essere copiato, con il Suo URL e la Sua chiave già inseriti, per Claude, Claude Desktop, Cursor, VS Code e Gemini CLI. La invitiamo a utilizzare tale comando anziché digitarlo manualmente.

Per Claude Code il comando è il seguente:

claude mcp add --transport http flow-transactional-email \
  https://shopify.workflow-transactional-email.app/api/mcp \
  --header "Authorization: Bearer fak_your_key_here"

Per gli editor che utilizzano una configurazione JSON, la struttura è la seguente:

{
  "mcpServers": {
    "flow-transactional-email": {
      "url": "https://shopify.workflow-transactional-email.app/api/mcp",
      "headers": {
        "Authorization": "Bearer fak_your_key_here"
      }
    }
  }
}

Strumenti disponibili

Il set di strumenti riflette il livello della Sua chiave. Una chiave di sola lettura non viene semplicemente rifiutata quando richiama uno strumento di scrittura: non vede affatto tale strumento nell’elenco, pertanto non è possibile convincere un assistente a tentare l’operazione.

Leggi (15 strumenti)

Layout delle e-mail: list_email_templates, get_email_template, get_layout_schema, list_template_translations, list_template_versions, get_template_version. list_email_templates accetta q, category (transactional o marketing), page e limit.

Mittenti delle e-mail: list_smtp_configs, list_senders

Segreti: list_secret_keys (solo nomi)

Richieste HTTP: list_http_requests, get_http_request

Media: list_files (inserisca usage: true per visualizzare quali elementi fanno ancora riferimento a ciascun file)

Cronologia: list_history (filtrare per status, compreso SKIPPED per le e-mail di marketing i cui destinatari si erano tutti cancellati dalla mailing list), get_history_entry, get_stats

Lettura e scrittura (somma di 12)

Modelli di email: create_email_template, update_email_template, delete_email_template

Lingue: set_template_translation, delete_template_translation, promote_template_translation

Versioni: restore_template_version, restore_template_github_version

Richieste HTTP: create_http_request, update_http_request, delete_http_request

Media: delete_file

Lettura, scrittura ed esecuzione (aggiunge 1)

test_http_request - esegue una richiesta HTTP configurata nei confronti del bersaglio reale.

Progettazione di planimetrie con l'ausilio di un assistente

Chieda all’assistente di leggere innanzitutto get_layout_schema: descrive il formato di progettazione visiva con le impostazioni predefinite di ogni blocco, il codice Liquid che è possibile utilizzare e i limiti, generati dallo stesso builder. Successivamente, create_email_template accetta un name, un subject e un bodyDesign (visivo, impostazione predefinita) oppure un HTML body (testo). Il layout viene visualizzato immediatamente nell’app e ogni modifica viene conservata nella cronologia delle versioni, pertanto qualsiasi azione compiuta dall’assistente può essere annullata.

Due campi determinano il comportamento di un layout all’interno di un’e-mail:

• category: transactional (impostazione predefinita) oppure marketing. Un layout di marketing esclude i destinatari che si sono disiscritti e include un link di disiscrizione e un piè di pagina; si veda E-mail di marketing e cancellazioni dall’iscrizione.
• marketingTexts: i testi del piè di pagina di un layout di marketing anziché quelli del negozio, come specificato in Impostazioni, { unsubscribeText, unsubscribeLinkLabel, companyDetails }; ogni campo è facoltativo; null indica i testi delle Impostazioni. La frase relativa alla disiscrizione deve contenere {{ unsubscribe_link }} o {{ unsubscribe_url }}.

set_template_translation crea o sostituisce una lingua con il contenuto tradotto per intero. Per un layout di testo può anche includere attachments (a list = i file propri di questa lingua, null = quelli del layout, omitted = invariati), mentre per un layout di marketing marketingTexts per quella lingua oltre a quelli del layout. promote_template_translation rende una lingua la lingua principale del layout; le due si scambiano di posto, in modo che nulla vada perso.

Una buona prima richiesta:

"Legga lo schema del layout, quindi traduca il mio layout 'Ordine spedito' in tedesco e in francese. Mantenga ogni tag Liquid e ogni URL esattamente così com’è."

Ogni operazione di scrittura viene verificata come se si trattasse di un salvataggio nell'app: Liquid deve analizzare i dati, i file devono essere di vostra proprietà e lo strumento indica il campo in cui si è verificato l'errore.

Messa in ordine della libreria multimediale

Un ottimo impiego per un assistente. Chieda di elencare i Suoi file indicando anche lo spazio occupato, quindi elimini quelli a cui non fa riferimento alcun file:

"Elenchi i file che ho caricato indicando il loro utilizzo e mi indichi quali non vengono utilizzati da nessun programma. Successivamente, li elimini."

delete_file viene rifiutata con un errore 409 se un layout di e-mail o un'impostazione predefinita di intestazione/piè di pagina fa ancora riferimento al file, e il messaggio di rifiuto indica quale elemento lo sta utilizzando; pertanto, l'assistente non può rimuovere un logo di cui un'e-mail attiva ha ancora bisogno, anche se glielo si richiede.

Ciò che l’assistente non può mai vedere

Non è presente**,** in modo deliberato**, alcuno strumento che restituisca un valore segreto, un nome utente o una password SMTP, né un token di accesso alla casella di posta**. Il comando list_secret_keys restituisce esclusivamente i nomi.

Questo è proprio il punto centrale del progetto: potete chiedere a un assistente di scrivere una richiesta HTTP che effettui l’autenticazione presso il vostro fornitore di servizi di pagamento, e tale richiesta farà correttamente riferimento a {{ secrets.stripeApiKey }} senza che la chiave stessa entri mai nel contesto del modello.

La cronologia restituita tramite MCP viene mascherata esattamente come avviene tramite REST. Vale la stessa avvertenza: il mascheramento agisce sui nomi dei campi e sui modelli di valore, mentre i campi di testo libero possono comunque trasmettere dati personali durante la comunicazione. La invitiamo a tenerne conto prima di indirizzare un assistente verso un ampio intervallo di cronologia.