API y MCP para agentes

Cómo un agente conversacional busca, consulta agenda y reserva en Lukin: manifiestos de descubrimiento, contrato OpenAPI, canal MCP y las cinco tools con sus campos obligatorios.

Descubrimiento

/.well-known/ai-plugin.json
Manifiesto de plugin: nombre del modelo, autenticación y dónde están el OpenAPI y el canal MCP.
/.well-known/mcp.json
Descubrimiento MCP: el servidor de Lukin, su transporte streamable-http y su guía.
/llms.txt
El mismo mapa en prosa, en el formato de llmstxt.org, para un modelo que solo conoce el dominio.
https://staging.lukin.cl/openapi.json
Contrato HTTP completo, con un ejemplo por operación. Es lo que necesita un agente que no habla MCP.
https://staging.lukin.cl/mcp
Canal MCP, transporte streamable-http, sin autenticación.
https://staging.lukin.cl/api/v1/agent/guide
La guía en markdown: el flujo completo con ejemplos curl paso a paso y el catálogo de errores.

El flujo, en cuatro pasos

  1. Buscar search_lukin_services

    Comuna y tipo de servicio en las palabras de la persona. Devuelve el slug del local y el service_id.

  2. Consultar agenda get_availability_matrix

    Las horas libres reales de ese servicio. Copia un starts_at tal cual: no se inventan horas.

  3. Reservar execute_agent_booking

    Aparta el hueco unos minutos con consent_accepted y devuelve confirmation_url y status_token.

  4. Confirmar el titular, en confirmation_url

    La persona acepta los textos legales y teclea su código de 4 dígitos. Sin eso, el hueco vuelve a la agenda.

Las cinco tools del canal MCP

ping

Estado del servidor

Comprueba que el canal MCP está vivo y devuelve su versión, la hora del servidor y la lista de tools. Llámala al abrir la sesión para descubrir el catálogo antes de planificar nada.

Entrada obligatoria
—
Salida garantizada
—

search_lukin_services

Buscar servicios en Lukin

Busca locales que puedan atender lo que la persona pide, en una comuna de Chile y —si quieres— con hora libre en un rango de fechas. Es la primera tool de cualquier conversación sobre reservar: devuelve el slug y el business_id con los que se piden agenda y se reserva.

Entrada obligatoria
service_type
Salida garantizada
total, query_understood, next_step_hint

get_availability_matrix

Agenda disponible de un servicio

Devuelve las horas libres reales de un servicio, agrupadas por día y con el offset del negocio. Es la única fuente de horas válidas: una hora inventada se rechaza al crear la reserva.

Entrada obligatoria
business, service_id, date_from
Salida garantizada
timezone, business, service, days, total_slots, warnings, next_step_hint

execute_agent_booking

Reservar en nombre de una persona

escribe

Abre la reserva en estado PENDING y aparta el hueco hasta expires_at: no está confirmada al volver de la llamada. Exige consent_accepted y devuelve la confirmation_url que el titular tiene que abrir para teclear su código.

Entrada obligatoria
business, service_id, starts_at, customer, consent_accepted
Salida garantizada
booking_id, status, created, expires_at, otp_channel, payment_checkout_url, confirmation_url, status_token, summary_for_user, next_step_hint

get_booking_status

Estado de una reserva

Dice si la reserva sigue pendiente, si el titular ya la confirmó, si el pago se acreditó o si se canceló. Pregúntale a ella en vez de volver a preguntarle a la persona; necesita el token de esa reserva.

Entrada obligatoria
booking_id
Salida garantizada
booking_id, status, cancelled_reason, otp_verified, starts_at, ends_at, timezone, business, service, staff_name, payment_status, expires_at, next_action_hint

El consentimiento lo da la persona

Un agente no confirma reservas. Puede apartar un hueco declarando que mostró los textos legales, pero la reserva solo queda en pie cuando el titular abre su enlace de confirmación, acepta la política de privacidad y teclea el código de cuatro dígitos que le enviamos. Si no lo hace antes de expires_at, la hora vuelve a la agenda.