Claude Code MCP: como usar os dados do Little Hotelier no Claude Code, Cursor e VS Code

Adicione um servidor MCP remoto, https://dashboard.hotelier.tools/api/mcp, com uma chave de API do Hotelier Tools, e o Claude Code, o Cursor, o VS Code (modo agente do Copilot), o Windsurf ou o Gemini CLI conseguem ler as suas reservas, tarifas e faturas do Little Hotelier enquanto escrevem código para você. No Claude Code é um único comando: claude mcp add --transport http hotelier-tools https://dashboard.hotelier.tools/api/mcp --header "Authorization: Bearer htk_YOUR_API_KEY".

A seguir ficam as configurações exatas para cada ferramenta (conferidas com a documentação de cada fornecedor em outubro de 2026), três coisas que vale a pena construir e quando chamar diretamente a API REST.

Antes de começar: crie uma chave de API

O Little Hotelier não publica um servidor MCP, e a própria documentação da API de parceiros da SiteMinder diz que os dados de disponibilidade e tarifas não se conseguem obter do Little Hotelier. O Hotelier Tools oferece um servidor MCP e uma API REST, usando o login do Little Hotelier do seu próprio hotel. Não é afiliado à SiteMinder nem ao Little Hotelier, nem tem o aval deles. Contexto: o Little Hotelier tem API?

1. No Hotelier Tools, conecte o Little Hotelier em Credentials (/credentials), se ainda não o fez.
2. Abra Developer → API & MCP → API Keys (/developer/api-keys).
3. Escreva um nome que diga onde a chave vai ficar, como cursor-laptop, e clique em Generate key.
4. Copie-a logo: "Copy this key now — it will not be shown again." Começa por htk_.

demo.hotelier.tools/developer/api-keys

Uma chave tem as mesmas permissões que a sua conta do Hotelier Tools, na única propriedade em que a criou. Pode ter até 10 chaves.

Mantenha a chave fora dos seus ficheiros. Guarde-a numa variável de ambiente chamada HT_API_KEY e referencie-a nas configurações:

echo 'export HT_API_KEY="htk_YOUR_API_KEY"' >> ~/.zshrc   # ou ~/.bashrc

setx HT_API_KEY "htk_YOUR_API_KEY"

Abra um novo terminal (e reinicie o editor) para que ele reconheça a variável.

Como adicionar o servidor MCP ao Claude Code, Cursor, VS Code, Windsurf e Gemini CLI

Cada ferramenta guarda os mesmos três dados (endereço, transporte, chave) num ficheiro ligeiramente diferente. Escolha a sua.

Claude Code

O Claude Code tem um comando integrado para servidores remotos (documentação da Anthropic):

claude mcp add --transport http hotelier-tools https://dashboard.hotelier.tools/api/mcp --header "Authorization: Bearer htk_YOUR_API_KEY"

Depois inicie claude e escreva /mcp. O Hotelier Tools deve aparecer como connected; um estado failed com um 401 significa que a chave está errada.

• Âmbito (scope). Por padrão, o servidor fica guardado só para a pasta atual. Acrescente --scope user a seguir ao nome para o usar em todos os projetos, ou --scope project para escrever um .mcp.json partilhado / compartilhado.
• Login em vez de chave. Execute o comando sem --header, e depois, dentro do Claude Code, escreva /mcp e autentique-se no navegador. Se já conectou o Hotelier Tools como conector no claude.ai, o Claude Code pode aproveitá-lo quando faz login com a mesma conta Claude.

Para um projeto em que trabalha com um colega ou que guarda no Git, ponha o servidor no .mcp.json e deixe cada pessoa fornecer a sua própria chave:

{
  "mcpServers": {
    "hotelier-tools": {
      "type": "http",
      "url": "https://dashboard.hotelier.tools/api/mcp",
      "headers": { "Authorization": "Bearer ${HT_API_KEY}" }
    }
  }
}

A linha "type": "http" é obrigatória: o Claude Code trata uma entrada com url mas sem type como um erro de configuração.

Cursor

O Cursor lê ~/.cursor/mcp.json para todos os projetos, ou .cursor/mcp.json dentro de um projeto (documentação do Cursor):

{
  "mcpServers": {
    "hotelier-tools": {
      "url": "https://dashboard.hotelier.tools/api/mcp",
      "headers": { "Authorization": "Bearer ${env:HT_API_KEY}" }
    }
  }
}

Guarde e depois confirme que o servidor está ativado nas configurações MCP do Cursor (as versões recentes listam os servidores em Customize na barra lateral). Pergunte no chat Agent. Por padrão, o Cursor pede aprovação antes de executar uma ferramenta; mantenha-o assim para este servidor. Se omitir headers, o Cursor oferece o login pelo navegador.

VS Code com GitHub Copilot

O VS Code usa .vscode/mcp.json, com servers como chave de topo e um "type": "http" obrigatório (documentação do VS Code). A sua funcionalidade inputs pede a chave uma vez e guarda-a no armazenamento seguro do VS Code, para que nunca fique no ficheiro:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "ht-api-key",
      "description": "Hotelier Tools API key (htk_…)",
      "password": true
    }
  ],
  "servers": {
    "hotelier-tools": {
      "type": "http",
      "url": "https://dashboard.hotelier.tools/api/mcp",
      "headers": { "Authorization": "Bearer ${input:ht-api-key}" }
    }
  }
}

Abra o Copilot Chat, mude para o modo Agent e use Configure Tools para ver as ferramentas do Hotelier Tools. O VS Code pode pedir-lhe que confie no servidor na primeira vez que é iniciado. Para todos os espaços de trabalho, execute MCP: Open User Configuration e cole lá o mesmo bloco. O VS Code também suporta o login pelo navegador se omitir headers.

demo.hotelier.tools/developer/mcp-setup

Windsurf e Gemini CLI

O Windsurf (cuja documentação passou a estar sob o Devin) lê ~/.codeium/windsurf/mcp_config.json e usa serverUrl para servidores remotos (documentação):

{
  "mcpServers": {
    "hotelier-tools": {
      "serverUrl": "https://dashboard.hotelier.tools/api/mcp",
      "headers": { "Authorization": "Bearer ${env:HT_API_KEY}" }
    }
  }
}

O Windsurf limita o Cascade a 100 ferramentas no total, e o Hotelier Tools oferece mais de 100, por isso pode ter de desativar no painel MCP as ferramentas que não usa.

O Gemini CLI lê ~/.gemini/settings.json (ou .gemini/settings.json num projeto) e usa httpUrl para este tipo de servidor; url significaria o transporte SSE mais antigo, que o Hotelier Tools não serve (documentação):

{
  "mcpServers": {
    "hotelier-tools": {
      "httpUrl": "https://dashboard.hotelier.tools/api/mcp",
      "headers": { "Authorization": "Bearer $HT_API_KEY" }
    }
  }
}

Ou a partir do terminal: gemini mcp add --transport http --header "Authorization: Bearer htk_YOUR_API_KEY" hotelier-tools https://dashboard.hotelier.tools/api/mcp. Escreva /mcp dentro do Gemini CLI para confirmar.

Estas duas configurações seguem a documentação de cada fornecedor; não foram testadas em todas as versões.

Três coisas que vale a pena construir

O truque é deixar o agente usar o MCP para olhar para os seus dados reais e depois escrever código que chama a API REST, para que o resultado funcione todos os meses sem IA.

Um relatório mensal de ocupação

Peça ao Claude Code (ou ao agente do Cursor) numa pasta vazia:

Um bom script começa assim. Vai buscar os tipos de quarto e todas as reservas que se sobrepõem ao mês, e guarda a resposta em bruto para que possa conferir os campos antes de fazer contas:

// Uso: node fetch-month.mjs 2026-09   (precisa de HT_API_KEY no seu ambiente)
import { writeFile } from "node:fs/promises";

const API = "https://dashboard.hotelier.tools/api/v1";
const headers = {
  Authorization: `Bearer ${process.env.HT_API_KEY}`,
  "Content-Type": "application/json",
};

async function call(path, options = {}) {
  const res = await fetch(`${API}${path}`, { ...options, headers });
  if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
  return res.json();
}

const month = process.argv[2];
const [year, mon] = month.split("-").map(Number);
const startDate = `${month}-01`;
const endDate = new Date(Date.UTC(year, mon, 0)).toISOString().slice(0, 10);

const roomTypes = await call("/room-types");
const reservations = await call("/methods/getReservationsByDateRange", {
  method: "POST",
  body: JSON.stringify({ params: { startDate, endDate } }),
});

await writeFile(
  `raw-${month}.json`,
  JSON.stringify({ roomTypes: roomTypes.data, reservations: reservations.result }, null, 2)
);
console.log(`Saved raw-${month}.json`);

A própria especificação da API diz que os objetos de reserva vêm do Little Hotelier e que a sua "shape may vary" (estrutura pode variar), por isso deixe o agente ler o ficheiro guardado antes de calcular o que quer que seja. /room-types dá o totalRooms por tipo, que é a outra metade da conta da ocupação.

Uma sincronização com o Google Sheets

Para uma folha de cálculo / planilha que lista as chegadas dos próximos 30 dias e se atualiza todas as manhãs, abra a sua folha no Google Sheets, vá a Extensions → Apps Script e cole:

function syncArrivals() {
  const key = PropertiesService.getScriptProperties().getProperty('HT_API_KEY');
  const fmt = d => Utilities.formatDate(d, Session.getScriptTimeZone(), 'yyyy-MM-dd');
  const today = new Date();
  const in30 = new Date(today.getTime() + 30 * 24 * 60 * 60 * 1000);
  const url = 'https://dashboard.hotelier.tools/api/v1/reservations'
    + '?startDate=' + fmt(today) + '&endDate=' + fmt(in30) + '&limit=100';

  const res = UrlFetchApp.fetch(url, {
    headers: { Authorization: 'Bearer ' + key },
    muteHttpExceptions: true,
  });
  if (res.getResponseCode() !== 200) throw new Error(res.getContentText());

  const rows = JSON.parse(res.getContentText()).data.map(r => [
    r.id, r.guestName, r.status, r.checkIn, r.checkOut, r.roomType, r.totalAmount,
  ]);
  const book = SpreadsheetApp.getActive();
  const sheet = book.getSheetByName('Arrivals') || book.insertSheet('Arrivals');
  sheet.clearContents();
  sheet.appendRow(['ID', 'Guest', 'Status', 'Check-in', 'Check-out', 'Room type', 'Total']);
  if (rows.length) sheet.getRange(2, 1, rows.length, rows[0].length).setValues(rows);
}

Guarde a chave em Project Settings → Script properties como HT_API_KEY, execute-o uma vez para conceder acesso e depois acrescente um acionador diário por tempo em Triggers. /reservations devolve no máximo 100 estadias por chamada, filtradas pela data de check-in, por isso divida os meses movimentados em semanas. Lembre-se de que a folha passa a conter nomes de hóspedes: tenha cuidado com quem tem acesso a ela.

Um pequeno dashboard personalizado

Duas regras tornam isto seguro: a chave fica no servidor (qualquer pessoa que abra uma página consegue ler chaves no código do navegador) e o uso de cache, porque a API permite 100 pedidos por minuto por endereço IP.

MCP ou API REST: qual usar?

Ambos usam a mesma chave e as mesmas permissões. O guia da API REST está em API do Little Hotelier.

Ferramentas de leitura e de escrita: mantenha o agente sob rédea curta

Os agentes de programação são bons a executar ferramentas depressa, e é exatamente por isso que convém fazê-los ir mais devagar aqui.

• As escritas são executadas assim que o agente as chama. Fora do dashboard do Hotelier Tools não há cartão de aprovação. Alterar uma reserva, lançar um pagamento, aplicar preços ou definir stop sell acontece assim que a ferramenta é executada. Mantenha ativa a opção do seu editor "perguntar antes de executar ferramentas" e não use modos de execução automática com este servidor.
• As ações irreversíveis ficam bloqueadas de qualquer modo. Oito ferramentas (enviar faturas por e-mail aos hóspedes, reembolsos, enviar o questionário do INE, convites a funcionários, enviar links por e-mail aos hóspedes, responder a perguntas do Booking.com e a verificação da lista de espera que envia mensagens aos hóspedes) só funcionam no dashboard.
• As alterações a reservas fazem-se em dois passos. propose_reservation_changes mostra o antes e o depois; apply_reservation_changes precisa de confirmed: true. Leia a proposta.
• Nunca faça commit de uma chave. Use referências no estilo ${HT_API_KEY}, acrescente os ficheiros de configuração locais ao .gitignore e revogue qualquer chave que vaze em /developer/api-keys.

Resolução de problemas: "o servidor não aparece"

• Nada aparece depois de editar uma configuração: reinicie o editor ou a CLI. A maioria das ferramentas lê as configurações MCP ao iniciar.
• O Claude Code ou o VS Code ignora o servidor: confirme o "type": "http".
• O Gemini CLI conecta-se mas falha: use httpUrl, não url.
• 401: chave errada ou revogada, ou a variável de ambiente não está definida nesse terminal.
• 400 "No Little Hotelier credentials configured": conecte o Little Hotelier em /credentials.
• 423 lh_frozen: o login no Little Hotelier está em pausa após uma tentativa falhada (muitas vezes uma palavra-passe / senha expirada). Guarde a nova palavra-passe em Credentials ou clique em Check now & resume.
• 429: demasiados pedidos; espere o tempo indicado em Retry-After.
• A quebra de linha com barra invertida falha no Windows: o PowerShell não usa \ para continuar linhas. Cole os comandos numa só linha, como mostrado acima.

Próximos passos

• Não é programador? Conecte o Claude ou o ChatGPT no navegador.
• Novo nesta ideia? Leia o que é um servidor MCP.
• Quer folhas de cálculo sem código? Veja exportar reservas para o Excel.