Servidores MCP

As ferramentas MCP da Wink são publicadas como conjuntos de ferramentas — endpoints focados, cada um cobrindo uma tarefa. Você liga o seu cliente de IA ao um ou dois que correspondem ao seu trabalho, não a todos eles.

Cada endpoint usa login interativo OAuth2 (fluxo de código de autorização PKCE): o seu agente de IA abre uma aba do navegador, você inicia sessão com a sua conta Wink, e está feito. Sem segredos de cliente para gerir.

Um integrador de channel manager liga-se a um endpoint

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

Um hoteleiro a gerir as suas próprias tarifas liga-se a outro

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

---

Por que as ferramentas estão divididas por endpoints

A Wink expõe cerca de 500 ferramentas. Entregar todas elas a um agente de uma só vez é tecnicamente possível — e uma má ideia.

As definições das ferramentas consomem contexto. Cada ferramenta que um servidor MCP anuncia é carregada na janela de contexto do modelo antes de fazer qualquer trabalho, juntamente com a sua descrição e esquema completo de parâmetros. Quinhentas dessas consomem uma grande parte do orçamento que a sua tarefa real necessita, em cada pedido.

A qualidade da escolha diminui à medida que a lista cresce. Um agente que escolhe entre 500 ferramentas com nomes semelhantes faz escolhas piores do que um que escolhe entre 40. Se integrar um channel manager, cerca de vinte ferramentas são relevantes para si; as outras 480 são ruído que dificulta encontrar a ferramenta certa.

O trabalho é genuinamente separável. Alguém a sincronizar disponibilidade de um PMS e alguém a criar páginas de afiliados partilham quase nenhuma ferramenta. Dividir por tarefa significa que cada ligação transporta o vocabulário de uma tarefa.

Conjuntos de ferramentas não são permissões

Escolher um conjunto de ferramentas restrito não limita o que a sua conta pode fazer, e escolher um conjunto amplo não concede nada extra. Cada ferramenta aplica as mesmas permissões de conta que o portal web, sob a sua identidade autenticada. Se a sua conta não pode cancelar uma reserva no Wink Portal, o agente também não pode — independentemente do endpoint a que está ligado.

Escolha conjuntos de ferramentas para foco, não para segurança.

---

Diretório de endpoints

Dois hosts servem conjuntos de ferramentas. A contagem de ferramentas é aproximada e cresce com o tempo.

https://api.wink.travel — a plataforma

Endpoint	Ferramentas	O que cobre
/mcp/extranet/facilities	~64	Inventário reservável e no local: quartos e tipos de quartos, spas, restaurantes, salas de reuniões, atividades, atrações, locais, outros itens vendáveis
/mcp/extranet/property	~62	Registo da propriedade e seus termos comerciais: perfil e conteúdo, extras, políticas de cancelamento, benefícios, anúncios
/mcp/settings	~60	Administração da conta: perfil e branding da entidade gestora, gestores e suas permissões, personalização, webhooks, preferências de notificação
/mcp/studio/embeds	~48	Publicação de inventário curado: widgets, grelhas e grelhas classificadas, cartões, mapas, links profundos para inventário e páginas de fornecedores
/mcp/extranet/rates	~44	Preços e disponibilidade: períodos e lotes de tarifas de inventário, planos tarifários, tarifas principais, tarifas especiais e promocionais
/mcp/extranet/operations	~39	Gestão de uma propriedade ativa: reservas e seu ciclo de vida, avaliações e respostas de hóspedes, feeds de calendário, tarefas agendadas
/mcp/extranet/distribution	~37	Onde o inventário é vendido: canais de venda e modificadores de tarifa, pedidos de relacionamento com afiliados e fornecedores, registo, captura de leads
/mcp/studio/curation	~35	Construção de coleções comercializáveis: listas estáticas e dinâmicas, listas classificadas, pesquisas guardadas, agregados de propriedades
/mcp/link-manager	~28	Coleções de links sindicados, seu design, categorias e etiquetas, além de URLs encurtados
/mcp/reference	~24	Dados de consulta apenas leitura: países, moedas e taxas de câmbio, idiomas, fusos horários, consultas geográficas, geolocalização por IP
/mcp/analytics	~18	Análise de reservas e receitas: visões gerais, gráficos de linha, rankings, desempenho de afiliados, métricas de partilha
/mcp/payment	~18	Operações financeiras: razão, levantamentos e estimativas de taxas, agregados de fundos de reserva
/mcp/booking-engine	~17	Caminho de compra para o viajante: pesquisa e consulta, carrinho de compras e checkout, listas de desejos, personalização de campanhas
/mcp/social	~17	Contas sociais ligadas, publicação e agendamento de posts, leitura de insights de posts
/mcp/travel-agent	~8	Reservas facilitadas por agentes em nome dos viajantes, e relatórios de agentes

https://integrations.wink.travel — integrações de channel manager

Um endpoint, porque este host existe para uma tarefa.

Endpoint	Ferramentas	O que cobre
/mcp/channel-manager	~9	Ligação e verificação de uma integração de channel manager, PMS ou CRS

Integrar um channel manager vs. gerir as suas próprias tarifas

São tarefas diferentes para pessoas diferentes, e não partilham um endpoint.

Um fornecedor de channel manager, PMS ou CRS integra-se uma vez através de integrations.wink.travel/mcp/channel-manager, e a partir daí troca propriedades, tarifas, disponibilidade e reservas por essa integração. Esse único endpoint é toda a superfície.

Um hoteleiro a alterar as suas próprias tarifas manualmente usa os conjuntos de ferramentas do extranet em api.wink.travel — /mcp/extranet/rates e afins. Estes não fazem parte de uma integração de channel manager e um integrador não tem razão para se ligar a eles.

A administração da conta também está em api.wink.travel, em /mcp/settings. Não existe /mcp/settings no host de integrações.

Cada endpoint também inclui uma ferramenta ping, para que possa confirmar que a ligação está ativa antes de pedir trabalho real.

---

Que conjuntos de ferramentas preciso?

Se você é…	Ligue-se a
A integrar um channel manager, PMS ou CRS	integrations.wink.travel/mcp/channel-manager — apenas este
A gerir o conteúdo de uma propriedade	/mcp/extranet/property + /mcp/extranet/facilities
A gerir quartos e tipos de quartos	/mcp/extranet/facilities
A gerir preços e disponibilidade	/mcp/extranet/rates
A gerir reservas diárias	/mcp/extranet/operations
A expandir a distribuição	/mcp/extranet/distribution + /mcp/analytics
A construir páginas de afiliados	/mcp/studio/curation + /mcp/studio/embeds
A gerir páginas link-in-bio	/mcp/link-manager + /mcp/social
A reservar em nome dos viajantes	/mcp/travel-agent
A reconciliar dinheiro	/mcp/payment
A construir uma experiência de reserva	/mcp/booking-engine + /mcp/reference

Comece com um. Adicione outro quando se vir a pedir algo que ele não pode fazer — cada ligação é independente, e adicionar um nunca afeta os outros.

Quer mesmo tudo?

https://api.wink.travel/mcp e https://integrations.wink.travel/mcp permanecem disponíveis e servem todas as ferramentas no seu host. São úteis para explorar o que existe, mas não os recomendamos para trabalho diário: a lista de ferramentas é grande o suficiente para sobrecarregar a sua tarefa e degradar a seleção de ferramentas do agente. Prefira os conjuntos de ferramentas acima.

---

Como funciona a autenticação

Os servidores MCP da Wink usam o fluxo OAuth2 Authorization Code + PKCE e suportam Dynamic Client Registration (RFC 7591). Isto é o que acontece quando se liga pela primeira vez:

1. O seu cliente de IA descobre o servidor de autorização a partir dos metadados /.well-known/oauth-protected-resource do endpoint MCP.
2. O cliente regista-se automaticamente via Dynamic Client Registration — não é necessário configurar a aplicação manualmente.
3. O cliente abre uma aba do navegador para https://iam.wink.travel. Você inicia sessão com a sua conta Wink e aprova as permissões solicitadas no ecrã de consentimento.
4. A Wink emite um token de acesso com escopo para a sua conta e ligado à sua identidade.
5. O cliente de IA anexa o token a cada pedido MCP. Todos os resultados das ferramentas são automaticamente limitados à sua entidade gestora.
6. Os tokens expiram após 3 horas. O seu cliente de IA atualiza silenciosamente em segundo plano sem pedir novamente.

Cada chamada de ferramenta é executada sob a sua identidade — as mesmas regras ACL que protegem o portal web aplicam-se ao agente de IA.

---

Ligue o seu cliente de IA

Claude Code

1. Certifique-se de que o Claude Code está atualizado:

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

2. Escolha um conjunto de ferramentas do diretório acima e adicione-o. Por exemplo, preços e disponibilidade:

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

3. O Claude Code contacta o servidor, descobre o servidor de autorização e abre o seu navegador padrão.

4. Inicie sessão na Wink e aprove as permissões no ecrã de consentimento.

5. O Claude Code confirma a ligação. Digite /mcp para verificar se o servidor aparece e as suas ferramentas foram carregadas.

Adicione tantos conjuntos de ferramentas quanto o seu trabalho necessitar — cada um é uma entrada de servidor separada com o seu próprio 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

Você só inicia sessão uma vez. Após a primeira aprovação no navegador, o Claude Code reutiliza a sua sessão Wink para endpoints Wink adicionais.

Partilhe com a sua equipa

Adicione --scope project ao claude mcp add e o Claude Code grava a URL do servidor em .mcp.json na raiz do repositório. Faça commit desse ficheiro — cada membro da equipa obtém os mesmos conjuntos de ferramentas, e cada um completa o seu próprio login no navegador na primeira vez que se liga.

Claude Desktop

1. Edite o ficheiro de configuração do 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. Adicione as entradas dos servidores 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. Feche completamente e reinicie o Claude Desktop (use Quit no menu — fechar a janela não é suficiente).

4. O Claude Desktop abre uma aba do navegador para cada novo servidor. Inicie sessão na Wink e aprove as permissões.

5. O ícone de ficha na barra inferior mostra ambos os servidores como ligados.

OpenAI Codex

1. Certifique-se de que o Codex CLI está instalado:

   npm install -g @openai/codex

2. Abra (ou crie) o ficheiro de configuração do Codex:

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

3. Adicione as entradas dos servidores MCP da 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. Inicie o Codex. Na primeira utilização, o Codex abre uma aba do navegador para https://iam.wink.travel.

5. Inicie sessão na Wink e aprove as permissões solicitadas.

6. O Codex confirma a ligação. Execute codex e peça para listar as ferramentas disponíveis para verificar se os servidores Wink estão ativos.

Nota

O suporte MCP do Codex CLI requer a versão 1.0 ou superior. Execute codex --version para verificar, e npm install -g @openai/codex para atualizar.

ChatGPT

O suporte a servidores MCP está disponível na app desktop ChatGPT para assinantes Plus, Pro, Team e Enterprise.

1. Descarregue e instale a app desktop ChatGPT se ainda não o fez.

2. Abra a app e clique no ícone do seu perfil no canto superior direito, depois escolha Definições.

3. Vá a Conectores (ou Servidores MCP dependendo da versão da app) e clique em Adicionar.

4. Introduza a URL de um conjunto de ferramentas do diretório acima, por exemplo:

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

   Depois clique em Ligar.

5. O ChatGPT abre uma aba do navegador para https://iam.wink.travel. Inicie sessão na Wink e aprove as permissões.

6. Repita os passos 4–5 para qualquer outro conjunto de ferramentas que o seu trabalho necessite, por exemplo:

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

7. Cada conjunto de ferramentas aparece na sua lista de Conectores. Inicie uma nova conversa — as ferramentas Wink estão disponíveis automaticamente.

Limitação da app web

Os servidores MCP só são configuráveis na app desktop. A interface web do ChatGPT em chatgpt.com não suporta servidores MCP personalizados.

Cursor

1. Abra (ou crie) o ficheiro de configuração MCP do Cursor:

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

2. Adicione as entradas dos servidores MCP da 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. Abra o Cursor. Vá a Definições → Definições do Cursor → MCP e confirme que ambos os servidores aparecem com um indicador de estado verde. Se aparecerem a vermelho, clique em Atualizar.

4. O Cursor abre uma aba do navegador para https://iam.wink.travel. Inicie sessão na Wink e aprove as permissões.

5. Abra um chat (Ctrl+L / Cmd+L) e peça ao Cursor para listar as ferramentas Wink disponíveis para confirmar a ligação.

Configuração com escopo de projeto

Também pode colocar um ficheiro mcp.json na raiz do seu projeto em vez de em ~/.cursor/. A configuração a nível de projeto tem prioridade e torna os servidores disponíveis para todos os membros da equipa que abrirem o projeto no Cursor.

Windsurf

1. Abra (ou crie) o ficheiro de configuração MCP do Windsurf:

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

2. Adicione as entradas dos servidores MCP da 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. Reinicie completamente o Windsurf (Ficheiro → Sair, depois reabra).

4. Vá a Definições → Servidores MCP e verifique se ambos os servidores aparecem como ligados. O Windsurf abre uma aba do navegador para https://iam.wink.travel na primeira utilização.

5. Inicie sessão na Wink e aprove as permissões. Os servidores ficam verdes no painel de definições assim que autenticados.

Nota

O suporte MCP do Windsurf requer a versão 1.4 ou superior. Verifique em Ajuda → Sobre o Windsurf e atualize a partir do site do Windsurf se necessário.

Cline (VS Code)

O Cline é uma extensão para VS Code com um gestor de servidores MCP incorporado. Não é necessário editar JSON manualmente.

1. Instale o Cline a partir do Marketplace do VS Code:

   • Abra o VS Code e pressione Ctrl+Shift+X / Cmd+Shift+X
   • Procure por Cline e clique em Instalar

2. Clique no ícone do Cline na Barra de Atividades (barra lateral esquerda) para abrir o painel do Cline.

3. Clique no ícone Servidores MCP (ícone de ficha) na barra de ferramentas do Cline, depois escolha Editar Definições MCP.

4. O VS Code abre o ficheiro cline_mcp_settings.json. Adicione as entradas da 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. Guarde o ficheiro. O Cline recarrega automaticamente e abre uma aba do navegador para https://iam.wink.travel.

6. Inicie sessão na Wink e aprove as permissões. Ambos os servidores aparecem como ativos no painel Servidores MCP.

Alternativa: adicionar via URL

No painel Servidores MCP, clique em Adicionar Servidor e cole diretamente uma URL de conjunto de ferramentas como https://api.wink.travel/mcp/extranet/rates. O Cline preenche automaticamente a configuração e trata da autenticação sem necessidade de editar JSON manualmente.

---

Escopos

Quando aprova o ecrã de consentimento verá uma discriminação do que o agente está a pedir. Os clientes MCP usam o mesmo vocabulário de permissões que o resto da plataforma — veja a referência completa de escopos na página de Autenticação.

Duas coisas são específicas do MCP:

• Os escopos mcp.read, mcp.write e mcp.remove são adicionalmente necessários para abrir o transporte MCP. Um cliente que detém um escopo mcp.* é admitido em qualquer endpoint MCP da Wink, mas cada ferramenta que invoca ainda aplica o escopo da secção do endpoint que envolve (ex.: booking.read).
• O cliente de IA pede apenas os escopos que precisa. Pode negar permissões individuais no ecrã de consentimento — ferramentas que requerem um escopo negado retornam erro quando invocadas.

Os conjuntos de ferramentas não alteram nada disto. O endpoint a que se liga decide quais ferramentas são listadas, não o que elas estão autorizadas a fazer. Ligar a /mcp/payment não concede nenhuma permissão financeira que já não tivesse, e ligar a /mcp/reference não impede uma ferramenta aí de aplicar o seu próprio escopo. A autorização é decidida por chamada de ferramenta, a partir do seu token e das permissões da sua conta.

---

Resolução de problemas

A aba do navegador não abre

O seu cliente de IA pode ainda não suportar o fluxo interativo PKCE. Verifique se está a usar uma versão recente:

• Claude Code: npm install -g @anthropic-ai/claude-code
• Codex CLI: npm install -g @openai/codex
• Claude Desktop / ChatGPT desktop: atualize pelo atualizador incorporado da app

401 Unauthorized após iniciar sessão

O seu token em cache pode estar desatualizado. Remova e adicione novamente o servidor para forçar um novo login:

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

Para Claude Desktop e ChatGPT, remova a entrada do servidor nas definições, reinicie a app e adicione novamente.

403 Forbidden ao chamar uma ferramenta específica

A ferramenta requer um escopo que não aprovou no ecrã de consentimento, ou uma permissão que a sua conta não possui. Reconecte o servidor — o ecrã de consentimento aparecerá novamente e poderá aprovar a permissão em falta. Se continuar a falhar, a ferramenta precisa de uma permissão de conta que não tem; ligar a um conjunto de ferramentas diferente não ajuda, porque os conjuntos de ferramentas não concedem permissões.

A ferramenta que preciso não está na lista

Provavelmente está ligado a um conjunto de ferramentas que não cobre essa tarefa. Verifique o diretório de endpoints e adicione o conjunto de ferramentas que cobre — as ligações são independentes, por isso adicionar um não altera os outros. Se não souber qual tem, ligue temporariamente a https://api.wink.travel/mcp, encontre a ferramenta, depois veja qual conjunto de ferramentas a lista.

404 Not Found num endpoint de conjunto de ferramentas

Verifique o caminho cuidadosamente — os conjuntos aninhados têm dois segmentos (/mcp/extranet/rates, não /mcp/extranet-rates), e os planos têm um (/mcp/link-manager). Note que um pedido não autenticado a qualquer caminho sob /mcp retorna 401, não 404, por isso um 401 sozinho não indica se o endpoint existe.

Liguei a api.wink.travel/mcp/channel-manager e não obtive nada

Esse endpoint não existe. A integração de channel manager é servida apenas em https://integrations.wink.travel/mcp/channel-manager. Se também precisa de ler ou escrever as tarifas próprias de uma propriedade manualmente, essa é uma tarefa separada num endpoint separado — veja /mcp/extranet/rates.

O servidor aparece mas as chamadas às ferramentas retornam “conta não encontrada”

Está autenticado numa conta Wink que não tem uma entidade gestora. Vá a Wink Portal e assegure-se de que a sua conta está configurada antes de usar o servidor MCP.

O token expira durante a sessão

Os tokens são válidos por 3 horas. O Claude Code e o Claude Desktop atualizam tokens silenciosamente sem interromper a sua sessão. Se vir erros de autenticação após um longo período de inatividade, escreva uma nova mensagem — o cliente irá reautenticar automaticamente.

O Codex CLI mostra “MCP server unreachable”

Verifique se o seu ~/.codex/config.json é JSON válido (sem vírgulas finais) e que "type": "http" está definido. O Codex requer transporte HTTP para servidores remotos; transporte stdio é apenas para binários locais.

O menu “Conectores” do ChatGPT está ausente

O suporte MCP requer a versão da app desktop ChatGPT 1.2024.352 ou superior e uma subscrição ativa Plus, Pro, Team ou Enterprise. Atualize a app e verifique o seu plano em Definições → Conta.

O servidor Cursor mostra vermelho / “Falha na ligação”

Verifique se o seu ~/.cursor/mcp.json é JSON válido e contém "type": "http". Depois vá a Definições → Definições do Cursor → MCP e clique em Atualizar. Se o erro persistir, reinicie completamente o Cursor — as alterações na configuração nem sempre são aplicadas sem reinício.

Os servidores MCP do Windsurf não aparecem nas definições

O Windsurf requer um reinício completo (não apenas recarregar a janela) para aplicar alterações ao mcp_config.json. Use Ficheiro → Sair e reinicie. Se os servidores ainda não aparecerem, confirme que está na versão Windsurf 1.4+ em Ajuda → Sobre o Windsurf.

A opção “Adicionar Servidor” do Cline não está visível

O gestor de servidores MCP requer o Cline 2.0 ou superior. Abra o painel de Extensões do VS Code, encontre o Cline e clique em Atualizar se houver uma atualização disponível. Após atualizar, recarregue o VS Code (Ctrl+Shift+P → “Developer: Reload Window”).

---

Abrir Wink Portal Wink no GitHub