Un server MCP di prenotazione turistica
per agenti IA.

Adrasis gestisce un server Model Context Protocol (MCP) basato su Distribution Partner API. Gli agenti IA cercano e prenotano alloggi, transfer, escursioni, voli charter e pacchetti secondo le regole dell'API, all'interno di un account partner.

Un server MCP remoto basato su Partner API.

Il server incapsula il contratto REST di Adrasis Distribution Partner API. Il tuo agente chiama strumenti invece di endpoint, e ogni strumento si comporta come la chiamata REST corrispondente.

Nel confronto tra server MCP per il turismo, tre domande decidono quasi tutto: da dove viene l'offerta, chi controlla cosa può fare un agente e se una prenotazione è reale. Qui l'offerta è quella che un'agenzia o un tour operator gestisce in Adrasis Console, e il titolare controlla l'accesso tramite un account partner e i relativi permessi. Una chiamata book andata a buon fine crea la prenotazione e riduce l'inventario, come una prenotazione REST.

Nulla viene reinterpretato per gli agenti. Gli strumenti usano gli stessi schemi di richiesta e risposta, la stessa logica di business, gli stessi prezzi e le stesse regole di utilizzo del contratto REST, quindi un agente e un'integrazione tradizionale lavorano con un unico insieme di regole.

# Server MCP remoto, streamable HTTP
https://ari.console.adrasis.com/mcp

# Token di accesso OAuth 2.0
Authorization: Bearer <token di accesso>

Un agente può anche fare a meno di MCP e chiamare direttamente l'API REST. Il contratto completo dell'API, in formato leggibile dalle macchine, è pubblicato nel riferimento API (in inglese).

MCP e Operatore IA di Adrasis.

Il server MCP serve a un agente IA che prenota dall'offerta di un'altra azienda tramite un account partner. L'Operatore IA svolge il lavoro all'interno della tua organizzazione.

Le parti coinvolte sono due. Il titolare dell'inventario è un'agenzia o un tour operator che tiene contratti e prezzi in Adrasis Console. Il partner sviluppa l'agente: una OTA (agenzia di viaggi online), un'app di viaggi, un'altra agenzia o un partner tecnologico. Il titolare crea un account partner, abilita le strutture che il partner può prenotare e rilascia le credenziali, e l'agente opera solo all'interno di quell'account.

L'Operatore IA lavora sui tuoi dati

Il tuo team invia istruzioni dal pannello chat della Console, via email o WhatsApp. L'Operatore IA prepara il lavoro su catalogo, tariffe, contratti e distribuzione della tua organizzazione. Gli SMS servono per avvisi e approvazioni delle operazioni. Le richieste di sola lettura ricevono risposta subito. Tutto ciò che modifica i dati viene mostrato in anteprima ed eseguito solo dopo la tua conferma, e l'Operatore IA non legge mai i dati di un'altra organizzazione. Scopri come funziona l'Operatore IA.

Quali strumenti può chiamare un agente?

Ogni strumento corrisponde a un'operazione REST e ne usa gli schemi di richiesta e risposta. Gli strumenti sono raggruppati per prodotto e ciascuno richiede uno dei due permessi.

Alloggi

Dati di riferimento, contenuti delle strutture, ricerca della disponibilità e intero ciclo di vita della prenotazione per hotel, case vacanza, ville e appartamenti. «Strutture aperte» è l'elenco delle strutture aperte a un singolo profilo partner.

Strumento Cosa fa Permesso
search_property_availability Trova l'offerta più economica per ciascuna struttura, fino a 200 strutture. distribution:read
search_place_availability Trova le offerte più economiche in una destinazione, fino a 100 strutture per pagina. distribution:read
list_countries Elenca i paesi con ID, codici ISO e nomi localizzati. distribution:read
list_place_types Elenca gli otto tipi di luogo e quali sono ricercabili in ciascun paese. distribution:read
list_places Trova le destinazioni per paese, tipo, luogo di appartenenza o nome. distribution:read
list_properties Elenca i contenuti delle strutture in «Strutture aperte», senza prezzi. distribution:read
get_property Legge il contenuto completo di una struttura. distribution:read
prebook Ricalcola il prezzo dell'offerta scelta; restituisce un token di preprenotazione, lo stato di corrispondenza e le condizioni di cancellazione. distribution:booking
book Conferma la prenotazione, con una chiave di idempotenza per ripetere la richiesta in sicurezza. distribution:booking
get_booking Legge una prenotazione o verifica periodicamente lo stato di una in sospeso. distribution:booking
list_bookings Riconcilia le prenotazioni in base al tuo riferimento, a un intervallo di date o alle modifiche recenti. distribution:booking
cancellation_quote Mostra in anteprima la penale di cancellazione senza modificare nulla. distribution:booking
cancel Cancella la prenotazione e applica la relativa penale. Si può ripetere senza rischi. distribution:booking

La ricerca di offerte su una singola struttura è disponibile solo via REST. Restituisce l'offerta migliore per l'intero gruppo, seguita da tutte le opzioni di camera e piano tariffario disponibili per ogni camera richiesta, a partire dalla più economica, con quantità selezionabili.

Transfer, escursioni e voli

Ogni prodotto segue lo stesso schema di ricerca, preprenotazione e prenotazione degli alloggi. I voli sono voli charter e per un'andata e ritorno si cercano due tratte separate.

Strumento Cosa fa Permesso
search_transfers Trova offerte di transfer tra due zone per una data di servizio e un gruppo. distribution:booking
prebook_transfer Ricalcola il prezzo di un'offerta di transfer e restituisce un token di preprenotazione con le relative condizioni di cancellazione. distribution:booking
book_transfer Conferma il transfer, con una chiave di idempotenza. distribution:booking
search_tours Trova offerte per un'escursione in una data di partenza e per un gruppo. distribution:booking
prebook_tour Ricalcola il prezzo di un'offerta di escursione e restituisce un token di preprenotazione con le relative condizioni di cancellazione. distribution:booking
book_tour Conferma l'escursione, con una chiave di idempotenza. distribution:booking
search_flights Trova offerte di voli charter in base alla data di partenza e alla composizione dei passeggeri. distribution:booking
prebook_flight Ricalcola il prezzo di un'offerta di volo e restituisce un token di preprenotazione con le relative condizioni di cancellazione. distribution:booking
book_flight Conferma la prenotazione del volo, con una chiave di idempotenza. distribution:booking

Pacchetti

Un pacchetto mette in vendita da 2 a 8 servizi già scelti dall'agente, di almeno due tipi di prodotto, a un unico prezzo complessivo. O si confermano tutti i servizi o nessuno. Una volta prenotato, un pacchetto si consulta e si cancella con get_booking, cancellation_quote e cancel, e gli ultimi due possono riguardare anche singoli servizi al suo interno.

Strumento Cosa fa Permesso
search_packages Combina da 2 a 8 servizi scelti in un'unica offerta con un unico prezzo complessivo. distribution:booking
prebook_package Ricontrolla ogni servizio e restituisce lo stato di corrispondenza, l'informativa di conformità e un token di preprenotazione. distribution:booking
book_package Prenota l'intero pacchetto in un'unica operazione: o si confermano tutti i servizi o nessuno. distribution:booking

Raggruppamento in viaggi

Un viaggio raggruppa in un unico itinerario prenotazioni già confermate. Ogni prenotazione mantiene il proprio totale, le proprie condizioni di cancellazione e il proprio ciclo di vita, quindi un viaggio non è mai un pacchetto con un suo prezzo.

Strumento Cosa fa Permesso
create_trip Raggruppa prenotazioni confermate in un unico viaggio. I prezzi restano separati. distribution:booking
get_trip Legge un viaggio con le sue prenotazioni e i totali per valuta. distribution:booking
add_trip_member Aggiunge una prenotazione esistente a un viaggio. distribution:booking
remove_trip_member Toglie una prenotazione da un viaggio senza modificarla. distribution:booking
cancel_trip Cancella tutte le prenotazioni del viaggio e riporta l'esito di ciascuna. distribution:booking

Come fa un agente a prenotare un soggiorno?

Il flusso documentato ha otto passaggi, dalla geografia alla cancellazione. L'agente si ferma due volte in attesa della conferma dell'utente: prima di prenotare e prima di cancellare.

  1. Individua la geografia. Chiama list_countries, list_place_types e list_places per trovare il paese, i tipi di luogo ricercabili in quel paese e la destinazione stessa, ad esempio Antalya.
  2. Costruisci il contesto senza prezzi. Leggi i contenuti delle strutture dall'elenco «Strutture aperte» con list_properties e get_property. Nessuna delle due accetta un punto vendita come parametro.
  3. Cerca. Chiama search_property_availability per strutture note, oppure search_place_availability per esplorare una destinazione. Indica il criterio di allocazione: strict mantiene ogni camera esattamente come richiesta, flexible consente di distribuire il gruppo su un massimo di nove camere. Conserva lato server il selection_token dell'offerta scelta.
  4. Preprenota. Passa quel token a prebook, che ricalcola il prezzo dell'offerta. Leggi lo stato di corrispondenza e le condizioni di cancellazione, poi chiedi all'utente di confermarli entrambi.
  5. Prenota. Chiama book con i dati degli ospiti e di contatto e una idempotency_key univoca. Un nuovo tentativo con la stessa chiave e lo stesso corpo della richiesta entro 24 ore dalla prima richiesta restituisce la prenotazione originale invece di crearne una seconda.
  6. Verifica lo stato. Se la prenotazione risulta in attesa, ad esempio su una tariffa che attende l'accettazione della struttura, chiama get_booking finché lo stato non si stabilizza.
  7. Riconcilia. Abbina le prenotazioni dell'account con list_bookings, usando il tuo agency_reference oppure un intervallo limitato per data o per data di modifica. I risultati non contengono dati personali degli ospiti.
  8. Cancella su richiesta. Mostra la penale con cancellation_quote e chiama cancel solo quando l'utente conferma.

La preprenotazione non blocca l'inventario. La disponibilità viene ricontrollata quando viene eseguito book, quindi l'ultima camera può andare a qualcun altro tra i due passaggi e in quel caso l'agente ripete la ricerca. Un token di preprenotazione è valido 30 minuti e consente una sola prenotazione.

Nessun pagamento passa dal server. Il partner resta l'esercente responsabile della transazione. Le tariffe che richiedono un pagamento da effettuare altrove, come un addebito su carta o un piano di acconti, non si possono prenotare in questo modo.

Come si autentica l'agente?

Con le stesse credenziali client OAuth 2.0 usate da un'integrazione REST. Una sessione dell'agente si autentica esattamente come un client REST.

Il partner scambia il proprio client ID e client secret con un token di accesso su https://ari.console.adrasis.com/api/v1/oauth/token. Il token è valido per un'ora e non viene emesso alcun refresh token: alla scadenza, l'agente ne richiede uno nuovo con le stesse credenziali. La documentazione consiglia di mantenere un solo token e rinnovarlo poco prima della scadenza, invece di richiederne uno per ogni chiamata.

Il token viaggia nell'header Authorization della sessione MCP. L'account del partner e i permessi del token vengono inoltrati invariati a ogni chiamata a uno strumento, e una chiamata a uno strumento per cui il token non ha il permesso richiesto viene rifiutata.

Due permessi

Permesso Cosa copre
distribution:read Dati di riferimento, contenuti delle strutture e ricerca della disponibilità degli alloggi.
distribution:booking Per gli alloggi: preprenotazione, prenotazione, lettura delle prenotazioni, preventivi di cancellazione e cancellazione; inoltre tutti gli strumenti per transfer, escursioni, voli, pacchetti e viaggi, compresi quelli di ricerca.

Concedi solo ciò che serve all'agente. Un agente che risponde a domande sulla disponibilità ma non deve mai prenotare riceve solo distribution:read. Le nuove credenziali ricevono entrambi i permessi per impostazione predefinita, quindi, quando crei le credenziali per un agente, scegli il minimo indispensabile. Un token si può anche richiedere con meno permessi di quelli delle sue credenziali. I codici di errore e gli altri dettagli sono nella guida all'autenticazione (in inglese).

Cosa può vedere l'agente?

Solo ciò che il proprietario dell'inventario gli ha aperto. Per gli alloggi, è l'elenco «Strutture aperte» di un profilo partner.

Gli strumenti per le strutture restituiscono le strutture ricettive pubblicate esplicitamente aperte nell'elenco «Strutture aperte» del profilo selezionato, e nient'altro. Ogni account partner parte con un profilo Default, che contiene un'istantanea delle strutture pubblicate al momento della creazione dell'account. Una struttura pubblicata in seguito resta chiusa al partner finché il titolare non la apre. Chiudere una struttura la toglie dai risultati di quel profilo, senza eliminarla né chiuderla negli altri profili.

Quando lo stesso partner ha bisogno di cataloghi separati per pubblici diversi, il titolare aggiunge altri profili all'account. Gli strumenti legati al profilo accettano un profile_public_id facoltativo: omettilo per usare il profilo Default, oppure invialo per selezionare un altro profilo dello stesso account. Ogni risposta con esito positivo indica il profilo effettivamente usato. Le credenziali appartengono all'account, quindi una sola credenziale funziona con tutti i profili.

Vedere una struttura non significa venderla

list_properties e get_property mostrano ciò che è aperto al profilo e non accettano il mercato di vendita come parametro. Tariffe, inventario e regole per destinazione non ampliano né restringono ciò che mostrano. Se un soggiorno può essere venduto a un viaggiatore lo decidono solo gli strumenti di disponibilità, che ricevono come codice paese il mercato di vendita del viaggiatore.

list_bookings è l'eccezione alla selezione del profilo. Legge le prenotazioni dell'intero account, e lì profile_public_id si limita a restringere il report alle prenotazioni create da quel profilo.

Come fa un partner a ottenere l'accesso?

Il titolare dell'inventario configura il partner in Adrasis Console. Sviluppo, certificazione e traffico in produzione usano tutti lo stesso host.

  1. Account partner

    Il titolare apre «Connettività», poi «Canali di vendita», «Partner API» e «Account partner», e crea un account per il rapporto con il partner. Con l'account viene creato un profilo Default.

  2. Strutture aperte

    Il titolare apre in ogni profilo le strutture che intende rendere disponibili: una alla volta, in gruppo o tramite filtri per paese e località.

  3. Credenziali

    Una credenziale con un nome distinto per ogni ambiente, con i permessi minimi. Il segreto viene mostrato una sola volta, quindi va salvato subito in un gestore dei segreti.

  4. Certificazione e messa in produzione

    Le credenziali pilota danno accesso a un catalogo dimostrativo. Al passaggio all'offerta reale, client ID, host e flusso di integrazione restano invariati.

Il catalogo dimostrativo ha tariffe e disponibilità generate per i test, e le prenotazioni di prova non toccano l'inventario reale né generano addebiti. Cancella comunque ogni prenotazione di prova: una prenotazione di prova aperta occupa inventario dimostrativo, e test ripetuti possono iniziare a restituire SOLD_OUT.

Non è pubblicato un limite fisso di richieste. I limiti vengono concordati per ogni connessione, quindi confermali con il tuo referente Adrasis prima di aumentare il traffico. Aggiungere credenziali o profili non aumenta il limite consentito. Il titolare può ruotare, disattivare o revocare una credenziale dalla scheda «Accesso API» dell'account, e una credenziale disattivata o revocata smette di funzionare insieme ai token emessi con essa.

Le operazioni a carico del titolare sono descritte in partner API e credenziali (in inglese). Se il tuo team sta sviluppando un agente IA per il turismo e vuole diventare partner, contattaci.

Pronto a collegare un agente?

Richiedi l'accesso a Console per configurare la tua offerta, oppure parlaci dell'agente che stai sviluppando e dell'accesso di cui ha bisogno.