Server MCP
Gli strumenti MCP di Wink sono pubblicati come toolset — endpoint focalizzati, ognuno dedicato a un lavoro specifico. Colleghi 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.
claude mcp add wink-channel-manager https://integrations.wink.travel/mcp/channel-manager --transport httpclaude mcp add wink-rates https://api.wink.travel/mcp/extranet/rates --transport httpPerché gli strumenti sono suddivisi in endpoint
Sezione intitolata “Perché gli strumenti sono suddivisi in endpoint”Wink espone circa 500 strumenti. Fornire tutti contemporaneamente a un agente è 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. Suddividere per lavoro significa che ogni connessione porta il vocabolario di un solo lavoro.
Directory degli endpoint
Sezione intitolata “Directory degli endpoint”Due host servono i toolset. Il numero di strumenti è approssimativo e cresce nel tempo.
https://api.wink.travel — la piattaforma
Sezione intitolata “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 | Scheda della proprietà 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 autorizzazioni, 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 delle tariffe, piani tariffari, tariffe master, tariffe speciali e promozionali |
/mcp/extranet/operations | ~39 | Gestione operativa di una struttura: prenotazioni e ciclo di vita, recensioni ospiti e risposte, feed calendario, attività programmate |
/mcp/extranet/distribution | ~37 | Dove si vende l’inventario: canali di vendita e modificatori di tariffa, richieste di relazione con affiliati e fornitori, registrazione, acquisizione lead |
/mcp/studio/curation | ~35 | Costruzione di collezioni commercializzabili: liste statiche e dinamiche, liste classificate, ricerche salvate, aggregati di proprietà |
/mcp/link-manager | ~28 | Collezioni di link sindacati, loro 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 affiliati, 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 viaggiatori: 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
Sezione intitolata “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 un’integrazione channel manager, PMS o CRS |
Ogni endpoint include anche uno strumento ping, così puoi confermare che la connessione è attiva prima di chiedere un lavoro reale.
Pagamenti agentici
Sezione intitolata “Pagamenti agentici”Per il flusso completo di prenotazione del viaggiatore, collega 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 la ricerca destinazioni, 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?
Sezione intitolata “Quali toolset mi servono?”| Se sei… | Collegati a |
|---|---|
| Un integratore di channel manager, PMS o CRS | integrations.wink.travel/mcp/channel-manager — solo questo |
| Gestisci il contenuto di una proprietà | /mcp/extranet/property + /mcp/extranet/facilities |
| Gestisci camere e tipologie | /mcp/extranet/facilities |
| Gestisci prezzi e disponibilità | /mcp/extranet/rates |
| Gestisci le prenotazioni quotidiane | /mcp/extranet/operations |
| Espandi la distribuzione | /mcp/extranet/distribution + /mcp/analytics |
| Costruisci pagine affiliate | /mcp/studio/curation + /mcp/studio/embeds |
| Gestisci pagine link-in-bio | /mcp/link-manager + /mcp/social |
| Prenoti per conto dei viaggiatori | /mcp/travel-agent |
| Riconcili i pagamenti | /mcp/payment |
| Prenoti una camera con un agente AI | /mcp/booking-engine + un wallet di pagamento compatibile — vedi Agentic Payments |
| Costruisci 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. Gli strumenti di prenotazione e pagamento agentici sono inclusi 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 quello non può fare — ogni connessione è indipendente, e aggiungerne una non influenza le altre.
Come funziona l’autenticazione
Sezione intitolata “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:
- Il tuo client AI scopre il server di autorizzazione dai metadati
/.well-known/oauth-protected-resourcedell’endpoint MCP. - Il client si registra automaticamente tramite Dynamic Client Registration — nessuna configurazione manuale dell’applicazione richiesta.
- 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. - Wink emette un token di accesso associato al tuo account e collegato alla tua identità.
- Il client AI allega il token a ogni richiesta MCP. Tutti i risultati degli strumenti sono automaticamente limitati alla tua entità gestore.
- I token scadono dopo 3 ore. Il client AI aggiorna silenziosamente 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.
Collega il tuo client AI
Sezione intitolata “Collega il tuo client AI”Aggiungi ogni toolset a Claude come connettore personalizzato. Non c’è file di configurazione da modificare né applicazione o segreto da creare.
-
In Claude, apri Customize › Connectors, clicca Add, poi Add custom connector.
-
Inserisci un Nome (per esempio Wink Link manager) e, come URL server MCP, un toolset dalla directory sopra, per esempio:
https://api.wink.travel/mcp/link-managerClicca Continue.
-
Claude rileva il login Wink. Mantieni Authentication: Sign in now e OAuth client: Register automatically, poi clicca Add.
-
Clicca Connect. Si apre una pagina di login Wink su
https://iam.wink.travel. Accedi a Wink e approva i permessi nella schermata di consenso. -
Gli strumenti del connettore sono ora disponibili nelle tue chat. Ripeti per ogni toolset necessario al tuo lavoro; ognuno è un connettore a sé.
-
Assicurati che Claude Code sia aggiornato:
Finestra del terminale npm install -g @anthropic-ai/claude-code -
Scegli un toolset dalla directory sopra e aggiungilo. Per esempio, prezzi e disponibilità:
Finestra del terminale claude mcp add wink-rates https://api.wink.travel/mcp/extranet/rates --transport http -
Claude Code contatta il server, scopre il server di autorizzazione e apre il browser predefinito.
-
Accedi a Wink e approva la richiesta di permessi nella schermata di consenso.
-
Claude Code conferma la connessione. Digita
/mcpper 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 httpclaude mcp add wink-analytics https://api.wink.travel/mcp/analytics --transport httpAccedi una sola volta. Dopo la prima approvazione nel browser, Claude Code riutilizza la sessione Wink per ulteriori endpoint Wink.
-
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
- macOS:
-
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"}}} -
Chiudi completamente e riavvia Claude Desktop (usa Quit dal menu — chiudere la finestra non basta).
-
Claude Desktop apre una scheda browser per ogni nuovo server. Accedi a Wink e approva i permessi.
-
L’icona della spina nella barra inferiore mostra entrambi i server come connessi.
-
Assicurati che Codex CLI sia installato:
Finestra del terminale npm install -g @openai/codex -
Apri (o crea) il file di configurazione Codex:
- macOS / Linux:
~/.codex/config.json - Windows:
%USERPROFILE%\.codex\config.json
- macOS / Linux:
-
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"}}} -
Avvia Codex. Al primo utilizzo, Codex apre una scheda browser su
https://iam.wink.travel. -
Accedi a Wink e approva i permessi richiesti.
-
Codex conferma la connessione. Esegui
codexe chiedi di elencare gli strumenti disponibili per verificare che i server Wink siano attivi.
Il supporto ai server MCP è disponibile nell’app desktop ChatGPT per abbonati Plus, Pro, Team ed Enterprise.
-
Scarica e installa l’app desktop ChatGPT se non l’hai già fatto.
-
Apri l’app e clicca sull’icona del profilo in alto a destra, poi scegli Settings.
-
Vai su Connectors (o MCP Servers a seconda della versione dell’app) e clicca Add.
-
Inserisci l’URL di un toolset dalla directory sopra, per esempio:
https://api.wink.travel/mcp/extranet/ratesPoi clicca Connect.
-
ChatGPT apre una scheda browser su
https://iam.wink.travel. Accedi a Wink e approva i permessi. -
Ripeti i passaggi 4–5 per ogni altro toolset necessario, per esempio:
https://api.wink.travel/mcp/extranet/operations -
Ogni toolset appare nella tua lista Connectors. Avvia una nuova chat — gli strumenti Wink sono disponibili automaticamente.
-
Apri (o crea) il file di configurazione MCP di Cursor:
- macOS / Linux:
~/.cursor/mcp.json - Windows:
%USERPROFILE%\.cursor\mcp.json
- macOS / Linux:
-
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"}}} -
Apri Cursor. Vai su Settings → Cursor Settings → MCP e verifica che entrambi i server appaiano con indicatore di stato verde. Se sono rossi, clicca Refresh.
-
Cursor apre una scheda browser su
https://iam.wink.travel. Accedi a Wink e approva i permessi. -
Apri una chat (
Ctrl+L/Cmd+L) e chiedi a Cursor di elencare gli strumenti Wink disponibili per confermare la connessione.
-
Apri (o crea) il file di configurazione MCP di Windsurf:
- macOS / Linux:
~/.codeium/windsurf/mcp_config.json - Windows:
%USERPROFILE%\.codeium\windsurf\mcp_config.json
- macOS / Linux:
-
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"}}} -
Riavvia completamente Windsurf (File → Quit, poi riapri).
-
Vai su Settings → MCP Servers e verifica che entrambi i server siano connessi. Windsurf apre una scheda browser su
https://iam.wink.travelal primo utilizzo. -
Accedi a Wink e approva i permessi. I server diventano verdi nel pannello impostazioni una volta autenticati.
Cline è un’estensione VS Code con un gestore MCP integrato. Non serve modificare manualmente JSON.
-
Installa Cline dal Marketplace di VS Code:
- Apri VS Code e premi
Ctrl+Shift+X/Cmd+Shift+X - Cerca Cline e clicca Install
- Apri VS Code e premi
-
Clicca sull’icona Cline nella Activity Bar (barra laterale sinistra) per aprire il pannello Cline.
-
Clicca sull’icona MCP Servers (icona spina) nella toolbar di Cline, poi scegli Edit MCP Settings.
-
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"}}} -
Salva il file. Cline si ricarica automaticamente e apre una scheda browser su
https://iam.wink.travel. -
Accedi a Wink e approva i permessi. Entrambi i server appaiono attivi nel pannello MCP Servers.
Quando approvi la schermata di consenso vedrai un dettaglio di cosa l’agente sta richiedendo. I client MCP usano lo stesso vocabolario di permessi del resto della piattaforma — vedi il riferimento completo agli scope nella pagina Autenticazione.
Tre cose sono specifiche per MCP:
- Gli scope
mcp.read,mcp.write,mcp.removesono richiesti in aggiunta per aprire il trasporto MCP. Un client che possiede uno scopemcp.*è ammesso a qualsiasi endpoint MCP Wink, ma ogni strumento che invoca applica comunque lo scope della sezione dell’endpoint che incapsula (es.booking.read). - MCP agisce sempre come utente autenticato. Il client AI riceve gli scope
mcp.*tramite il tuo login, mai da un’Applicazione che crei. I token machine-to-machine (client-credentials) non possono aprire il trasporto MCP; usa l’API REST per lavoro server-to-server. - Il client AI richiede solo gli scope necessari. Puoi negare singoli permessi nella schermata di consenso — gli strumenti che richiedono uno scope negato restituiranno un errore se invocati.
I toolset non cambiano nulla di tutto ciò. L’endpoint a cui ti connetti decide quali strumenti sono elencati, non cosa sono autorizzati a fare. Collegarsi a /mcp/payment non concede permessi finanziari che non avevi già, e collegarsi a /mcp/reference non impedisce a uno strumento di applicare il proprio scope. L’autorizzazione è decisa per ogni chiamata strumento, dal tuo token e dalle autorizzazioni del tuo account.
Risoluzione problemi
Sezione intitolata “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 il login
Il token memorizzato potrebbe essere scaduto. Rimuovi e riaggiungi il server per forzare un nuovo login:
# Claude Codeclaude mcp remove wink-ratesclaude mcp add wink-rates https://api.wink.travel/mcp/extranet/rates --transport httpPer Claude Desktop e ChatGPT, rimuovi il server dalle impostazioni, riavvia l’app e aggiungilo 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; collegarsi 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 nulla sugli altri. Se non sei sicuro quale lo abbia, connettiti temporaneamente a https://api.wink.travel/mcp, trova lo strumento, poi verifica quale toolset lo elenca.
404 Not Found su un endpoint toolset
Controlla attentamente il percorso — i toolset annidati 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 collegato 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 not found”
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 “Connectors” 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 Settings → Account.
Il server Cursor mostra rosso / “Failed to connect”
Verifica che il tuo ~/.cursor/mcp.json sia JSON valido e contenga "type": "http". Poi vai su Settings → Cursor Settings → MCP e clicca Refresh. Se l’errore persiste, riavvia completamente Cursor — le modifiche alla configurazione non sempre vengono rilevate senza 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, verifica di usare Windsurf 1.4+ tramite Help → About Windsurf.
L’opzione “Add 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 Update se disponibile. Dopo l’aggiornamento, ricarica VS Code (Ctrl+Shift+P → “Developer: Reload Window”).
Apri Wink Portal Wink su GitHub
