My Next Adventure

npx add-mcp 'https://mcp.mynextadventure.cloud/mcp'

Servidor MCP MyNextAdventure

Un servidor remoto Model Context Protocol que permite a un asistente de IA planificar viajes en MyNextAdventure: crear un viaje, diseñar el itinerario, proponer vuelos y hoteles, añadir actividades y compartir el resultado.

Se ejecuta como un Cloudflare Worker sin estado y es un proxy autenticado y ligero frente a la API pública de MyNextAdventure: no almacena datos de viajes propios y reenvía cada llamada a la API con la clave API del usuario que realiza la llamada.

• Producción: https://mcp.mynextadventure.cloud/mcp (HTTP Streamable)
• API ascendente: https://api.mynextadventure.cloud (API pública v1)

Autenticación

Cada solicitud necesita una clave API de MyNextAdventure. Crea una en la aplicación en Configuración → Claves API y envíala como:

• Authorization: Bearer <api-key> — lo que envían la mayoría de clientes MCP, y lo que hace mcp-remote, o
• X-API-Key: <api-key> — para clientes que solo permiten configurar encabezados personalizados.

El worker la reenvía a la API como X-API-Key. Las solicitudes sin clave reciben un 401. Lo que la clave pueda hacer, el asistente puede hacerlo: las claves son por usuario, por lo que el asistente solo ve los viajes de ese usuario.

Dónde vive tu clave. El servidor no tiene estado: tu clave se lee de los encabezados de cada solicitud, se usa para realizar esa única llamada a la API de MyNextAdventure y nunca se almacena — no hay almacenamiento de sesión ni un Durable Object que la conserve entre solicitudes. Nunca se registra y no se comparte entre solicitudes ni usuarios. Revoca una clave en cualquier momento en la aplicación en Configuración → Claves API.

Herramientas

24 herramientas que cubren las operaciones que la planificación conversacional realmente necesita. Cada una es una vista seleccionada sobre una operación de la API de MyNextAdventure — consulta Regeneración de herramientas.

Herramienta	Qué hace
whoami	A qué cuenta pertenece la clave API (útil para comprobar la conexión).
list_trips	Lista los viajes del usuario; filtra por estado (planning, ready, finished, cancelled).
get_trip	Un viaje completo: variantes, destinos, opciones, eventos. Necesario antes de cualquier edición.
create_trip	Crea un viaje nuevo y vacío.
update_trip	Renombra, establece una foto de portada o mueve el viaje por su ciclo de vida.
create_trip_share_link	Crea/actualiza un enlace de uso compartido público de solo lectura.
create_variant	Añade un plan alternativo (las fechas viven aquí: exactas o flexibles).
duplicate_variant	Copia una variante con todo su contenido.
update_variant	Renombra una variante, cambia sus fechas o notas.
select_variant	Marca una variante como el plan elegido.
add_destination	Añade una parada a una variante, en orden de itinerario.
update_destination	Cambia el nombre del lugar, las fechas o las notas de una parada.
reorder_destinations	Reordena las paradas de una variante.
add_accommodation_option	Propone un lugar para alojarse en un destino.
add_transport_option	Propone una forma de llegar a un destino.
add_getting_around_option	Propone movilidad local (transporte público, coche de alquiler, …).
update_destination_option	Edita una opción existente de cualquiera de los tres tipos.
select_destination_option	Selecciona — o, sin optionId, deselecciona — una opción.
add_event	Añade una actividad (museo, concierto, restaurante, visita) a una variante.
update_event	Edita una actividad.
toggle_event	Cambia una actividad entre confirmada y "solo una idea".
delete_trip_item	Elimina permanentemente una variante, destino, opción o evento. Eliminar una variante completa además requiere confirm: true.
list_goals	Lista los objetivos de viaje / lista de deseos del usuario.
add_goal	Añade un objetivo a partir de un nombre o una URL.

El servidor también incluye MCP instructions que describe el modelo de datos (trip → variants → destinations → options, con eventos en la variante) y el orden habitual de operaciones, para que un cliente no tenga que adivinar el flujo de trabajo.

Aún no expuestas, aunque la API las admite: gestión de acceso de colaboradores e invitaciones, votación, colecciones, tokens de invitación, vinculación objetivo↔viaje, gestión de claves API y eliminación de viajes.

Conexión

Claude Desktop

Configuración → Desarrollador → Editar configuración y añade:

{
  "mcpServers": {
    "mynextadventure": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.mynextadventure.cloud/mcp",
        "--header",
        "Authorization: Bearer ${MNA_API_KEY}"
      ],
      "env": { "MNA_API_KEY": "your-api-key" }
    }
  }
}

Reinicia Claude Desktop; las herramientas aparecen bajo el conector.

claude.ai / Claude Code

Añade un conector personalizado que apunte a https://mcp.mynextadventure.cloud/mcp y establece el encabezado Authorization: Bearer <api-key>. Desde Claude Code:

claude mcp add --transport http mynextadventure https://mcp.mynextadventure.cloud/mcp \
  --header "Authorization: Bearer <api-key>"

ChatGPT

Configuración → Conectores → Añadir conector personalizado, URL del servidor MCP https://mcp.mynextadventure.cloud/mcp, autenticación "encabezado personalizado" con X-API-Key: <api-key> (o Authorization: Bearer <api-key>).

Cualquier otro cliente MCP

HTTP Streamable en /mcp. GET / devuelve un pequeño documento JSON de estado con el endpoint y el número de herramientas.

Desarrollo

npm install
npm run dev              # wrangler dev on http://localhost:8787
npm test                 # vitest: request building, schemas, generator freshness
npm run type-check       # tsc --noEmit
npm run generate:tools   # regenerate src/generated/tools.ts from the OpenAPI spec
npx tsx scripts/smoke.ts # drive the MCP protocol against localhost:8787

scripts/smoke.ts realiza un handshake real (initialize → tools/list → un tools/call), leyendo la clave API de $MNA_API_KEY o ~/.config/mna/credentials. Se niega a llamar a herramientas de mutación a menos que se pase --force. Para ejercitar herramientas de escritura sin tocar datos reales, apunta el worker a un mock local:

npx wrangler dev --var MNA_API_BASE_URL:http://localhost:8899

Regeneración de herramientas

Los esquemas de herramientas están generados, no escritos a mano:

apps/server/openapi-v1.json   (the API's OpenAPI snapshot, kept fresh by server CI)
        +
scripts/tool-manifest.ts      (which operations become tools, their names and descriptions)
        ↓  scripts/generator.ts
src/generated/tools.ts        (committed; zod input schemas + request builders)

Para añadir o cambiar una herramienta, edita scripts/tool-manifest.ts y ejecuta npm run generate:tools. Nunca edites src/generated/tools.ts a mano: una prueba falla si se desvía de la especificación.

Una entrada de manifiesto nombra una operación de API, o agrupa varias operaciones sin cuerpo detrás de un argumento discriminador (delete_trip_item's target, select_destination_option's action) para mantener bajo el número de herramientas. Los parámetros de ruta se pueden renombrar (id → tripId), los parámetros de consulta se pueden restringir a enums y las descripciones se pueden sobrescribir — todo lo demás, incluidos los esquemas del cuerpo de la solicitud, proviene de la especificación.

Despliegue

npm run deploy (wrangler) — solo producción, por lo que está restringido a un mantenedor; CI nunca despliega este worker.

Desarrollo

npm ci
npm run type-check
npm test        # includes a drift test: src/generated/tools.ts must match the generator output
npm run dev     # wrangler dev

Las herramientas se generan a partir de la instantánea OpenAPI incluida en spec/openapi-v1.json (especificación canónica en vivo: https://api.mynextadventure.cloud/api/v1/openapi.json) mediante scripts/generate-tools.ts. Regenera después de actualizar la instantánea.

Este repositorio es la fuente desplegable para mcp.mynextadventure.cloud. El desarrollo también ocurre en el monorepo de My Next Adventure y se sincroniza aquí en cada versión. Las incidencias y las solicitudes de extracción son bienvenidas.

Licencia

MIT