1. Centro Assistenza
  2. Pilota / Beta
  3. Altre pubblicazioni

Beta: Collegamento degli assistenti IA compatibili con MCP al tuo account Guesty

Questo articolo spiega come connettere gli assistenti AI compatibili con il Model Context Protocol (MCP) al tuo account Guesty utilizzando il Guesty MCP Server. Ciò consente ad assistenti come Cursor, Claude Desktop e VS Code di recuperare ed elaborare i dati Guesty a cui sei autorizzato ad accedere.

Importante:

Guesty MCP Server è una funzionalità sperimentale in una versione beta preliminare. Non utilizzatela in ambienti di produzione. In questa fase, il server consente solo l'accesso in sola lettura, il che significa che gli assistenti possono consultare e riepilogare i dati, ma non possono creare, aggiornare o eliminare i record Guesty.

Panoramica del server Guesty MCP

Il server espone le funzionalità Guesty supportate come strumenti MCP. Il tuo assistente AI può utilizzare solo gli strumenti registrati sul server MCP e autenticati con le tue credenziali API Guesty.

I casi d'uso tipici includono:

  • Ricerca dei record Guesty supportati da un assistente
  • Riepilogo delle informazioni su prenotazione, proprietà o ospite
  • Analisi di questioni operative utilizzando i dati autorizzati Guesty
  • Ridurre le ricerche manuali mantenendo le credenziali API fuori dai messaggi di chat

Prima di iniziare

  • Ti serviranno i tuoi client_id e client_secret API Guesty.
  • Per il metodo di connessione locale consigliato, è necessario avere Node.js 20 o versioni successive installate e disponibili nel PATH di sistema.

Ottieni il tuo token API Guesty

Per connettere il tuo assistente, ti serve innanzitutto un token bearer API Guesty. Puoi ottenerlo scambiando le tue credenziali client OAuth con un token di accesso.

I tuoi client_id e client_secret sono disponibili nel tuo account Guesty. Per ulteriori informazioni, consulta il nostro articolo sull'utilizzo API aperta di Guesty.

Nota:

Se configuri il tuo client MCP per utilizzare direttamente il tuo CLIENT_ID e CLIENT_SECRET , puoi saltare la fase di scambio manuale dei token.

  1. Esegui il seguente comando curl nel tuo terminale, sostituendo your-client-id e your-client-secret con le tue credenziali effettive.

  2. Bash

     curl -s -X POST https://open-api.guesty.com/oauth2/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials" \ -d "client_id=your-client-id" \ -d "client_secret=your-client-secret" \ -d "scope=open-api"
  3. Una richiesta andata a buon fine restituisce una risposta simile a questa:

  4. JSON

     { "token_type": "Bearer", "access_token": "eyJ...", "expires_in": 86400 }
  5. Copia il valore di access_token. Questo è il token di accesso che utilizzerai per configurare il tuo client. I token in genere scadono dopo 24 ore.

Nota:

Per evitare di raggiungere i limiti di tariffa API, riutilizza i tuoi token Guesty fino alla loro scadenza.

Scegli un metodo di connessione

È possibile connettersi al server Guesty MCP in due modi: localmente tramite stdio o tramite un endpoint HTTP ospitato. Per la maggior parte degli utenti, consigliamo la configurazione locale tramite stdio, in quanto evita di visualizzare le credenziali nella chat.

Modalità Punto finale / Comando Ideale per
Locale (stdio) — consigliato npx -y @guestyorg/sdk mcp Predefinito per tutti i client supportati; credenziali in env ; blocco della versione SDK
Ospitato (HTTP) https://mcp.guesty.com/v1 Nessun Node.js installato sulla macchina, né implementazione gestita da Guesty.

Collega il tuo client MCP

Segui le istruzioni riportate di seguito per il tuo specifico client di assistente AI.

Connetti Cursor

  1. Apri il file di configurazione MCP, che si trova in ~/.cursor/mcp.json (per le impostazioni utente) oppure nella configurazione MCP del tuo progetto.
  2. Aggiungi una delle seguenti configurazioni:
    Consigliato — Studio locale

  3. JSON

     { "mcpServers": { "guesty": { "command": "npx", "args": ["-y", "@guestyorg/sdk", "mcp"], "env": { "BEARER_TOKEN": "eyJ..." } } } }
  4. Alternativa: ospitato con intestazione di autorizzazione

  5. JSON

     { "mcpServers": { "guesty": { "url": "https://mcp.guesty.com/v1", "headers": { "Authorization": "Bearer your-guesty-token" } } } }
  6. Riavvia Cursor e verifica che il server Guesty risulti connesso in "Impostazioni → Pannello di controllo principale".

Torna all'inizio

Collega Claude Desktop

  1. Apri il file di configurazione di Claude Desktop.
    1. macOS: ~/Library/ Applicazione Supporto/Claude/claude_desktop_config.json
    2. Windows: %APPDATA%\Claude\claude_desktop_config.json
  2. Aggiungi una delle seguenti configurazioni:
    Consigliato — Studio locale

  3. JSON

     { "mcpServers": { "guesty": { "command": "npx", "args": ["-y", "@guestyorg/sdk", "mcp"], "env": { "BEARER_TOKEN": "eyJ..." } } } }
  4. Alternativa — Ospitata
    Poiché Claude Desktop non supporta intestazioni personalizzate nella sua configurazione MCP, è necessario autenticarsi per ogni sessione.
    1. Aggiungi quanto segue al tuo file di configurazione:

    2. JSON

       { "mcpServers": { "guesty": { "url": "https://mcp.guesty.com/v1" } } }
    3. Dopo la connessione, chiedi all'assistente di autenticarsi inviando un messaggio come questo: Il mio token Guesty è eyJ... — per favore autenticati .
    4. L'assistente utilizzerà lo strumento set_token per memorizzare il token per la sessione corrente. È necessario ripetere questa operazione per ogni nuova sessione.

Torna all'inizio

Collega VS Code (GitHub Copilot)

  1. Apri il file di configurazione di MCP.
    • Area di lavoro: .vscode/mcp.json
    • Utente: Apri la "Palette dei comandi" e seleziona "MCP: Apri configurazione Utente".
  2. Aggiungi una delle seguenti configurazioni all'interno dell'oggetto server :
    Consigliato — Studio locale

  3. JSON

     { "servers": { "guesty": { "type": "stdio", "command": "npx", "args": ["-y", "@guestyorg/sdk", "mcp"], "env": { "BEARER_TOKEN": "eyJ..." } } } }
  4. Alternativa — Ospitata

  5. JSON

     { "servers": { "guesty": { "type": "http", "url": "https://mcp.guesty.com/v1", "headers": { "Authorization": "Bearer your-guesty-token" } } } }
  6. Ricarica la finestra o riavvia l'host MCP. Verifica che Guesty sia pubblicato e connesso nelle impostazioni di Copilot Chat su MCP.

Torna all'inizio

Collega Google Antigravità

  1. Apri il file di configurazione MCP, che si trova in ~/.gemini/config/mcp_config.json . Puoi aprirlo anche dal pannello dell'agente selezionando "Gestisci server MCP → Visualizza configurazione non elaborata".
  2. Aggiungi una delle seguenti configurazioni:
    Consigliato — Studio locale

  3. JSON

     { "mcpServers": { "guesty": { "command": "npx", "args": ["-y", "@guestyorg/sdk", "mcp"], "env": { "BEARER_TOKEN": "eyJ..." } } } }
  4. Alternativa — Ospitata

  5. JSON

     { "mcpServers": { "guesty": { "serverUrl": "https://mcp.guesty.com/v1", "headers": { "Authorization": "Bearer your-guesty-token" } } } }
  6. Riavvia Antigravity dopo la modifica. Su macOS, se l'IDE non riesce a trovare npx , usa il percorso completo di npx (ad esempio, /opt/homebrew/bin/npx ) nel campo dei comandi .

Torna all'inizio

Avanzato: Utilizzo Credenziali client OAuth2

In alternativa all'utilizzo di un token bearer, è possibile fornire direttamente CLIENT_ID e CLIENT_SECRET nella configurazione. Il server effettuerà lo scambio dei token all'avvio.

JSON

 { "mcpServers": { "guesty": { "command": "npx", "args": ["-y", "@guestyorg/sdk", "mcp"], "env": { "CLIENT_ID": "your-client-id", "CLIENT_SECRET": "your-client-secret" } } } }

Torna all'inizio

Avanzate: Blocco di una versione di rilascio

Per garantire un comportamento riproducibile, è possibile specificare una versione specifica dell'SDK Guesty nell'array args .

JSON

 "args": ["-y", "@guestyorg/sdk@0.2.0", "mcp"]

Torna all'inizio

Come utilizzare la connessione

Una volta che il tuo cliente è connesso e autenticato, puoi porre al tuo assistente domande sui tuoi dati Guesty. L'assistente rileva automaticamente gli strumenti Guesty disponibili e li utilizza quando necessario per rispondere alle tue richieste.

Esempi di richieste:

  • "Trova la prenotazione con il codice conferma ABC123."
  • "Riepiloga i dettagli della prenotazione attuale di questo ospite."
  • "Consulta l'annuncio di questa proprietà."

Migliori pratiche di sicurezza

  • Conserva in un luogo sicuro il tuo token bearer Guesty, poiché ti garantisce l'accesso API al tuo account.
  • È preferibile utilizzare il metodo stdio locale con BEARER_TOKEN in env oppure il metodo ospitato con le intestazioni di autorizzazione. Questo impedisce che i token siano visibili nella cronologia della chat.
  • Se proprio devi usare lo strumento set_token, evita di incollare i token in sessioni condivise o registrate.
  • Non passare i token come parametri di query URL.
  • Non inserire nel sistema di controllo versione i file di configurazione MCP contenenti token attivi.
  • Aggiorna le tue credenziali in base alle politiche di sicurezza della tua organizzazione.

Distribuzioni gestite

Per le implementazioni dedicate in cui Guesty gestisce le credenziali lato server, è sufficiente connettersi tramite URL. Non è richiesta alcuna configurazione del token lato client.

JSON

 { "mcpServers": { "guesty": { "url": "https://mcp.guesty.com/v1" } } }

Contatta Guesty per configurare un'implementazione gestita.

Come il server utilizza il tuo token

Il token utilizzato per le chiamate API Guesty è determinato dalla modalità con cui viene fornito. Tutte le chiamate API all'interno di una sessione utilizzano il token associato a quella sessione e le sessioni sono isolate l'una dall'altra.

Fonte Quando si applica
BEARER_TOKEN o ambiente OAuth (stdio) Applicato all'avvio del processo del server MCP
Intestazione di autorizzazione (ospitata) Associato all'inizializzazione della sessione MCP
Strumento set_token (ospitato, Agent Desktop) Memorizzato immediatamente per il resto della sessione

Correlato a:

Questo articolo ti è stato utile?
Utenti che ritengono sia utile: 0 su 0