Servidores MCP

A Wink disponibiliza dois servidores MCP autenticados. Ambos usam login interativo OAuth2 (fluxo de código de autorização PKCE) — o seu agente de IA abre uma aba do navegador para que faça login com a sua conta Wink. Sem segredos de cliente para gerir.

Servidor	URL	O que faz
Inventory API	https://api.wink.travel/mcp	Inventário, reservas, tarifas, canais de venda, análises e todas as operações da plataforma
Integrations	https://integrations.wink.travel/mcp	Integrações de gestor de canais — sincronize propriedades, tarifas e disponibilidade com OTAs

---

Como funciona a autenticação

Os servidores MCP da Wink usam o fluxo OAuth2 Authorization Code + PKCE e suportam Dynamic Client Registration (RFC 7591). Eis o que acontece quando se conecta 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. Faz login com a sua conta Wink e aprova as permissões solicitadas no ecrã de consentimento.
4. A Wink emite um token de acesso associado à sua conta e 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-os silenciosamente em segundo plano sem pedir login novamente.

Cada chamada a uma 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. Adicione o servidor MCP Inventory da Wink:

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

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

4. Faça login na Wink e aprove as permissões solicitadas no ecrã de consentimento.

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

Para adicionar também o servidor Integrations:

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

Partilhe com a sua equipa

Adicione --scope project ao comando 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 completa o seu próprio login no navegador na primeira vez que se conecta.

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-inventory": {
         "type": "http",
         "url": "https://api.wink.travel/mcp"
       },
       "wink-integrations": {
         "type": "http",
         "url": "https://integrations.wink.travel/mcp"
       }
     }
   }

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. Faça login na Wink e aprove as permissões.

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

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-inventory": {
         "type": "http",
         "url": "https://api.wink.travel/mcp"
       },
       "wink-integrations": {
         "type": "http",
         "url": "https://integrations.wink.travel/mcp"
       }
     }
   }

4. Inicie o Codex. Na primeira utilização, o Codex abre uma aba do navegador para https://iam.wink.travel.

5. Faça login 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 subscritores 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 Settings.

3. Vá a Connectors (ou MCP Servers dependendo da versão da app) e clique em Add.

4. Introduza a URL do servidor Inventory da Wink:

   https://api.wink.travel/mcp

   Depois clique em Connect.

5. O ChatGPT abre uma aba do navegador para https://iam.wink.travel. Faça login na Wink e aprove as permissões.

6. Repita os passos 4–5 para o servidor Integrations:

   https://integrations.wink.travel/mcp

7. Ambos os servidores aparecem na sua lista de Connectors. Inicie uma nova conversa — as ferramentas Wink estarã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-inventory": {
         "type": "http",
         "url": "https://api.wink.travel/mcp"
       },
       "wink-integrations": {
         "type": "http",
         "url": "https://integrations.wink.travel/mcp"
       }
     }
   }

3. Abra o Cursor. Vá a Settings → Cursor Settings → MCP e confirme que ambos os servidores aparecem com um indicador de estado verde. Se estiverem vermelhos, clique em Refresh.

4. O Cursor abre uma aba do navegador para https://iam.wink.travel. Faça login 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 na pasta ~/.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-inventory": {
         "type": "http",
         "url": "https://api.wink.travel/mcp"
       },
       "wink-integrations": {
         "type": "http",
         "url": "https://integrations.wink.travel/mcp"
       }
     }
   }

3. Reinicie completamente o Windsurf (Ficheiro → Quit, depois reabra).

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

5. Faça login na Wink e aprove as permissões. Os servidores ficam verdes no painel de configurações assim que autenticados.

Nota

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

Cline (VS Code)

O Cline é uma extensão para VS Code com gestor de servidores MCP integrado. 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 Install

2. Clique no ícone do Cline na Activity Bar (barra lateral esquerda) para abrir o painel do Cline.

3. Clique no ícone MCP Servers (ícone de ficha) na barra de ferramentas do Cline, depois escolha Edit MCP Settings.

4. O VS Code abre o ficheiro cline_mcp_settings.json. Adicione as entradas da Wink:

   cline_mcp_settings.json

   {
     "mcpServers": {
       "wink-inventory": {
         "type": "http",
         "url": "https://api.wink.travel/mcp"
       },
       "wink-integrations": {
         "type": "http",
         "url": "https://integrations.wink.travel/mcp"
       }
     }
   }

5. Guarde o ficheiro. O Cline recarrega automaticamente e abre uma aba do navegador para https://iam.wink.travel.

6. Faça login na Wink e aprove as permissões. Ambos os servidores aparecem como ativos no painel MCP Servers.

Alternativa: adicionar via URL

No painel MCP Servers, clique em Add Server e cole diretamente https://api.wink.travel/mcp. O Cline preenche automaticamente a configuração e gere a autenticação sem necessidade de editar JSON manualmente.

---

Escopos

Quando aprova o ecrã de consentimento verá um detalhamento do que o agente está a solicitar. Os clientes MCP usam o mesmo vocabulário de permissões que o resto da plataforma — consulte 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 detenha um escopo mcp.* é admitido em /mcp, mas cada ferramenta que invoca ainda aplica o escopo da secção do endpoint que envolve (ex.: booking.read).
• O cliente de IA solicita apenas os escopos que precisa. Pode negar permissões individuais no ecrã de consentimento — ferramentas que requerem um escopo negado retornam erro quando invocadas.

---

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 através do atualizador integrado da app

401 Unauthorized após login

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-inventory
claude mcp add wink-inventory https://api.wink.travel/mcp --transport http

Para Claude Desktop e ChatGPT, remova a entrada do servidor nas configuraçõ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. Reconecte o servidor — o ecrã de consentimento aparecerá novamente para aprovar a permissão em falta.

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

Está autenticado numa conta Wink sem entidade gestora. Aceda ao Wink Portal e certifique-se de que a sua conta está configurada antes de usar o servidor MCP.

Token expira durante a sessão

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

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 é só para binários locais.

Menu “Connectors” do ChatGPT está ausente

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

Servidor Cursor aparece vermelho / “Failed to connect”

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

Servidores MCP do Windsurf não aparecem nas configurações

O Windsurf requer reinício completo (não só recarregar a janela) para aplicar alterações em mcp_config.json. Use File → Quit e reabra. Se os servidores ainda não aparecerem, confirme que está na versão Windsurf 1.4+ em Help → About Windsurf.

Opção “Add Server” do Cline não está visível

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

---

Abrir Wink Portal Wink no GitHub