Come collegare apaleo a Microsoft Copilot via MCP

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

apaleo + Microsoft Copilot

Gestione alberghiera nel PMS cloud apaleo: strutture, camere e tipologie di camera, piani tariffari e tariffe, disponibilità e offerte, prenotazioni, reservation e ospiti, gruppi, folio, pagamenti, fatture, manutenzione, housekeeping e report di performance. Crea prenotazioni, assegna camere ed esegue check-in e check-out. Si collega come app con OAuth2 client credentials; cancellazioni e no-show 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:

APALEO_CLIENT_ID, APALEO_CLIENT_SECRET

Step 1 — Ottieni le credenziali

La configurazione richiede circa 5 minuti. Ti serve un account apaleo con accesso ad Apps. Non c'è un accesso dal browser: il connettore si autentica come app con il grant OAuth2 client credentials.

1. In apaleo apri Apps > Connected apps > Add a custom app (oppure su apaleo.dev registra un OAuth simple client con client credentials).
2. Dai all'app i permessi che servono al team. Per la lettura, per esempio properties.read, unitgroups.read, units.read, rateplans.read, rates.read, services.read, companies.read, availability.read, offers.read, reservations.read, groups.read, blocks.read, folios.read, payments.read, invoices.read, maintenances.read e reports.read; per le scritture reservations.create, reservations.manage, reservations.assign-unit, maintenances.create e operations.change-room-state. Ometti i permessi di scrittura per un connettore in sola lettura.
3. Copia il client id in APALEO_CLIENT_ID e il client secret in APALEO_CLIENT_SECRET. Il secret viene mostrato una sola volta; se lo perdi, creane uno nuovo nell'app.
4. Installa il connettore ed esegui apaleo_list_properties per verificare la connessione.

Il connettore ottiene un token da https://identity.apaleo.com/connect/token e lo rinnova ogni ora. Ogni chiamata gira come custom app con i suoi permessi; un permesso mancante all'app risponde 403.

Cosa legge:

• Inventario e tariffe: strutture (hotel), unit group (tipologie di camera), unit (camere) con stato di pulizia e manutenzione, piani tariffari, prezzi per notte con restrizioni (apaleo_list_rates), servizi (extra come colazione o parcheggio), politiche di cancellazione e aziende (clienti corporate).
• Disponibilità e offerte: camere rimaste per tipologia e notte (apaleo_get_unit_group_availability), camere libere per tutto un soggiorno (apaleo_get_unit_availability), camere assegnabili a una reservation, e apaleo_get_offers, i piani tariffari prenotabili con i prezzi per un soggiorno.
• Prenotazioni e reservation: apaleo_list_reservations con text_search (nome, email, id della reservation) e date_filter Arrival, Departure o Stay insieme a from e to; apaleo_count_reservations conta senza caricarle. Inoltre prenotazioni, servizi di una reservation, gruppi e blocchi. Gli ospiti fanno parte delle reservation (primaryGuest, additionalGuests) e delle prenotazioni (booker).
• Contabilità: folio (conti degli ospiti, da trovare con reservation_ids), pagamenti sui folio e fatture.
• Operatività e report: finestre di manutenzione, performance della struttura (occupazione, ADR, RevPAR), ricavi per conto con netto, lordo e IVA (per al massimo un anno) e arrivi al giorno in un mese.

Cosa scrive:

• Prenotazioni: apaleo_create_booking con il ratePlanId e un timeSlice per notte presi da apaleo_get_offers. apaleo_update_booking e apaleo_update_reservation accettano operazioni JSON Patch come [{"op": "replace", "path": "/comment", "value": "Late arrival"}]. apaleo_amend_reservation cambia arrivo, partenza, numero di ospiti, piano tariffario e prezzo per notte.
• Reception: apaleo_assign_unit (apaleo sceglie una camera libera) oppure apaleo_assign_specific_unit, apaleo_unassign_units, apaleo_check_in_reservation (annullabile con apaleo_revert_check_in) e apaleo_check_out_reservation, che addebita sul folio tutte le voci aperte e funziona solo se la partenza non è oltre domani.
• Housekeeping e manutenzione: apaleo_set_unit_conditions (Clean, CleanToBeInspected, Dirty) e apaleo_create_maintenance (OutOfService, OutOfOrder, OutOfInventory).

Prenotazioni, check-in e check-out cambiano l'hotel in tempo reale, quindi l'AI ti mostra cosa sta per modificare e aspetta il tuo sì.

Disattivati all'installazione: apaleo_cancel_reservation (si applica la penale della politica del piano tariffario e una reservation cancellata non si può riattivare) e apaleo_set_reservation_no_show (addebita la penale di no-show sul folio e non si può annullare). Un admin li attiva quando servono al team.

Formati dei dati: gli id sono codici leggibili: una struttura MUC, una unit group MUC-DBL, una unit MUC-101, un piano tariffario MUC-FLEX-DBL, una prenotazione ABCDEF, le sue reservation ABCDEF-1 e ABCDEF-2, un folio ABCDEF-1-1. Gli importi sono {"amount": 120.0, "currency": "EUR"} in unità intere; il balance di una reservation è negativo quando l'ospite deve ancora pagare. Le date sono YYYY-MM-DD; gli orari sono ISO 8601 con l'offset UTC della struttura. Una notte appartiene al giorno operativo in cui inizia; to è incluso per disponibilità e performance, escluso per il report dei ricavi. Lo stato di una reservation è Confirmed, InHouse, CheckedOut, Canceled o NoShow. I filtri con più valori sono separati da virgole senza spazi (status: Confirmed,InHouse) e expand aggiunge oggetti incorporati (expand: booker,assignedUnits).

Paginazione: le liste accettano page_number (da 1) e page_size (fino a 500) e restituiscono il totale in count. Una pagina oltre la fine risponde 204 No Content: non c'è altro.

Errori comuni: 401 indica client id o secret errati o un token scaduto. 403 indica un permesso mancante sulla custom app. 404 è un id sconosciuto. 422 è una regola di business, per esempio un check-in prima del giorno di arrivo, nessuna camera assegnata o un'offerta esaurita, con il motivo in messages. 429 è il limite di richieste.

Il connettore non registra addebiti o pagamenti, non crea fatture, non modifica piani tariffari, prezzi o inventario e non gestisce utenti o app di apaleo.

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 apaleo.
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 reservation arrivano oggi a MUC e quali non hanno ancora una camera assegnata?"
• "Quante doppie sono ancora libere venerdì e sabato prossimi, e quanto costa la tariffa flessibile per le due notti?"
• "Mostrami occupazione, ADR e RevPAR del mese scorso rispetto al mese precedente."
• "Assegna una camera pulita alla reservation ABCDEF-1 e fai il check-in dell'ospite."
• "Segna le camere da MUC-101 a MUC-105 come pulite e metti MUC-210 fuori servizio fino a lunedì per una doccia rotta."

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