Conectar mediante MCP | VillaSlot Documentation

MCP permite que Claude Code consulte tus villas, reservas, clientes y disponibilidad, y cree clientes y reservas por horas o por noches en VillaSlot. Tú autorizas la conexión mediante el consentimiento OAuth: eliges la organización y revisas los permisos antes de dar acceso.

Conecta tu cliente MCP

Añade esta URL de servidor a tu cliente MCP:

https://www.villaslot.io/api/mcp

Inicia la conexión OAuth, accede con tu contraseña o Google y revisa la aplicación, los permisos y la organización antes de autorizar. Una aplicación registrada dinámicamente se muestra como no verificada. Los clientes públicos usan PKCE; offline_access mantiene la conexión mediante renovación. Los tokens de acceso caducan a los 15 minutos.

Elige explícitamente la organización de equipo en el consentimiento. Tu última organización activa solo se preselecciona si conservas acceso de equipo; de lo contrario, elige una aunque sea la única disponible. La organización activa del navegador no cambia. La autorización queda vinculada a tu elección; reconectar crea una autorización nueva. La pertenencia, suspensión y revocación se verifican en cada petición.

Claude Code

Con Claude Code instalado, ejecuta estos comandos en tu terminal:

bash

claude mcp add --transport http --scope user villaslot https://www.villaslot.io/api/mcp
claude mcp login villaslot

El navegador se abre para la conexión OAuth. Inicia sesión en VillaSlot, elige la organización, revisa los permisos solicitados y pulsa Autorizar. El ámbito user permite usar esta configuración en todos tus proyectos de esta máquina.

Después, abre Claude Code:

bash

claude

Escribe /mcp dentro de la conversación de Claude Code para comprobar el servidor villaslot. Si tu versión no ofrece claude mcp login, usa /mcp, selecciona villaslot e inicia allí la autenticación.

Codex

Con la CLI de Codex instalada, añade el servidor:

bash

codex mcp add villaslot --url https://www.villaslot.io/api/mcp

Codex puede ofrecer la conexión OAuth al añadir el servidor. Si todavía no la has completado, ejecuta:

bash

codex mcp login villaslot

En el navegador, inicia sesión en VillaSlot, elige la organización, revisa los permisos y pulsa Autorizar. Después, abre una nueva sesión:

bash

codex

Escribe /mcp dentro de Codex para ver los servidores disponibles. Esta conexión OAuth no requiere una clave API de VillaSlot ni copiar una cabecera Authorization.

Comprueba la conexión

En Claude Code o Codex, pide:

Use the villaslot MCP to list my villas.
State which organization you are using. Do not change any data.

Comprueba que la organización devuelta coincide con la que autorizaste. Una sesión ya abierta puede necesitar reiniciarse para cargar el nuevo servidor.

Para una instancia local o autoalojada, sustituye la URL de los comandos por la de esa instancia seguida de /api/mcp (por ejemplo, http://localhost:3088/api/mcp). Usa un nombre distinto, como villaslot-local, tanto al añadir el servidor como al iniciar sesión. Un servidor local con conexiones salientes bloqueadas puede necesitar un cliente OAuth prerregistrado en lugar del descubrimiento automático del cliente.

Referencias: MCP en Claude Code y MCP en Codex.

Herramientas

Tool	Scope
`list_villas`	`mcp:read`
`get_villa`	`mcp:read`
`list_bookings`	`mcp:read`
`get_booking`	`mcp:read`
`list_customers`	`mcp:read`
`get_customer`	`mcp:read`
`get_availability`	`mcp:read`
`create_customer`	`mcp:customers`
`create_booking`	`mcp:bookings`
`create_overnight_booking`	`mcp:bookings`

Entradas y resultados

Las listas aceptan limit (25 por defecto, máximo 100), offset (0–10000) y search (máximo 200 caracteres). list_villas acepta status: active, archived o all. list_bookings acepta axis: UPCOMING o RECENT, y un propertyId opcional.

get_availability acepta kind: HOURLY, una villa, una date local y una durationMinutes admitida; o kind: OVERNIGHT con checkInDay y checkOutDay. Las estancias tienen un máximo de 366 noches y respetan el mínimo de la organización. Las fechas usan su zona horaria, indicada cuando corresponde. Los importes son enteros en unidades monetarias menores con su divisa: no los conviertas implícitamente por 100.

create_customer acepta un nombre y, opcionalmente, email, teléfono y notas. create_booking acepta identificadores de villa/cliente, fecha, minuto inicial, duración y estado (HOLD o CONFIRMED); precio y porcentaje de depósito son opcionales. create_overnight_booking exige un priceAmount total, identificadores de villa/cliente, fechas de llegada/salida y estado. El total no se calcula desde la tarifa por noche.

Las creaciones respetan los mismos permisos, límites del plan, precios, márgenes, disponibilidad y reglas de conflictos Airbnb que la aplicación. No son idempotentes: no reintentes automáticamente una creación con resultado incierto. Consulta primero los datos. Cada resultado identifica la organización autorizada. No se exponen tokens de enlaces de cliente, secretos de pago ni agregados financieros.

Si una llamada se rechaza porque has desactivado un permiso personal, vuelve a activarlo y pulsa Guardar; no necesitas reconectar. Si la autorización se ha revocado o ha caducado, vuelve a conectar tu cliente MCP y da un nuevo consentimiento. Si has perdido la pertenencia a la organización o el rol necesario, primero debes recuperar el acceso con un rol que permita la operación. Reinicia desde el cliente cualquier solicitud caducada. El registro, los enlaces mágicos y los códigos de recuperación no están disponibles en este flujo OAuth.

Permisos personales, límites y aplicaciones

En Cuenta → Agentes MCP puedes ver las aplicaciones, sus hosts de redirección, scopes y organizaciones. Revocar desconecta la aplicación de todas tus organizaciones inmediatamente, incluidos sus tokens de acceso y renovación. Puedes hacerlo incluso sin acceso de equipo. Reconectar nunca reactiva los tokens antiguos.

Los tres interruptores controlan lectura, creación de reservas y creación de clientes para todas tus aplicaciones. Guarda los cambios para aplicarlos en la próxima llamada sin reconectar. Siguen aplicándose scopes OAuth, permisos del equipo y límites del plan. Un permiso desactivado devuelve MCP_RIGHTS_DENIED, sin un nuevo inicio de sesión.

Si desactivas Leer datos, pulsa Guardar para aplicar el cambio. La siguiente llamada de lectura se rechaza sin necesidad de reconectar. Para volver a permitir la lectura, activa Leer datos y pulsa Guardar. Esto no equivale a Revocar: revocar desconecta la aplicación y exige reconectarla con un nuevo consentimiento.

El límite diario se aplica por separado a cada organización entre todas las aplicaciones: vacío significa ilimitado y cero bloquea las creaciones. Cada cliente, sesión o estancia confirmada en la base cuenta como una creación; leer no cuenta. Un error posterior de respuesta o actividad no descuenta una creación. MCP_DAILY_LIMIT indica que se alcanzó el límite personal. El día corresponde a la zona horaria de la organización al admitir la llamada (UTC si falta). Una zona inválida bloquea creaciones, pero mantiene accesibles la configuración y revocación.