Server MCP

Gli strumenti MCP di Wink sono pubblicati come toolset — endpoint focalizzati, ognuno dedicato a un lavoro specifico. Connetti il tuo client AI a uno o due di questi che corrispondono al tuo lavoro, non a tutti.

Ogni endpoint utilizza il login OAuth2 interattivo (flusso di autorizzazione con codice PKCE): il tuo agente AI apre una scheda del browser, effettui l’accesso con il tuo account Wink, e il gioco è fatto. Nessun segreto client da gestire.

Un integratore di channel manager si connette a un endpoint

claude mcp add wink-channel-manager https://integrations.wink.travel/mcp/channel-manager --transport http

Un albergatore che gestisce le proprie tariffe si connette a un altro

claude mcp add wink-rates https://api.wink.travel/mcp/extranet/rates --transport http

---

Perché gli strumenti sono divisi in endpoint

Wink espone circa 500 strumenti. Fornire tutti a un agente contemporaneamente è tecnicamente possibile — ma una cattiva idea.

Le definizioni degli strumenti consumano contesto. Ogni strumento pubblicizzato da un server MCP viene caricato nella finestra di contesto del modello prima che esegua qualsiasi lavoro, insieme alla sua descrizione e allo schema completo dei parametri. Cinquecento di questi consumano una grande parte del budget che il tuo compito reale richiede, a ogni singola richiesta.

La qualità della scelta diminuisce con l’aumentare della lista. Un agente che sceglie tra 500 strumenti con nomi simili fa scelte peggiori rispetto a uno che sceglie tra 40. Se integri un channel manager, circa venti strumenti sono rilevanti per te; gli altri 480 sono rumore che rende più difficile trovare lo strumento giusto.

Il lavoro è realmente separabile. Chi sincronizza la disponibilità da un PMS e chi cura pagine affiliate condividono quasi nessuno strumento. Dividere per lavoro significa che ogni connessione porta il vocabolario di un solo lavoro.

I toolset non sono permessi

Scegliere un toolset ristretto non limita ciò che il tuo account può fare, e sceglierne uno ampio non concede nulla in più. Ogni strumento applica le stesse autorizzazioni dell’account del portale web, sotto la tua identità autenticata. Se il tuo account non può cancellare una prenotazione nel Wink Portal, nemmeno l’agente può farlo — indipendentemente dall’endpoint a cui è connesso.

Scegli i toolset per focalizzazione, non per sicurezza.

---

Directory degli endpoint

Due host servono i toolset. Il numero di strumenti è approssimativo e cresce nel tempo.

https://api.wink.travel — la piattaforma

Endpoint	Strumenti	Cosa copre
/mcp/extranet/facilities	~64	Inventario prenotabile e in loco: camere e tipologie, spa, ristoranti, sale riunioni, attività, attrazioni, luoghi, altri articoli vendibili
/mcp/extranet/property	~62	Anagrafica della struttura e termini commerciali: profilo e contenuti, extra, politiche di cancellazione, vantaggi, annunci
/mcp/settings	~60	Amministrazione account: profilo e branding dell’entità gestore, manager e loro permessi, personalizzazioni, webhook, preferenze notifiche
/mcp/studio/embeds	~48	Pubblicazione inventario curato: widget, griglie e griglie classificate, card, mappe, link profondi a inventario e pagine fornitori
/mcp/extranet/rates	~44	Prezzi e disponibilità: periodi e allotment di tariffe, piani tariffari, tariffe master, tariffe speciali e promozionali
/mcp/extranet/operations	~39	Gestione operativa della struttura: prenotazioni e ciclo di vita, recensioni ospiti e risposte, feed calendario, attività programmate
/mcp/extranet/distribution	~37	Dove viene venduto l’inventario: canali di vendita e modificatori di tariffa, richieste di affiliazione e fornitori, registrazione, acquisizione lead
/mcp/studio/curation	~35	Creazione di collezioni commercializzabili: liste statiche e dinamiche, liste classificate, ricerche salvate, aggregati di proprietà
/mcp/link-manager	~28	Collezioni di link sindacati, design, categorie e tag, più URL abbreviati
/mcp/reference	~24	Dati di consultazione in sola lettura: paesi, valute e tassi di cambio, lingue, fusi orari, ricerche geografiche, geolocalizzazione IP
/mcp/analytics	~18	Analisi di prenotazioni e ricavi: panoramiche, grafici a linee, classifiche, performance affiliate, metriche di condivisione
/mcp/payment	~18	Operazioni finanziarie: libro mastro, prelievi e stime commissioni, aggregati fondi prenotazioni
/mcp/booking-engine	~17	Percorso di acquisto per il viaggiatore: ricerca e consultazione, carrello e checkout, bucket list, personalizzazione campagne
/mcp/social	~17	Account social connessi, pubblicazione e programmazione post, lettura insight post
/mcp/travel-agent	~8	Prenotazioni facilitate da agenti per conto dei viaggiatori, e report agenti

https://integrations.wink.travel — integrazioni channel manager

Un solo endpoint, perché questo host esiste per un solo lavoro.

Endpoint	Strumenti	Cosa copre
/mcp/channel-manager	~9	Connessione e verifica di integrazione channel manager, PMS o CRS

Integrare un channel manager vs. gestire le proprie tariffe

Sono lavori diversi per persone diverse, e non condividono un endpoint.

Un fornitore di channel manager, PMS o CRS integra una volta sola tramite integrations.wink.travel/mcp/channel-manager, e da lì scambia proprietà, tariffe, disponibilità e prenotazioni tramite quell’integrazione. Quel singolo endpoint è tutta la superficie.

Un albergatore che modifica manualmente le proprie tariffe usa i toolset extranet su api.wink.travel — /mcp/extranet/rates e affini. Questi non fanno parte di un’integrazione channel manager e un integratore non ha motivo di connettersi a essi.

L’amministrazione account è anch’essa su api.wink.travel, in /mcp/settings. Non esiste /mcp/settings sull’host delle integrazioni.

Ogni endpoint include anche uno strumento ping, così puoi confermare che la connessione è attiva prima di chiedere un lavoro reale.

Pagamenti agentici

Per il flusso completo di prenotazione del viaggiatore, connetti Wink Booking Engine su https://api.wink.travel/mcp/booking-engine e un wallet di pagamento compatibile. Aggiungere il MCP di Wink apre il login nel browser e la selezione dei permessi; il tuo client gestisce poi l’autenticazione.

Booking Engine include ricerca destinazioni, ricerca hotel e camere, agentic_booking_quote, agentic_booking_pay, agentic_booking_book, recupero prenotazioni e ricevute, quando prenotazione e pagamento agentici sono abilitati per quell’ambiente. Vedi Agentic Payments per configurazione, permessi da selezionare e passaggi dalla ricerca alla conferma.

---

Quali toolset mi servono?

Se sei…	Connettiti a
Integratore di channel manager, PMS o CRS	integrations.wink.travel/mcp/channel-manager — solo questo
Gestore del contenuto di una struttura	/mcp/extranet/property + /mcp/extranet/facilities
Gestore di camere e tipologie	/mcp/extranet/facilities
Gestore di prezzi e disponibilità	/mcp/extranet/rates
Gestore delle prenotazioni quotidiane	/mcp/extranet/operations
Sviluppatore della distribuzione	/mcp/extranet/distribution + /mcp/analytics
Costruttore di pagine affiliate	/mcp/studio/curation + /mcp/studio/embeds
Gestore di pagine link-in-bio	/mcp/link-manager + /mcp/social
Prenotazione per conto di viaggiatori	/mcp/travel-agent
Riconciliazione finanziaria	/mcp/payment
Prenotazione di una camera con un agente AI	/mcp/booking-engine + wallet di pagamento compatibile — vedi Agentic Payments
Costruttore di un’esperienza di prenotazione	/mcp/booking-engine; opzionalmente /mcp/reference per ricerche aggiuntive

Booking Engine include il flusso di prenotazione principale. Fornisce scoperta account e personalizzazione, ricerca destinazioni, disponibilità hotel e dettagli tariffe camere, carrelli, checkout e gestione prenotazioni viaggiatori. Include anche strumenti di prenotazione e pagamento agentici quando abilitati per quell’ambiente.

Per una ricerca hotel basata su città, usa destination_lookup_search_suggestions per risolvere la destinazione, poi inventory_search_city per trovare hotel e tariffe disponibili. Entrambi gli strumenti sono in /mcp/booking-engine, quindi questo flusso non richiede una connessione Reference.

Aggiungi /mcp/reference quando ti servono ricerche di supporto come paesi, valute e tassi di cambio, lingue supportate, fusi orari, ricerche geografiche più ampie, classificazioni OTA o conoscenza pubblica delle proprietà. Sono aggiunte opzionali al flusso di prenotazione.

Inizia con uno. Aggiungi un altro quando ti accorgi che ti serve qualcosa che il primo non può fare — ogni connessione è indipendente, e aggiungerne una non influenza le altre.

Vuoi ancora tutto?

https://api.wink.travel/mcp e https://integrations.wink.travel/mcp rimangono disponibili e servono tutti gli strumenti sul loro host. Sono utili per esplorare cosa esiste, ma non li consigliamo per il lavoro quotidiano: la lista degli strumenti è abbastanza grande da sovraccaricare il tuo compito e peggiorare la selezione degli strumenti da parte dell’agente. Preferisci i toolset sopra indicati.

---

Come funziona l’autenticazione

I server MCP di Wink usano il flusso OAuth2 Authorization Code + PKCE e supportano la Dynamic Client Registration (RFC 7591). Ecco cosa succede quando ti connetti per la prima volta:

1. Il tuo client AI scopre il server di autorizzazione dai metadati /.well-known/oauth-protected-resource dell’endpoint MCP.
2. Il client si registra automaticamente tramite Dynamic Client Registration — nessuna configurazione manuale dell’applicazione richiesta.
3. Il client apre una scheda del browser su https://iam.wink.travel. Effettui l’accesso con il tuo account Wink e approvi i permessi richiesti nella schermata di consenso.
4. Wink emette un token di accesso associato al tuo account e collegato alla tua identità.
5. Il client AI allega il token a ogni richiesta MCP. Tutti i risultati degli strumenti sono automaticamente limitati all’entità gestore del tuo account.
6. I token scadono dopo 3 ore. Il client AI aggiorna silenziosamente il token in background senza richiedere nuovamente l’accesso.

Ogni chiamata a uno strumento avviene sotto la tua identità — le stesse regole ACL che proteggono il portale web si applicano all’agente AI.

---

Connetti il tuo client AI

Claude Code

1. Assicurati che Claude Code sia aggiornato:

   npm install -g @anthropic-ai/claude-code

2. Scegli un toolset dalla directory sopra e aggiungilo. Per esempio, prezzi e disponibilità:

   claude mcp add wink-rates https://api.wink.travel/mcp/extranet/rates --transport http

3. Claude Code contatta il server, scopre il server di autorizzazione e apre il browser predefinito.

4. Accedi a Wink e approva la richiesta di permessi nella schermata di consenso.

5. Claude Code conferma la connessione. Digita /mcp per verificare che il server appaia e che gli strumenti siano caricati.

Aggiungi quanti toolset servono al tuo lavoro — ognuno è una voce server separata con un proprio nome:

claude mcp add wink-operations https://api.wink.travel/mcp/extranet/operations --transport http
claude mcp add wink-analytics  https://api.wink.travel/mcp/analytics           --transport http

Effettui l’accesso una sola volta. Dopo la prima approvazione nel browser, Claude Code riutilizza la sessione Wink per ulteriori endpoint Wink.

Condividi con il tuo team

Aggiungi --scope project a claude mcp add e Claude Code scrive l’URL del server in .mcp.json nella radice del repository. Committa quel file — ogni membro del team avrà gli stessi toolset, e ognuno completerà il proprio login nel browser la prima volta che si connette.

Claude Desktop

1. Modifica il file di configurazione di Claude Desktop:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Aggiungi le voci dei server MCP:

   claude_desktop_config.json

   {
     "mcpServers": {
       "wink-extranet-rates": {
         "type": "http",
         "url": "https://api.wink.travel/mcp/extranet/rates"
       },
       "wink-extranet-operations": {
         "type": "http",
         "url": "https://api.wink.travel/mcp/extranet/operations"
       }
     }
   }

3. Chiudi completamente e riavvia Claude Desktop (usa Quit dal menu — chiudere la finestra non basta).

4. Claude Desktop apre una scheda del browser per ogni nuovo server. Accedi a Wink e approva i permessi.

5. L’icona della spina nella barra inferiore mostra entrambi i server come connessi.

OpenAI Codex

1. Assicurati che Codex CLI sia installato:

   npm install -g @openai/codex

2. Apri (o crea) il file di configurazione Codex:

   • macOS / Linux: ~/.codex/config.json
   • Windows: %USERPROFILE%\.codex\config.json

3. Aggiungi le voci dei server MCP di Wink:

   ~/.codex/config.json

   {
     "mcpServers": {
       "wink-extranet-rates": {
         "type": "http",
         "url": "https://api.wink.travel/mcp/extranet/rates"
       },
       "wink-extranet-operations": {
         "type": "http",
         "url": "https://api.wink.travel/mcp/extranet/operations"
       }
     }
   }

4. Avvia Codex. Al primo utilizzo, Codex apre una scheda del browser su https://iam.wink.travel.

5. Accedi a Wink e approva i permessi richiesti.

6. Codex conferma la connessione. Esegui codex e chiedi di elencare gli strumenti disponibili per verificare che i server Wink siano attivi.

Nota

Il supporto MCP di Codex CLI richiede la versione 1.0 o successiva. Esegui codex --version per controllare, e npm install -g @openai/codex per aggiornare.

ChatGPT

Il supporto ai server MCP è disponibile nell’app desktop ChatGPT per abbonati Plus, Pro, Team ed Enterprise.

1. Scarica e installa l’app desktop ChatGPT se non l’hai già fatto.

2. Apri l’app e clicca sull’icona del profilo in alto a destra, poi scegli Impostazioni.

3. Vai su Connettori (o Server MCP a seconda della versione dell’app) e clicca su Aggiungi.

4. Inserisci l’URL di un toolset dalla directory sopra, per esempio:

   https://api.wink.travel/mcp/extranet/rates

   Poi clicca su Connetti.

5. ChatGPT apre una scheda del browser su https://iam.wink.travel. Accedi a Wink e approva i permessi.

6. Ripeti i passaggi 4–5 per ogni altro toolset necessario, per esempio:

   https://api.wink.travel/mcp/extranet/operations

7. Ogni toolset appare nella lista dei Connettori. Inizia una nuova chat — gli strumenti Wink sono disponibili automaticamente.

Limitazione app web

I server MCP sono configurabili solo nell’app desktop. L’interfaccia web di ChatGPT su chatgpt.com non supporta server MCP personalizzati.

Cursor

1. Apri (o crea) il file di configurazione MCP di Cursor:

   • macOS / Linux: ~/.cursor/mcp.json
   • Windows: %USERPROFILE%\.cursor\mcp.json

2. Aggiungi le voci dei server MCP di Wink:

   ~/.cursor/mcp.json

   {
     "mcpServers": {
       "wink-extranet-rates": {
         "type": "http",
         "url": "https://api.wink.travel/mcp/extranet/rates"
       },
       "wink-extranet-operations": {
         "type": "http",
         "url": "https://api.wink.travel/mcp/extranet/operations"
       }
     }
   }

3. Apri Cursor. Vai su Impostazioni → Impostazioni Cursor → MCP e verifica che entrambi i server appaiano con indicatore di stato verde. Se sono rossi, clicca su Aggiorna.

4. Cursor apre una scheda del browser su https://iam.wink.travel. Accedi a Wink e approva i permessi.

5. Apri una chat (Ctrl+L / Cmd+L) e chiedi a Cursor di elencare gli strumenti Wink disponibili per confermare la connessione.

Configurazione a livello di progetto

Puoi anche posizionare un file mcp.json nella radice del tuo progetto invece che in ~/.cursor/. La configurazione a livello di progetto ha priorità e rende i server disponibili a ogni membro del team che apre il progetto in Cursor.

Windsurf

1. Apri (o crea) il file di configurazione MCP di Windsurf:

   • macOS / Linux: ~/.codeium/windsurf/mcp_config.json
   • Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json

2. Aggiungi le voci dei server MCP di Wink:

   ~/.codeium/windsurf/mcp_config.json

   {
     "mcpServers": {
       "wink-extranet-rates": {
         "type": "http",
         "url": "https://api.wink.travel/mcp/extranet/rates"
       },
       "wink-extranet-operations": {
         "type": "http",
         "url": "https://api.wink.travel/mcp/extranet/operations"
       }
     }
   }

3. Riavvia completamente Windsurf (File → Quit, poi riapri).

4. Vai su Impostazioni → Server MCP e verifica che entrambi i server risultino connessi. Windsurf apre una scheda del browser su https://iam.wink.travel al primo utilizzo.

5. Accedi a Wink e approva i permessi. I server diventano verdi nel pannello impostazioni una volta autenticati.

Nota

Il supporto MCP di Windsurf richiede la versione 1.4 o successiva. Controlla tramite Aiuto → Informazioni su Windsurf e aggiorna dal sito Windsurf se necessario.

Cline (VS Code)

Cline è un’estensione VS Code con un gestore MCP integrato. Non serve modificare manualmente JSON.

1. Installa Cline dal Marketplace di VS Code:

   • Apri VS Code e premi Ctrl+Shift+X / Cmd+Shift+X
   • Cerca Cline e clicca su Installa

2. Clicca sull’icona Cline nella barra attività (sidebar sinistra) per aprire il pannello Cline.

3. Clicca sull’icona Server MCP (icona spina) nella toolbar di Cline, poi scegli Modifica impostazioni MCP.

4. VS Code apre cline_mcp_settings.json. Aggiungi le voci di Wink:

   cline_mcp_settings.json

   {
     "mcpServers": {
       "wink-extranet-rates": {
         "type": "http",
         "url": "https://api.wink.travel/mcp/extranet/rates"
       },
       "wink-extranet-operations": {
         "type": "http",
         "url": "https://api.wink.travel/mcp/extranet/operations"
       }
     }
   }

5. Salva il file. Cline si ricarica automaticamente e apre una scheda del browser su https://iam.wink.travel.

6. Accedi a Wink e approva i permessi. Entrambi i server appaiono attivi nel pannello Server MCP.

Alternativa: aggiungi tramite URL

Nel pannello Server MCP, clicca su Aggiungi Server e incolla direttamente un URL di toolset come https://api.wink.travel/mcp/extranet/rates. Cline popola automaticamente la configurazione e gestisce l’autenticazione senza modificare manualmente il JSON.

---

Scopes

Quando approvi la schermata di consenso vedrai un dettaglio di cosa l’agente sta richiedendo. I client MCP usano lo stesso vocabolario di permessi della piattaforma — vedi la riferimento completo degli scope nella pagina Autenticazione.

Due cose sono specifiche per MCP:

• Gli scope mcp.read, mcp.write e mcp.remove sono richiesti in aggiunta per aprire il trasporto MCP. Un client che possiede uno scope mcp.* è ammesso a qualsiasi endpoint MCP Wink, ma ogni strumento invocato applica comunque lo scope della sezione dell’endpoint che incapsula (es. booking.read).
• Il client AI richiede solo gli scope di cui ha bisogno. Puoi negare permessi individuali nella schermata di consenso — gli strumenti che richiedono uno scope negato restituiranno un errore se invocati.

I toolset non cambiano nulla di questo. L’endpoint a cui ti connetti decide quali strumenti sono elencati, non cosa sono autorizzati a fare. Connettersi a /mcp/payment non concede permessi finanziari che non avevi già, e connettersi a /mcp/reference non impedisce a uno strumento di applicare il proprio scope. L’autorizzazione è decisa per ogni chiamata strumento, dal tuo token e dai permessi del tuo account.

---

Risoluzione problemi

La scheda del browser non si apre

Il tuo client AI potrebbe non supportare ancora il flusso PKCE interattivo. Verifica di usare una versione recente:

• Claude Code: npm install -g @anthropic-ai/claude-code
• Codex CLI: npm install -g @openai/codex
• Claude Desktop / ChatGPT desktop: aggiorna tramite l’updater integrato nell’app

401 Unauthorized dopo l’accesso

Il token memorizzato potrebbe essere scaduto. Rimuovi e aggiungi di nuovo il server per forzare un nuovo login:

# Claude Code
claude mcp remove wink-rates
claude mcp add wink-rates https://api.wink.travel/mcp/extranet/rates --transport http

Per Claude Desktop e ChatGPT, rimuovi la voce server dalle impostazioni, riavvia l’app e aggiungila di nuovo.

403 Forbidden chiamando uno strumento specifico

Lo strumento richiede uno scope che non hai approvato nella schermata di consenso, o un permesso che il tuo account non possiede. Riconnetti il server — la schermata di consenso apparirà di nuovo e potrai approvare il permesso mancante. Se continua a fallire, lo strumento richiede un permesso account che non hai; connettersi a un toolset diverso non aiuta, perché i toolset non concedono permessi.

Lo strumento che mi serve non è nella lista

Probabilmente sei connesso a un toolset che non copre quel lavoro. Controlla la directory degli endpoint e aggiungi il toolset che lo contiene — le connessioni sono indipendenti, quindi aggiungerne uno non cambia gli altri. Se non sei sicuro, connettiti temporaneamente a https://api.wink.travel/mcp, trova lo strumento, poi verifica a quale toolset appartiene.

404 Not Found su un endpoint toolset

Controlla attentamente il percorso — i toolset nidificati hanno due segmenti (/mcp/extranet/rates, non /mcp/extranet-rates), quelli piatti ne hanno uno (/mcp/link-manager). Nota che una richiesta non autenticata a qualsiasi percorso sotto /mcp restituisce 401, non 404, quindi un 401 da solo non indica se l’endpoint esiste.

Mi sono connesso a api.wink.travel/mcp/channel-manager e non ho ottenuto nulla

Quell’endpoint non esiste. L’integrazione channel manager è servita solo da https://integrations.wink.travel/mcp/channel-manager. Se devi anche leggere o scrivere le tariffe di una proprietà manualmente, è un lavoro separato su un endpoint separato — vedi /mcp/extranet/rates.

Il server appare ma le chiamate agli strumenti restituiscono “account non trovato”

Sei autenticato con un account Wink che non ha un’entità gestore. Vai su Wink Portal e assicurati che il tuo account sia configurato prima di usare il server MCP.

Il token scade durante la sessione

I token sono validi per 3 ore. Claude Code e Claude Desktop aggiornano i token silenziosamente senza interrompere la sessione. Se vedi errori di autenticazione dopo un lungo periodo di inattività, invia un nuovo messaggio — il client si ri-autenticherà automaticamente.

Codex CLI mostra “MCP server unreachable”

Controlla che il tuo ~/.codex/config.json sia JSON valido (senza virgole finali) e che "type": "http" sia impostato. Codex richiede il trasporto HTTP per server remoti; il trasporto stdio è solo per binari locali.

Il menu “Connettori” di ChatGPT manca

Il supporto MCP richiede la versione 1.2024.352 o successiva dell’app desktop ChatGPT e un abbonamento Plus, Pro, Team o Enterprise attivo. Aggiorna l’app e verifica il piano in Impostazioni → Account.

Il server Cursor mostra rosso / “Connessione fallita”

Verifica che il tuo ~/.cursor/mcp.json sia JSON valido e contenga "type": "http". Poi vai su Impostazioni → Impostazioni Cursor → MCP e clicca su Aggiorna. Se l’errore persiste, riavvia completamente Cursor — le modifiche alla configurazione non sempre vengono rilevate senza un riavvio.

I server MCP di Windsurf non compaiono nelle impostazioni

Windsurf richiede un riavvio completo (non solo ricaricare la finestra) per rilevare le modifiche a mcp_config.json. Usa File → Quit e riapri. Se i server non appaiono ancora, conferma di usare Windsurf 1.4+ tramite Aiuto → Informazioni su Windsurf.

L’opzione “Aggiungi Server” in Cline non è visibile

Il gestore server MCP richiede Cline 2.0 o successivo. Apri il pannello Estensioni di VS Code, trova Cline e clicca su Aggiorna se disponibile. Dopo l’aggiornamento, ricarica VS Code (Ctrl+Shift+P → “Developer: Reload Window”).

---

Apri Wink Portal Wink su GitHub