Interfaccia MCP

In breve

MitoOps fornisce un server MCP remoto standard (Model Context Protocol) all’indirizzo /api/mcp, tramite cui un’applicazione AI compatibile richiede i dati da sola. Poggia sulle stesse funzionalità di REST: non è una seconda interfaccia con query proprie, è un altro modo di chiedere la stessa cosa.

MCP non è una proprietà del modello, ma dell’applicazione in cui il modello funziona (il client). Si collega qualsiasi applicazione che supporti MCP remoto tramite HTTP con OAuth o con chiave di accesso. Claude.ai è un client verificato in produzione: la sua procedura esatta è qui sotto; per un’altra applicazione vale la procedura generale nella parte successiva. I client che non abbiamo testato non li dichiariamo verificati.

Ci si può identificare in due modi:

• con una chiave di accesso che emettete nell’applicazione, per un vostro programma o per un server che chiama un server;
• tramite OAuth, quando si collega un’applicazione AI che lo supporta: in quel caso accedete voi e nella schermata del consenso scegliete cosa l’applicazione può leggere.

In entrambi i casi il token va nell’intestazione Authorization: Bearer e in entrambi vale lo stesso ambito di autorizzazioni: ciò che la chiave o il consenso non comprendono, lo strumento non lo restituisce.

Come collegare Claude.ai: collegamento verificato passo per passo

Claude.ai non si collega ai singoli e-shop, ma a MitoOps, il livello che già unisce i dati di tutti i vostri e-shop. Non serve alcuna chiave, Client ID né segreto. Claude.ai ricava tutto da solo dall’indirizzo dell’interfaccia.

1. In Claude.ai aprite Settings (Impostazioni) → Customize → Connectors (con il piano Team prima Organization settings → Connectors come amministratore).
2. Premete Add custom connector (Aggiungi connettore personalizzato).
3. Nel campo Name scrivete MitoOps.
4. Nel campo URL inserite l’indirizzo dell’interfaccia MCP dalla schermata Impostazioni → API & MCP, nella forma https://<il vostro indirizzo>/api/mcp, ad esempio https://app.mitoops.com/api/mcp.
5. Lasciate vuote le Advanced settings: Claude.ai usa i propri metadati del client ospitati (OAuth). Premete Add.
6. Accanto al connettore premete Connect (Collega).
7. Si apre l’accesso a MitoOps (anche con il secondo fattore, se lo avete). Accedete.
8. Vedete la schermata del consenso: quale applicazione, quale client, cosa può leggere e quali e-shop riguarda. Le autorizzazioni sono raggruppate per area dell’app (vendite, magazzino, spedizioni, marketing, programma partner, automazioni). La lettura è preselezionata, i dati sensibili e la preparazione di bozze no; le modifiche con effetto diretto (ad esempio l’eliminazione di coupon o l’approvazione di un invio) sono elencate singolarmente nella sezione chiusa Autorizzazioni avanzate. Per ogni gruppo è indicato esattamente cosa include.
9. Controllate gli ambiti. Quelli sensibili (ad esempio Report, Prezzi di acquisto e margini, Dati personali dei clienti, Fornitori e acquisti, Automazioni: bozze, Disponibilità: proposte di modifica e Reclami: proposte di modifica delle impostazioni) non sono spuntati. Se Claude deve vedere il margine, i dati personali, proporre bozze e modifiche di automazioni o modifiche delle disponibilità o delle impostazioni dei reclami, spuntateli consapevolmente. I modelli e le impostazioni dei reclami li legge l’ambito Reclami: impostazioni e modelli. Scegliete gli e-shop.
10. Premete Consenti. Claude.ai torna alla sua pagina e il connettore è collegato.
11. In una conversazione premete + → Connectors e attivate il connettore MitoOps.

Connettore collegato prima del 2/9/2026

Se avete collegato il connettore prima, Claude.ai ha in cache metadati più vecchi e nella schermata del consenso proponeva solo quattro ambiti di base. Scollegate il connettore (Disconnect) e collegatelo di nuovo (Connect): verranno proposti tutti gli ambiti, compresi quelli sensibili e i nuovi (spedizione, analytics, scorte).

Ciò che spuntate nella schermata del consenso vale, e mai più di quanto possiate voi stessi. Chi nell’applicazione non ha il diritto ai prezzi di acquisto non ha modo di concederlo ad altri. Il token che riceve Claude.ai porta solo gli ambiti consentiti.

Un altro client MCP o applicazione AI tramite OAuth

All’applicazione indicate lo stesso indirizzo /api/mcp e nient’altro, nessuna chiave. Il resto procede da solo:

1. L’applicazione ci chiede dove inviare l’accesso (metadati della risorsa protetta secondo RFC 9728).
2. Si apre il vostro accesso a MitoOps.
3. Vedete la schermata del consenso e scegliete ambiti ed e-shop.
4. Dopo il consenso il collegamento è pronto e l’applicazione vede gli strumenti.

Un’applicazione che sceglie da sola gli ambiti deve indicarli nella richiesta: la schermata del consenso propone solo ciò che l’applicazione ha chiesto (e a cui avete diritto). L’interfaccia pubblicizza tutti gli ambiti, compresi quelli sensibili, sia nella sfida WWW-Authenticate sia in scopes_supported. Quelli sensibili comunque non vengono mai consentiti da soli: nella schermata del consenso sono contrassegnati e non spuntati e il token viene emesso ristretto a ciò che avete consentito (scope nella risposta del token).

Come ci si collega con una chiave di accesso

L’assistente o il programma ha bisogno dell’indirizzo /api/mcp sul vostro dominio e di una chiave di accesso con MCP tra le interfacce. L’indirizzo esatto lo indica la schermata Impostazioni → API & MCP nel blocco “Dove inserirla”. Una chiave emessa solo per REST non funziona su MCP e viceversa.

Strumenti

L’elenco degli strumenti segue gli ambiti della chiave o del consenso: l’assistente vede esattamente ciò che gli è stato consentito e nient’altro. Uno strumento fuori ambito per lui non esiste.

Strumento MCP	Ambito	REST	Cosa restituisce
account_connection	stores:read	GET /account/connection	Diagnostica di questa connessione: l’app, chi ha concesso l’accesso e quando, permessi concessi e mancanti per area, e-shop e la modalità di scrittura tramite AI.
account_entitlements	account:read	GET /account/entitlements	Il piano del cliente, le funzioni e i limiti con l’utilizzo attuale.
affiliate_articles_create	affiliate:write	—	scrittura: Creazione di un articolo di aiuto proprio in tutte le lingue insieme (titolo e corpo nella lingua indicata); l’HTML viene ripulito.
affiliate_articles_get	affiliate:read	GET /affiliate/articles/:key	Un articolo di aiuto con il testo (HTML) in tutte le lingue o in una sola; variabili non sostituite.
affiliate_articles_list	affiliate:read	GET /affiliate/articles	Gli articoli di aiuto del portale partner: chiave, predefinito/personalizzato, attivazione, ordine, stato per lingua (titolo, indirizzo, compilato, identico al predefinito).
affiliate_articles_set_state	affiliate:write	—	scrittura: Attivazione o disattivazione di un articolo di aiuto per tutte le lingue insieme; quello predefinito non si elimina, si disattiva soltanto.
affiliate_articles_update	affiliate:write	—	scrittura: Modifica di un articolo di aiuto in una lingua (titolo, indirizzo, corpo; l’HTML viene ripulito) o ripristino del testo predefinito; restituisce le variabili sconosciute.
affiliate_campaigns_create	affiliate:write	—	scrittura: Creazione di una campagna sull’e-shop: nome, ricompensa (da non inventare), validità dell’attribuzione, disponibilità, approvazione delle conversioni.
affiliate_campaigns_get	affiliate:read	GET /affiliate/campaigns/:campaignId	Una campagna del programma partner.
affiliate_campaigns_list	affiliate:read	GET /affiliate/campaigns	Le campagne del programma partner dell’e-shop con ricompensa, disponibilità e conteggi.
affiliate_campaigns_update	affiliate:write	—	scrittura: Modifica di una campagna: nome, ricompensa, validità, disponibilità, approvazione, attivazione/disattivazione, descrizione per i partner per lingua.
affiliate_code_requests_decide	affiliate:write	—	scrittura: Gestione della richiesta di un partner per un codice proprio: l’approvazione crea subito il codice negli e-shop delle campagne con sconto per il cliente (richiede anche coupons:write), retry ripete la creazione, il rifiuto richiede un motivo; il partner riceve un’e-mail.
affiliate_code_requests_list	affiliate:read	GET /affiliate/code-requests	Le richieste dei partner per un codice sconto proprio con stato e motivo; prima quelle in attesa.
affiliate_conversions_decide	affiliate:approve	—	scrittura: Decisione su una singola provvigione per id: approve (nuova → approvata), reject (nuova → rifiutata, motivo obbligatorio), cancel (approvata → annullata, motivo obbligatorio); una pagata non viene stornata, la stessa decisione una seconda volta non cambia nulla; il partner riceve un’e-mail.
affiliate_conversions_get	affiliate:read	GET /affiliate/conversions/:conversionId	Il dettaglio di una conversione: importi, provvigione, stato della provvigione con motivo, stato dell’ordine nell’e-shop, nota di credito, pagamento.
affiliate_conversions_list	affiliate:read	GET /affiliate/conversions	Le conversioni del programma partner dell’e-shop: base della provvigione e ordine completo IVA inclusa, provvigione, stato della provvigione con motivo, stato dell’ordine nell’e-shop, legame con il pagamento.
affiliate_discount_codes_ensure	coupons:write	—	scrittura: Fa sì che il partner abbia un codice sconto sull’e-shop: il coupon viene creato tramite i coupon canonici (o ne viene usato uno esistente) e assegnato al partner; la nota nell’e-shop nasce automaticamente.
affiliate_discount_codes_list	affiliate:read	GET /affiliate/discount-codes	I codici sconto dei partner sull’e-shop con numero di utilizzi e fatturato.
affiliate_documents_draft_create	affiliate:write	—	scrittura: Proposta di un nuovo testo di un documento legale come bozza; non modifica il testo attivo, lo pubblica una persona nell’applicazione con differenze e audit.
affiliate_documents_get	affiliate:read	GET /affiliate/documents/:key/content	Un documento legale del programma con il testo per lingua (testo salvato, testo pubblico, versione, impronte, fonte, metadati PDF) e le bozze aperte.
affiliate_documents_list	affiliate:read	GET /affiliate/documents	I documenti del programma (condizioni, accordi): politica di conferma, copia firmata, allegato e-mail, versioni per lingua, completezza e numero di conferme.
affiliate_documents_update	affiliate:write	—	scrittura: La politica di un documento del programma (per chi vale, quando si conferma, copia firmata, allegato e-mail, attivazione); il testo si carica nell’applicazione.
affiliate_email_templates_list	affiliate:read	GET /affiliate/email-templates	I modelli di e-mail ai partner per lingua (oggetto, attivazione, con l’evento anche il corpo) e gli allegati automatici dell’e-mail Account approvato.
affiliate_email_templates_update	affiliate:write	—	scrittura: Modifica di un modello di e-mail ai partner in una lingua (oggetto, corpo) o attivazione/disattivazione dell’evento.
affiliate_links_generate	affiliate:read	GET /affiliate/links/generate	Un link partner tracciato alla home, a un prodotto o a una categoria dell’e-shop della campagna; dopo il clic mantiene l’attribuzione al partner.
affiliate_partners_get	affiliate:read	GET /affiliate/partners/:partnerId	Un partner del programma con le campagne a sua disposizione.
affiliate_partners_list	affiliate:read	GET /affiliate/partners	I partner del programma con stato, rendimento e provvigioni; il contatto solo con i dati personali.
affiliate_partners_set_market	affiliate:write	—	scrittura: L’appartenenza del partner a un e-shop: consentire (active, approva anche una richiesta dal portale) o revocare (revoked); campagne, coupon e documenti dell’e-shop riguardano il partner solo con un’appartenenza attiva.
affiliate_partners_set_state	affiliate:write	—	scrittura: Decisione sull’account del partner (approvare, rifiutare, sospendere, rimettere tra quelli in attesa); l’approvazione invia un’e-mail con l’accordo.
affiliate_payouts_list	affiliate:read	GET /affiliate/payouts	I pagamenti delle provvigioni ai partner con lo stato; senza dati bancari e di fatturazione.
affiliate_portal_get	affiliate:read	GET /affiliate/portal	Il portale pubblico del partner: indirizzi per e-shop, apertura della registrazione con motivo, domini propri, persona di contatto, aspetto e stato dei testi per lingua.
affiliate_portal_pages_update	affiliate:write	—	scrittura: Testi propri del portale pubblico in una lingua (pagine accesso/registrazione/panoramica, informativa, descrizione del programma); l’HTML viene ripulito.
affiliate_settings	affiliate:read	GET /affiliate/settings	Le impostazioni del programma partner: provvigioni, clic, pagamento minimo, segnalazione.
affiliate_settings_update	affiliate:write	—	scrittura: Impostazioni del programma escluso il denaro: nome, registrazione, approvazione automatica, persona di contatto, colori, link all’informativa.
affiliate_signatures_get	affiliate:read	GET /affiliate/signatures/:signatureId	Una firma elettronica con il testo firmato e l’istantanea dei valori; record immutabile, il PDF viene composto nell’applicazione.
affiliate_signatures_list	affiliate:read	GET /affiliate/signatures	I documenti firmati elettronicamente dai partner (chi, documento, versione, lingua, e-shop, ora, modalità, verifica, impronte, stato) e i partner a cui manca la firma; solo lettura: la firma nasce esclusivamente nel portale.
affiliate_statistics	affiliate:read	GET /affiliate/statistics	Le statistiche del programma partner: andamento per giorno, fonti di attribuzione, classifica dei partner.
affiliate_summary	affiliate:read	GET /affiliate/summary	La panoramica del programma partner dell’e-shop per il periodo: clic, conversioni, provvigioni, partner.
affiliate_variables_list	affiliate:read	GET /affiliate/variables	Il registro delle variabili dei contenuti e delle e-mail del programma partner: nomi canonici, alias, tipo, superfici, esempio; controllo facoltativo del testo per variabili sconosciute.
analytics_advertising	reports:read	GET /analytics/advertising	Pubblicità: spesa, budget, ROAS, incidenza pubblicitaria, CPA, valore medio dell’ordine e MER con confronto; Google Ads e Meta Ads, clic da GA4, 6 mesi.
analytics_channels	analytics:read	GET /analytics/channels	La ripartizione di visite, ordini e fatturato per canale di marketing.
analytics_comparison	reports:read	GET /analytics/comparison	Fatturato a confronto: fatturato, ordini, AOV, visite, CR e AI/LLM rispetto al periodo precedente o all’anno prima.
analytics_monthly	reports:read	GET /analytics/monthly	Fatturato, ordini e visite per mese (al massimo 24), ad esempio anno su anno.
analytics_order_coverage	analytics:read	GET /analytics/order-coverage	La copertura degli ordini e del fatturato da parte della misurazione in analytics.
analytics_order_heatmap	reports:read	GET /analytics/order-heatmap	Quando arrivano gli ordini: giorno della settimana × ora, giorno e ora più forti.
analytics_overview	analytics:read	GET /analytics/overview	Visite, ordini, fatturato, tasso di conversione e quota AI/LLM per il periodo.
analytics_revenue_sources	reports:read	GET /analytics/revenue-sources	Da dove arriva il fatturato: canali, totali AI/LLM, MitoOps e Affiliate, acquisizione secondo GA4.
analytics_seo	analytics:read	GET /analytics/seo	Search Console: clic, impressioni, CTR e posizione per query o pagine.
automations_catalog	automations:read	GET /automations/catalog	Il catalogo delle automazioni: trigger, condizioni, operatori, azioni, modelli; catalogVersion per le bozze.
automations_create_draft	automations:write	—	scrittura: Crea una bozza di automazione DISATTIVATA. Non la attiva né la avvia.
automations_get	automations:read	GET /automations/:workflowId	Un’automazione con il DSL e il risultato della validazione.
automations_list	automations:read	GET /automations	Le automazioni del cliente con stato e ambito di e-shop.
automations_options	automations:read	GET /automations/options	L’elenco dei valori per un campo di automazione (stati, spedizioni, pagamenti, modelli, reclami…): value per il DSL e nome.
automations_revision_create_draft	automations:write	—	scrittura: Propone una modifica di un’automazione pubblicata come revisione da far approvare a una persona. La versione in funzione non cambia.
automations_revision_discard_draft	automations:write	—	scrittura: Ritira la revisione aperta di un’automazione pubblicata.
automations_revision_update_draft	automations:write	—	scrittura: Modifica la revisione aperta di un’automazione pubblicata.
automations_runs	automations:read	GET /automations/:workflowId/runs	La cronologia delle esecuzioni di un’automazione.
automations_templates	automations:read	GET /automations/templates	I modelli di automazione pronti con il DSL.
automations_update_draft	automations:write	—	scrittura: Modifica una bozza di automazione non pubblicata con concorrenza ottimistica.
automations_validate_draft	automations:read	—	Verifica una bozza di automazione senza scrivere.
chatbot_conversations_get	chatbot-conversations:read	GET /chatbot/conversations/:sessionId	La trascrizione di una conversazione con il chatbot web, con le fonti delle risposte del bot.
chatbot_conversations_list	chatbot-conversations:read	GET /chatbot/conversations	Le conversazioni dei clienti con il chatbot web dalla più recentemente attiva, con la prima domanda; cursore.
chatbot_outcomes	chatbot:read	GET /chatbot/outcomes	How web chatbot conversations ended: since when the outcome is measured, measured and unmeasured conversations, known and unknown outcome, resolved, unresolved, bot error and resolution rate with its denominator; N/A with a reason when the denominator is zero. Totals only.
chatbot_stats	chatbot:read	GET /chatbot/stats	Le statistiche del chatbot web per il periodo: imbuto del messaggio, aperture, conversazioni, esiti, valutazioni.
chatbot_topics	chatbot:read	GET /chatbot/topics	Di cosa trattavano le conversazioni: quote degli argomenti, prodotti, tipo di pagina iniziale e candidati a lacune di conoscenza.
claims_config_change_draft	claims-settings:draft	—	scrittura: Propone una modifica a processi, stati, etichette, modelli, testi del modulo e impostazioni del modulo reclami; la scrive solo una persona approvandola nell’applicazione.
claims_config_draft_get	claims-settings:read	GET /claims/config-drafts/:draftId	Lo stato di una proposta di modifica delle impostazioni dei reclami (in attesa, scritta, rifiutata).
claims_configuration	claims-settings:read	GET /claims/configuration	Le impostazioni dei reclami: etichette, campi, trasporto di reso, modulo sull’e-shop, tipi di modulo.
claims_get	claims:read	GET /claims/:code	Un caso con articoli e collegamenti: ordine, nota di credito, spedizione di reso, movimento di magazzino.
claims_list	claims:read	GET /claims	I reclami e i resi di un e-shop dal più recente.
claims_refund_options	claims-settings:read	GET /claims/refund-options	Refunds: variable symbol source, refund coupon validity, coupon in the form, when the form asks for an account number.
claims_refund_readiness	claims:read	GET /claims/:code/refund-readiness	Claim before a refund: what the customer requests, masked account, variable symbol, mode and whether the claim can be deleted.
claims_refund_settings	claims-settings:read	GET /claims/refund-settings	Rimborsi dei reclami: modalità, conti bancari con idoneità all’ordine di pagamento (mascherati), conto predefinito e manuale.
claims_routes	claims-settings:read	GET /claims/routes	Spedizione di reso dei reclami: percorsi, indirizzi, profili dei corrieri con ID e supporto al reso, tipi di caso.
claims_routes_change_draft	claims-routes:draft	—	scrittura: Propone una tratta di reso (anche per tutta l’UE o il mondo) e un indirizzo del destinatario; li scrive una persona approvandoli (o la scrittura autonoma, se il cliente l’ha attivata).
claims_settings	claims:read	GET /claims/settings	I processi dei reclami con ID e nomi (tipi, passaggi, stati, termini), etichette; le impostazioni del modulo con l’ambito claims-settings:read.
claims_statistics	claims:read	GET /claims/statistics	Le statistiche di reclami e resi per il periodo: conteggi, tempi di gestione, tipi, valutazioni, motivi.
claims_templates	claims-settings:read	GET /claims/templates	I modelli di e-mail (oggetto, testo, quando e se vengono inviati automaticamente) e dei verbali dei reclami.
content_articles_search	products:read	GET /content/articles	Gli articoli del blog dell’e-shop con l’indirizzo sul web e l’immagine di anteprima.
coupons_activation_link	coupons:read	GET /coupons/activation-link	Un link che applica al cliente nel carrello un coupon ESISTENTE. Non crea il coupon.
coupons_activation_status	coupons:read	GET /coupons/activation-status	Se il coupon si può usare sull’e-shop tramite il link di attivazione: mirror del coupon + stato del codice sul web.
coupons_capabilities	coupons:read	GET /coupons/capabilities	Cosa sa fare con i coupon la piattaforma dell’e-shop. Leggetelo prima di crearne.
coupons_ensure	coupons:write	—	scrittura: Fa sì che il coupon esista sugli e-shop selezionati. Con un valore di sconto diverso NON viene sovrascritto.
coupons_get	coupons:read	GET /coupons/:code	Un coupon dall’archivio di MitoOps. Quando non c’è, la risposta è “non trovato”.
coupons_list	coupons:read	GET /coupons	I coupon sconto dell’e-shop con tipo e valore dello sconto, validità e stato derivato.
coupons_remove	coupons:delete	—	scrittura: Eliminazione esplicita di un coupon: dipendenze, anteprima, conferma; con una dipendenza attiva non viene eliminato.
coupons_update	coupons:write	—	scrittura: Modifica esplicita di un coupon esistente, comprese le limitazioni a prodotti e categorie; anteprima, poi conferma.
customers_get	customers:read	GET /customers/:customerKey	Un cliente della rubrica: identità, e-shop, importi LIFETIME e facoltativamente PERIOD, ripartizione per e-shop.
customers_list	customers:read	GET /customers	La rubrica clienti: identità (con mascheramento dei dati personali), e-shop, lingua, conteggi LIFETIME e fatturato per valuta; filtro facoltativo dell’attività di acquisto nel periodo.
customers_performance	reports:read	GET /customers/performance	I clienti come pseudonimi: numero di ordini, fatturato, primo e ultimo ordine, acquisto ripetuto, LTV.
credit_notes_search	invoices:read	GET /credit-notes	Ricerca nelle note di credito.
documents_list	invoices:read	GET /documents	Documenti contabili di un tipo (fatture, fatture proforma, note di credito) per pagine con ciclo di vita, stato nella fonte, filtro di validità e disponibilità del PDF.
documents_pdf_link	invoices:read	—	Link temporaneo (10 minuti) al PDF di una fattura, fattura proforma o nota di credito da aprire nel browser.
invoices_get	invoices:read	GET /invoices/:invoiceCode	Una fattura con righe, importi, note di credito e fatture di acconto collegate.
invoices_search	invoices:read	GET /invoices	Ricerca nelle fatture.
inventory_movements	inventory:read	GET /inventory/movements	La cronologia dei movimenti di magazzino: quando, cosa, di quanto, perché e da quale fonte.
inventory_product_availability	inventory:read	GET /inventory/availability	La giacenza di più articoli contemporaneamente.
inventory_stock	inventory:read	GET /inventory/stock	La giacenza di un articolo con la fonte del valore.
orders_get	orders:read	GET /orders/:orderCode	Un ordine salvato, righe comprese.
orders_list	orders:read	GET /orders	Gli ordini salvati di un e-shop, dal più recente.
availabilities_change_draft	availabilities:draft	—	scrittura: PROPOSTA di modifica del catalogo delle disponibilità (creare, modificare, eliminare). Nell’e-shop la scrive solo una persona approvandola in MitoOps.
availabilities_draft_get	products:read	GET /availabilities/drafts/:draftId	Lo stato di una proposta di modifica del catalogo delle disponibilità: in attesa di approvazione, scritta con risultato, rifiutata, scaduta.
availabilities_list	products:read	GET /availabilities	Il catalogo delle disponibilità dell’e-shop: nome, descrizione, rifornimento, consegna, significato per Google, colore, ruolo predefinito.
categories_content_change_draft	category-content:draft	—	scrittura: PROPOSTA di nuovi testi delle categorie (al massimo 30 alla volta); nell’e-shop li scrive solo una persona approvandoli in MitoOps.
categories_content_draft_get	category-content:read	GET /catalog/category-content-drafts/:draftId	Stato di una proposta di testi delle categorie: in attesa di approvazione, scritta, rifiutata, scaduta.
categories_content_get	category-content:read	GET /categories/:guid/content	Testi di una categoria (descrizione superiore e inferiore, titolo e descrizione SEO) con impronta e scrivibilità.
categories_list	products:read	GET /categories	Le categorie dell’e-shop con il numero di prodotti.
products_content_change_draft	product-content:draft	—	scrittura: PROPOSTA di nuovi testi dei prodotti (al massimo 30 alla volta); nell’e-shop li scrive solo una persona approvandoli in MitoOps.
products_content_draft_get	product-content:read	GET /catalog/product-content-drafts/:draftId	Stato di una proposta di testi dei prodotti: in attesa di approvazione, scritta con avvisi dell’e-shop, rifiutata, scaduta.
products_content_get	product-content:read	GET /products/:code/content	Testi di un prodotto dall’e-shop (descrizione, descrizione breve, titolo e descrizione SEO) con impronta e scrivibilità.
products_content_policy	product-content:read	GET /product-content/policy	Criteri dei contenuti dell’e-shop senza chiamare l’e-shop: cosa può leggere e proporre questo accesso, quali campi scrive la piattaforma, modalità di approvazione e scrittura autonoma, limiti e impronte.
products_get	products:read	GET /products/:code	Un prodotto per codice, con classificazione e prezzo dalla scheda.
products_search	products:read	GET /products	Ricerca dei prodotti per nome, codice, EAN o PLU.
reports_financial_summary	reports:read	GET /reports/financial-summary	Il riepilogo finanziario del periodo: fatturato, IVA, ordini, AOV; con i diritti anche acquisto, utile lordo, costi e risultato.
sales_order_performance	reports:read	GET /sales/order-performance	Il fatturato per ordine in EUR con i totali per l’intero periodo; con il diritto anche acquisto, utile lordo e margine per ordine.
sales_product_performance	reports:read	GET /sales/product-performance	Le vendite per prodotto dai documenti; con il diritto anche il prezzo di acquisto al momento della vendita e il margine.
search_console_query	search-console:read	GET /search-console/query	Search Console per giorno, query, pagina, paese e dispositivo, con paginazione e hash del contenuto.
search_console_status	search-console:read	GET /search-console/status	Stato di Search Console del negozio: connessione, proprietà, autorizzazione, sincronizzazione e ampiezza dell’archivio.
shipping_carriers	shipping:read	GET /shipping/carriers	I corrieri collegati e i loro profili, senza dati di accesso.
shipping_shipment_detail	shipping:read	GET /shipping/shipments/:shipmentId	Una spedizione con tutti gli eventi di tracciamento.
shipping_shipments	shipping:read	GET /shipping/shipments	Le spedizioni di un e-shop con corriere, paese e orari di affidamento e consegna.
shipping_stats	shipping:read	GET /shipping/stats	Le statistiche di consegna per corriere: conteggi, tasso di successo, mediana e p90 del tempo di consegna, paesi.
stores_integration_status	stores:read	GET /stores/integration-status	Lo stato del codice MitoOps sul web per e-shop: installato, versione, moduli, predisposizione del coupon dall’indirizzo.
stores_list	stores:read	GET /stores	L’elenco degli e-shop del cliente con il loro codice.
suppliers_get	purchasing:read	GET /suppliers/:supplierId	Un fornitore con le offerte di prodotti e le componenti di costo.
suppliers_list	purchasing:read	GET /suppliers	I fornitori del cliente con il numero di offerte e di prodotti abbinati.
webhooks_deliveries	webhooks:read	GET /webhooks/endpoints/:endpointId/deliveries	Il registro delle consegne di un endpoint, senza corpo.
webhooks_endpoint	webhooks:read	GET /webhooks/endpoints/:endpointId	Un endpoint webhook con il numero di consegne in attesa.
webhooks_endpoints	webhooks:read	GET /webhooks/endpoints	Gli endpoint webhook del cliente senza segreti e lo stato della coda.
webhooks_events	webhooks:read	GET /webhooks/events	Il catalogo degli eventi dei webhook in uscita, la busta e la firma.

Nome, e-mail, telefono e via del cliente sono in orders_list, orders_get, claims_list e claims_get solo con l’ambito personal-data:read; senza di esso la risposta riporta paese e città. Lo stesso vale per il contatto del fornitore e del partner del programma (affiliate_partners_*). L’ambito non ha uno strumento proprio.

Nella rubrica clienti (customers_list, customers_get) lo stesso ambito decide di nome, azienda, e-mail, telefono e genere di marketing; senza di esso restano pseudonimo, e-shop, paese, lingua, conteggi e date. Fatturato e LTV richiedono inoltre reports:read. Il genere di marketing è una stima dal nome di battesimo (genderSource: "name_inference"), non un dato indicato dal cliente: l’assistente deve presentarlo così. I dati bancari e fiscali dei partner non vengono forniti mai.

Chatbot web: argomenti delle conversazioni. chatbot_topics (lo stesso ambito chatbot:read) risponde con una sola chiamata alla domanda “di cosa si trattava”: la quota di conversazioni per argomento da una tassonomia chiusa (spedizione, pagamento, reso, scelta del prodotto, parametri, utilizzo, domande formative…), il tasso di risoluzione e il numero di candidati a lacune di conoscenza per argomento, i prodotti più frequenti (su cui i clienti hanno chiesto e che il bot ha consigliato), da quale tipo di pagina iniziano le conversazioni e l’andamento per giorno. La valutazione è deterministica: si basa sulle fonti delle risposte, sui prodotti consigliati e su un dizionario di parole chiave, quindi due chiamate sullo stesso periodo danno lo stesso numero. Restituisce solo totali: il testo del cliente non vi arriva per nessuna via, nemmeno come “domanda più frequente”. La quota va sempre insieme al conteggio: con poche conversazioni la percentuale è inaffidabile. chatbot_conversations_list ha i filtri topic e knowledgeGapCandidate; la trascrizione di una conversazione specifica resta dietro l’ambito sensibile e solo entro la conservazione.

Chatbot web. Le statistiche (chatbot_stats, ambito chatbot:read) restituiscono solo totali: a quante visite di pagina è stato mostrato il messaggio e quante di esse vi hanno fatto clic, le aperture della finestra, il numero di conversazioni e messaggi, cosa ha risolto il bot, le valutazioni dei clienti e l’imbuto dell’iscrizione alla newsletter. Le conversazioni dei clienti (chatbot_conversations_list, chatbot_conversations_get) stanno dietro un proprio ambito sensibile chatbot-conversations:read, che nella schermata del consenso spuntate consapevolmente: nella registrazione il cliente è solo una chiave casuale della conversazione (senza IP, cookie, nome o e-mail); e-mail, telefono e IBAN che ha scritto nel testo l’assistente li riceve solo con personal-data:read, altrimenti al loro posto vede il segnaposto [e-mail], [telefón], [iban]. Le conversazioni vengono fornite solo entro la conservazione dell’e-shop (impostazione Cronologia nel Centro AI); un e-shop con conservazione zero non fornisce nulla. Le visualizzazioni del messaggio fino al 21/9/2026 si contavano a ogni comparsa del messaggio; dal 22/9/2026 una visualizzazione è una visita di pagina e measurementChanges nella risposta dice se il periodo scelto mescola le due misurazioni.

Ogni strumento ha un equivalente in REST sulla stessa funzionalità. Le risposte differiscono per la busta, i dati commerciali sono identici. Le regole del periodo, della paginazione e il significato dei campi finanziari sono nell’interfaccia REST.

Gli strumenti di riepilogo (shipping_stats, analytics_*, reports_financial_summary) restituiscono numeri già pronti dall’applicazione: l’assistente non deve scaricare migliaia di record e calcolare da solo. Gli elenchi grezzi (shipping_shipments, orders_list) restano per la vista dettagliata.

Cosa si può chiedere

Dopo il collegamento Claude.ai risponde con i dati di MitoOps ad esempio a:

• “Qual è stata la ripartizione percentuale delle spedizioni ad agosto?”: shipping_stats
• “Qual è stata la mediana del tempo di consegna di DHL e GLS?” e “Quante non sono state consegnate e quante sono state rese?”: shipping_stats
• “In quali paesi abbiamo spedito tramite DHL?”: shipping_stats (campo countries)
• “Quali sono stati il fatturato e il tasso di conversione ad agosto?”: analytics_overview o reports_financial_summary
• “Quanti ordini e quanto fatturato sono arrivati da ChatGPT?”: analytics_channels
• “Quali query hanno avuto il CTR più alto?”: analytics_seo
• “Qual è il margine del prodotto X nell’ultimo mese?”: sales_product_performance (con purchase-prices:read)
• “Su cosa hanno chiesto più spesso i clienti al chatbot questo mese e su cosa scrivere un articolo per il blog?”: chatbot_conversations_list e chatbot_conversations_get (con chatbot-conversations:read)
• “Quante conversazioni ha avuto il chatbot e quante ne ha risolte senza assistenza?”: chatbot_stats
• “Quali disponibilità ha l’e-shop SK e quali sono predefinite?” (availabilities_list)
• “Aggiungi sull’e-shop SK la disponibilità Preordine ottobre con significato preordine e consegna entro 14 giorni” (availabilities_change_draft con availabilities:draft; nasce una proposta che scrivete approvandola nell’applicazione)
• “Modifica l’automazione attiva 12 in modo che invii l’avviso solo con la spedizione Corriere” (automations_options per la spedizione, poi automations_revision_create_draft; la versione in funzione non cambia finché non pubblicate la revisione nell’editor)
• “Quali e-mail inviano automaticamente i reclami e cosa c’è scritto in tedesco?” (claims_templates con claims-settings:read)
• “Rinomina lo stato del reclamo In attesa della merce in Attendiamo la spedizione” (claims_settings per l’ID, poi claims_config_change_draft con claims-settings:draft; lo scrivete approvandolo nell’applicazione)

Lettura e scritture ristrette: automazioni, coupon, programma partner, disponibilità, reclami

I dati operativi (ordini, giacenze, prodotti, documenti, spedizioni) tramite MCP si possono solo leggere. Ogni scrittura sta dietro un proprio ambito sensibile: bozza di automazione, coupon sconto, gestione del programma partner, decisione sulla provvigione, proposta di modifica del catalogo delle disponibilità, che nell’e-shop scrive solo una persona, e proposta di modifica delle impostazioni dei reclami, che scrive anch’essa solo una persona.

Bozza di automazione. Con l’ambito automations:write si tratta di una bozza disattivata: in base al catalogo (automations_catalog) l’assistente può proporre una regola e salvarla come bozza, oppure modificare una bozza che nessuno ha ancora pubblicato. La bozza compare in Automazioni come ogni bozza in lavorazione: attivarla, pubblicarla o avviarla potete solo voi nell’applicazione. Un’automazione pubblicata l’assistente non la modifica direttamente.

Revisione di un’automazione in funzione. Anche un’automazione pubblicata e attiva l’assistente con l’ambito automations:write può modificarla, ma solo con una proposta: automations_revision_create_draft (input workflowId, expectedPublishedVersion da automations_get, catalogVersion, l’intero nuovo dsl, note e clientRequestId) salva una revisione accanto alla versione in funzione. L’automazione in funzione non cambia e continua a funzionare. Per un’automazione c’è al massimo una revisione aperta; si modifica con automations_revision_update_draft con expectedRevisionVersion e si scarta con automations_revision_discard_draft. La risposta porta approvalUrl, un link all’editor dell’automazione. Lì una persona con il diritto di modificare le automazioni vede la revisione nel pannello superiore, la carica nell’editor (pulsante Carica la proposta nell’editor), la controlla e la pubblica con il normale pulsante; l’automazione resta attiva. Oppure la rifiuta. Se nel frattempo qualcuno ha pubblicato un’altra versione, la revisione viene chiusa (REVISION_STALE) e bisogna prepararne una nuova. La revisione aperta e lo storico li restituisce automations_get (openRevision, revisions).

Elenchi di valori dei campi e verifica dei valori. I campi che nell’editor si scelgono da un elenco (stato dell’ordine, spedizione, pagamento, profilo corriere, modello di notifica, tipo, stato, etichetta e modelli del reclamo, endpoint webhook e altri) hanno una fonte nel catalogo. automations_options con source e market restituisce i loro valori [{ value, name }] esattamente nella forma che l’editor salva (ID dello stato, GUID di spedizione e pagamento, ID dello stato del reclamo); senza source elenca le fonti e se sono diverse per ogni e-shop (perShop). La validazione (automations_validate_draft) e il salvataggio di una bozza o di una revisione rifiutano un valore che nell’e-shop non esiste (FIELD_UNKNOWN_OPTION) e un testo segnaposto del tipo DOPLNIT_… o TODO (FIELD_PLACEHOLDER). Quando l’elenco non si può verificare (l’e-shop non ha risposto, l’elenco è troncato), arriva solo l’avviso FIELD_OPTIONS_UNVERIFIED. orders_get e orders_list riportano statusId, shippingGuid e paymentGuid, cioè gli stessi valori con cui lavorano le condizioni dell’automazione.

L’ambito automations:write è sensibile: nella schermata del consenso non è preselezionato, viene offerto solo a una persona con il diritto di modificare le automazioni, i collegamenti esistenti non lo ricevono e il rinnovo del token non lo estende. Ordini, prodotti, giacenze, documenti, rimborsi, casi di reclamo e spedizioni tramite MCP non si possono modificare; il catalogo delle disponibilità dell’e-shop e le impostazioni dei reclami si modificano solo con una proposta approvata da una persona nell’applicazione (più avanti). Gli endpoint webhook tramite MCP si possono solo leggere. I dati di accesso ai corrieri, all’e-shop e ad analytics tramite MCP non si possono leggere.

Coupon sconto. Con l’ambito coupons:write l’assistente crea un coupon secondo i parametri che indicate (coupons_ensure, anche il coupon di un partner affiliate_discount_codes_ensure) e modifica esplicitamente uno esistente (coupons_update, anteprima e conferma); l’eliminazione ha un ambito proprio coupons:delete e un coupon con una dipendenza attiva non viene eliminato.

Gestione del programma partner. Con l’ambito affiliate:write l’assistente decide sull’account di un partner (affiliate_partners_set_state: approvare, rifiutare, sospendere; il partner riceve un’e-mail anche con il PDF dell’accordo secondo la politica dei documenti), gestisce una richiesta di codice proprio (affiliate_code_requests_decide), modifica le impostazioni del programma escluso il denaro (affiliate_settings_update: nome, registrazione, persona di contatto, colori), i testi del portale in una lingua (affiliate_portal_pages_update), gli articoli di aiuto (affiliate_articles_create, affiliate_articles_update anche con il ripristino del testo predefinito, affiliate_articles_set_state; l’eliminazione dall’esterno no), i modelli di e-mail (affiliate_email_templates_update), le campagne (affiliate_campaigns_create, affiliate_campaigns_update), la politica dei documenti (affiliate_documents_update) e l’appartenenza del partner a un e-shop (affiliate_partners_set_market: consentire o revocare). Il testo dei documenti legali lo legge (affiliate_documents_get: testo per lingua, versione, impronte, bozze) e un nuovo testo lo propone solo come bozza (affiliate_documents_draft_create; anche privacyNotice in affiliate_portal_pages_update da questa versione è una bozza): il testo attivo lo pubblica una persona nell’applicazione con differenze e audit. Il registro delle variabili dei contenuti e delle e-mail (nomi canonici, alias, tipo, superfici) lo fornisce affiliate_variables_list; affiliate_email_templates_list restituisce i nomi delle variabili, non gli indici. Pagamenti, base della provvigione e caricamento del file di un documento tramite MCP non esistono: restano nell’applicazione.

Decisione sulla provvigione. Con un proprio ambito sensibile affiliate:approve (diritto approvazione delle provvigioni, non gestione del programma) l’assistente prima legge le provvigioni in attesa insieme allo stato dell’ordine nell’e-shop (affiliate_conversions_list con state=new, dettaglio affiliate_conversions_get: base della provvigione revenue, ordine completo IVA inclusa revenueTotal, orderState open/completed/cancelled, orderPaid, nota di credito), le riassume e solo su indicazione esplicita dell’utente decide su una singola conversione specifica (affiliate_conversions_decide: approve, reject o cancel, per rifiuto e annullamento con un motivo obbligatorio che il partner riceve via e-mail). Vale la stessa macchina a stati dell’applicazione: una provvigione pagata non viene stornata, annullata e rifiutata sono stati finali, la stessa decisione una seconda volta non cambia nulla (changed: false). L’approvazione in blocco dall’esterno non esiste: per cento conversioni ci sono cento chiamate, ognuna con audit. Da W-AFF10 ogni conversione porta anche approvalPolicy (modalità di approvazione della campagna, periodo, stati dell’ordine consentiti, pagamento) e approvalEligibility: se l’automatismo orario la approverebbe ora e perché no (minimum_age_not_reached, order_state_not_allowed, order_not_paid, order_cancelled, fully_refunded, approval_manual…), lo stesso calcolo dell’applicazione; l’elenco ha i filtri orderPaid, minCommission, orderState e la paginazione offset + hasMore, quindi “passa in rassegna le nuove conversioni di due mesi, mostra quelle non pagate o superiori a 20 €” richiede una o poche letture. Le condizioni della campagna le imposta affiliate_campaigns_update (approval, approveAfterDays, requiredOrderStatusIds, paidRequired) con l’ambito affiliate:write. I pagamenti ai partner tramite MCP si possono solo leggere (affiliate_payouts_list): emettere un lotto, generare il documento, inviarlo al partner o presentare un ordine alla banca l’assistente non lo sa fare; resta nell’applicazione, nelle mani del gestore.

Proposta di modifica del catalogo delle disponibilità. Con l’ambito sensibile availabilities:draft l’assistente prepara una proposta su come creare, modificare o eliminare disponibilità su un e-shop (availabilities_change_draft, solo MCP). Nell’e-shop non scrive nulla: verifica la proposta, la salva in MitoOps per 24 ore e restituisce draftId, l’anteprima per voce (preview con i campi prima e dopo, warnings ed errors), expiresAt e approvalUrl, un link alla schermata Magazzino → Disponibilità, dove la proposta attende nella scheda Gestione. Lì una persona autorizzata la approva con il pulsante Approva e scrivi o la rifiuta, e la scrittura avviene con i suoi diritti al momento del clic. Se il catalogo dell’e-shop cambia dopo la proposta, l’approvazione non scrive nulla e la proposta termina come failed. Stato e risultato per voce li restituisce availabilities_draft_get: pending, writing, executed, partial, failed, rejected o expired. Quando l’anteprima segnala un blocco, la proposta non nasce (blocked), e nemmeno quando non cambia nulla (no_change).

L’input è market e changes (al massimo 30 voci). Ogni modifica ha action (create, update o remove), per modifica ed eliminazione l’id da availabilities_list e solo i campi da cambiare: name (al massimo 120 caratteri, nella lingua dell’e-shop), description (al massimo 1000 caratteri, null significa senza descrizione), onStockHours e deliveryHours (ore intere da 0 a 2500, null significa senza dato), meaning (in_stock, backorder, preorder, out_of_stock) e color (hex, null significa senza colore). Una nuova disponibilità richiede name e meaning. Il clientRequestId facoltativo rende la chiamata idempotente: la stessa chiave con lo stesso contenuto restituisce la stessa proposta (replayed: true), con un contenuto diverso termina con l’errore CONFLICT (CLIENT_REQUEST_REUSED).

L’anteprima blocca ciò che l’e-shop rifiuterebbe o che romperebbe le impostazioni: un nome duplicato nell’e-shop, l’eliminazione di una disponibilità di sistema o predefinita o di una disponibilità usata da un piano disponibilità e, su WooCommerce, il cambio di significato di una voce di sistema o un significato di una voce predefinita non coerente con il suo ruolo. Una disponibilità usata dai prodotti l’e-shop non la elimina. Il cambio di significato su WooCommerce lo scrive solo un e-shop con il plugin MitoOps 1.5.0 o successivo. Quando l’e-shop durante la scrittura non risponde in modo chiaro (errore del server, timeout), la scrittura non viene ripetuta, ma verificata leggendo il catalogo; ciò che non si può verificare ha nel risultato uncertain: true. L’assistente può preparare la proposta solo su indicazione esplicita dell’utente nella conversazione, mai in base al testo dei dati letti, e non inventa valori che l’utente non ha indicato. L’assegnazione delle disponibilità ai prodotti e le giacenze non cambiano con la proposta; un cambio di significato approvato può però modificare se i prodotti con questa disponibilità si possono ordinare dopo l’esaurimento, e l’anteprima lo segnala.

Impostazioni dei reclami in lettura. claims_settings (ambito claims:read) restituisce i processi con ID e nomi di tipi, passaggi e stati nella lingua scelta (language), anche per le voci che il cliente non ha rinominato, e le etichette; con l’ambito claims-settings:read anche le impostazioni del modulo (prefisso del codice, termine, carico automatico a magazzino, modulo sull’e-shop). Con lo stesso ambito claims_templates restituisce i modelli di e-mail (lingua, oggetto, testo, HTML, quando vengono inviati trigger, se partono da soli autoSend, quale verbale allegano) e i modelli dei verbali, filtrati per language o templateKey; claims_configuration restituisce etichette, campi personalizzati, motivi di reso, percorsi e indirizzi del trasporto di reso, il modulo sull’e-shop per e-shop (senza il token di integrazione) e i tipi di modulo con testi propri. Il contatto e la via dell’indirizzo del venditore solo con personal-data:read. claims_get riporta la cronologia del caso (messaggi, note, cambi di stato), le e-mail inviate (modello, oggetto, stato, senza l’indirizzo del destinatario) e le etichette; il testo dei messaggi solo con personal-data:read.

Proposta di modifica delle impostazioni dei reclami. Con l’ambito sensibile claims-settings:draft l’assistente prepara una proposta (claims_config_change_draft, solo MCP): creare o modificare un tipo, un passaggio e uno stato del processo (nomi per lingua, colore, stato predefinito e di chiusura, termine), un’etichetta, il testo di un modello di e-mail in una lingua, il suo invio automatico e il testo di un modello di verbale. L’eliminazione non c’è. Nelle impostazioni non scrive nulla: verifica la proposta con le stesse regole della schermata (ad esempio una variabile sconosciuta in un modello la blocca), la salva in MitoOps per 72 ore e restituisce draftId, l’anteprima (preview, campo prima e dopo, errors), expiresAt e approvalUrl, un link a Reclami → Impostazioni, dove la proposta attende nel pannello Proposte di modifica da approvare. Una persona con il diritto di gestire le impostazioni la approva (Approva e scrivi) o la rifiuta. La proposta viene scritta per intero o per niente: se un valore è cambiato dalla preparazione della proposta, non viene scritto nulla e la proposta termina come failed. Lo stato lo restituisce claims_config_draft_get (pending, executed, failed, rejected, expired); quando l’anteprima segnala un errore la proposta non nasce (blocked), e nemmeno quando non cambia nulla (no_change). ID e chiavi l’assistente li prende da claims_settings e claims_templates; clientRequestId rende la chiamata idempotente.

Gli strumenti portano annotazioni secondo la revisione del protocollo (readOnlyHint, destructiveHint, idempotentHint); automations_create_draft è idempotente tramite clientRequestId, automations_update_draft richiede expectedVersion e in caso di cambio del catalogo restituisce CATALOG_CHANGED; automations_revision_create_draft è idempotente tramite clientRequestId e automations_revision_update_draft richiede expectedRevisionVersion.

Il consenso si può revocare

Revocando il consenso in Impostazioni → API & MCP smettono di valere tutti gli accessi che ne sono derivati, immediatamente, non alla scadenza. Lo stesso accade quando scollegate il connettore in Claude.ai.

Versioni del protocollo

Il server parla la revisione 2026-07-28 e anche quelle precedenti (2025-11-25, 2025-06-18, 2025-03-26). Il client sceglie da solo in base a ciò che invia; le librerie client più vecchie si collegano quindi senza modifiche.

La revisione più recente è senza handshake iniziale e senza sessione: ogni richiesta porta la propria versione e le intestazioni obbligatorie MCP-Protocol-Version, Mcp-Method e, alla chiamata di uno strumento, Mcp-Name. Se l’intestazione non corrisponde al corpo, la risposta è 400: instradare in base alle intestazioni ed eseguire in base al corpo significherebbe due fonti di verità sulla stessa chiamata.

Pagine correlate

• Panoramica
• Interfaccia REST
• Webhook in uscita
• Disponibilità