Come collegare Mirakl Connect a Microsoft Copilot via MCP

💡 Niente installazione? Vai direttamente su cloud.anythingmcp.com. Accedi, clicca Connectors → Mirakl Connect, inserisci le credenziali, genera una MCP API key e hai finito. Niente Docker, niente git clone, niente server locale.

Mirakl Connect + Microsoft Copilot

Mirakl Connect per i venditori: ordini di tutti i marketplace e canali collegati in un unico posto, resi, documenti, conversazioni con i clienti e catalogo Connect con prezzi e giacenze. Non è la Mirakl Seller API di un singolo marketplace. Spedizione, annullamento e accettazione sono disattivati all'installazione.

Prerequisiti

Le istruzioni di setup complete sono incluse nel connettore stesso (visibili nello store quando lo selezioni). Le variabili d'ambiente richieste sono:

MIRAKL_CONNECT_CLIENT_ID, MIRAKL_CONNECT_CLIENT_SECRET

Step 1 — Ottieni le credenziali

Non è la Mirakl Seller API: il connettore separato Mirakl Seller API (mirakl) parla con un marketplace basato su Mirakl alla volta, tramite la sua https://<marketplace>.mirakl.net/api con una chiave API del negozio. Mirakl Connect è la piattaforma di canali lato venditore che sta sopra: un solo login e una sola API (https://miraklconnect.com/api) per tutti i marketplace e canali di vendita della tua azienda, con propri id d'ordine, credenziali OAuth2 ed endpoint. Installa questo quando la tua azienda lavora in Mirakl Connect.

La configurazione richiede circa 5 minuti.

1. Crea in Mirakl Connect le credenziali API OAuth2 per la tua azienda, come descritto nella guida di Mirakl Integrating with Connect APIs (aiuto di Mirakl Connect per i venditori). Ottieni un client ID e un client secret; il secret viene mostrato una sola volta.
2. Incollali in MIRAKL_CONNECT_CLIENT_ID e MIRAKL_CONNECT_CLIENT_SECRET. AnythingMCP li scambia presso il Mirakl Authentication System (https://auth.mirakl.net/oauth/token, grant client credentials) con un token bearer di circa un'ora e lo rinnova da solo.
3. Installa il connettore ed esegui mirakl_connect_list_orders: elenca i tuoi ultimi ordini e conferma le credenziali.

Id d'ordine e canali: ogni ordine ha un id d'ordine Connect (id), che mirakl_connect_get_order e i tool di scrittura richiedono, e il numero d'ordine proprio del canale in channel_order_id. Canale di vendita e negozio sono in origin (channel_name, channel_store_name). La Mirakl Connect API non ha un endpoint che elenchi i canali collegati; l'AI li ricava dall'origin degli ordini.

Cosa legge: gli ordini di tutti i canali collegati, dai più recentemente aggiornati, con stato, origine, righe d'ordine (prodotto, quantità, prezzo, imposte, stato della riga), dati di spedizione e fatturazione e tipo di evasione (FULFILLED_BY_SELLER o FULFILLED_BY_PARTNER); senza updated_from o id, Mirakl restituisce gli ultimi 30 giorni. Il catalogo prodotti Connect con titoli, marca, categoria, GTIN, immagini, prezzi standard e scontati, quantità in giacenza e attributi. I resi di tutti i canali, con stato (REQUEST_INITIATED, REQUEST_DECLINED, OPENED, RECEIVED, CLOSED), righe di reso, metodo, id RMA, URL dell'etichetta, tracking e motivo del rifiuto. I documenti degli ordini come fatture al cliente, documenti di trasporto ed etichette di reso. Le conversazioni dei clienti sugli ordini e i messaggi di una conversazione con autore, testo e allegati. L'esito di un'azione asincrona su un ordine.

Filtri: gli ordini si filtrano per statuses, updated_from, fulfillment_type e id d'ordine. I resi richiedono updated_from. I documenti richiedono id d'ordine o updated_from, le conversazioni updated_from o id di conversazione.

Disattivati all'installazione: mirakl_connect_ship_order (segna le righe come spedite e passa corriere e tracking al canale, che di solito avvisa il cliente), mirakl_connect_cancel_order_lines (il cliente viene rimborsato e avvisato sul canale; irreversibile) e mirakl_connect_accept_order_lines (accetta o rifiuta righe in AWAITING_ACCEPTANCE; il rifiuto annulla la riga ed è irreversibile). Agiscono sul canale di vendita live, quindi un admin li attiva consapevolmente. Anche allora l'AI ti mostra l'ordine, le righe e i valori e aspetta il tuo sì, prendendo gli id delle righe da order_lines[].id dell'ordine. Queste chiamate sono asincrone: restituiscono un action_id, e l'AI verifica l'esito con mirakl_connect_get_action_status, perché il canale può ancora rifiutare l'azione.

Paginazione e limiti: ogni elenco risponde con next_page_token finché ci sono altri elementi, e l'AI lo passa come page_token. Ordini e resi sono 10 per pagina di default (fino a 100), documenti e conversazioni 50 (fino a 100); i prodotti arrivano a 1000 per pagina, e l'AI usa una pagina piccola a meno che non serva l'intero catalogo. Mirakl chiede di richiamare gli elenchi di ordini, resi e prodotti al massimo una volta al minuto durante la sincronizzazione. Le date sono ISO 8601 con fuso orario.

Errori comuni: 401 significa client ID o secret errati, oppure token scaduto. 403 significa che al client API manca lo scope per quella chiamata, ad es. connect:order:read o connect:shipment:create. 402 significa che la funzione, ad es. le conversazioni, non è inclusa nel piano Mirakl Connect dell'account. 404 indica un id d'ordine o di conversazione sconosciuto. 429 significa troppe chiamate: attendi Retry-After.

Il connettore non modifica prezzi o giacenze, non risponde alle conversazioni, non crea resi e non collega nuovi canali. Per un singolo marketplace Mirakl senza Mirakl Connect usa il connettore Mirakl Seller API.

Step 2 — Installa l'adapter

curl -fsSL https://raw.githubusercontent.com/HelpCode-ai/anythingmcp/main/docker-compose.quickstart.yml -o docker-compose.yml
printf 'JWT_SECRET=%s\nENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
docker compose up -d

Step 3 — Aggiungi il connettore in Microsoft Copilot

L'URL del tuo server: in AnythingMCP apri MCP Servers → il server su cui si trova questo connettore e copia il suo URL (https://cloud.anythingmcp.com/mcp/…). Usalo ovunque questa guida mostra YOUR_SERVER_ID.

Microsoft Copilot usa i server MCP tramite gli agenti creati in Copilot Studio: aggiungi AnythingMCP a un agente come strumento, poi pubblichi l'agente in Microsoft 365 Copilot e in Teams. Copilot Studio si collega dal cloud di Microsoft via Streamable HTTP, che AnythingMCP supporta.

1. In Copilot Studio apri il tuo agente (o creane uno), vai su Tools e scegli Add a tool → New tool → Model Context Protocol.
2. Inserisci un Server name (per esempio AnythingMCP), una Server description che dica cosa fa il connettore e il Server URL https://cloud.anythingmcp.com/mcp/YOUR_SERVER_ID. Copilot Studio usa la descrizione per decidere quando chiamare il server.
3. Come autenticazione scegli API key, imposta Type su Header e come nome dell'header X-API-Key, poi seleziona Create.
4. In Add tool scegli Create a new connection, incolla una chiave API MCP di AnythingMCP (MCP Servers → il tuo server → API keys) e seleziona Add to agent.
5. Provalo nel riquadro Test dell'agente: chiedi qualcosa che richiede i tool di Mirakl Connect.
6. Seleziona Publish, poi Channels → Microsoft 365 and Microsoft Teams, lascia selezionato Make agent available in Microsoft Copilot e scegli Add channel. See agent in Teams lo installa per te; in Microsoft 365 Copilot scrivi @ e scegli l'agente.

Preferisci un accesso per ogni utente? Al posto della chiave API scegli OAuth 2.0 → Dynamic discovery: ogni persona accede ad AnythingMCP la prima volta che l'agente lo chiama.

Usi il self-hosting? Usa l'indirizzo HTTPS pubblico della tua istanza al posto di https://cloud.anythingmcp.com. Copilot Studio si collega dal cloud di Microsoft, quindi localhost non funziona.

Tool disponibili

Esempi di prompt

• "Quali ordini sono arrivati da ieri su tutti i nostri canali, raggruppati per canale?"
• "Trova l'ordine con numero d'ordine del canale 405-1234567-1234567 e mostra le righe e il loro stato."
• "Elenca i resi aperti questa settimana con canale, motivo e tracking."
• "Mostra le conversazioni dei clienti aggiornate oggi e riassumi cosa vuole ciascun cliente."
• "Spedisci la riga 1 di quest'ordine con il tracking DHL 00340434161234567890. Mostrami prima l'ordine e le righe."

FAQ

Per quale Copilot vale? Per Microsoft 365 Copilot in azienda, tramite gli agenti di Copilot Studio. L'app Microsoft Copilot per account personali non permette di aggiungere un proprio server MCP.

Cosa mi serve? Un account di lavoro con accesso a Copilot Studio (licenza o prova) per creare l'agente. Chi lo usa in Microsoft 365 Copilot o in Teams deve avere accesso all'agente: condividilo, oppure chiedi a un amministratore di pubblicarlo per l'organizzazione. Se la tua organizzazione applica criteri sui dati ai connettori di Power Platform, valgono anche per i server MCP.

L'agente non chiama i tool. Controlla che il nome dell'header sia esattamente X-API-Key e che la chiave appartenga allo stesso server MCP dell'URL, e scrivi una Server description precisa: Copilot Studio la usa per decidere quando chiamare il server. Dopo ogni modifica pubblica di nuovo l'agente; in una chat già aperta scrivi "start over" per passare alla nuova versione.

Prossimi passi

• Landing del connettore
• Collegare a Claude
• Collegare a ChatGPT
• Collegare a Cursor
• Collegare a Gemini
• Collegare a Meta Muse