API y MCP

Conecta un agente de IA (Cursor, Claude, ChatGPT) a tu cuenta de GuiaFlow para crear tours a partir de capturas de pantalla, ajustar textos y publicar el enlace permanente. Exclusivo del plan Pro.

Conectar

La dirección del servidor MCP es https://app.guiaflow.pro/mcp (Streamable HTTP). Con el login en el navegador (OAuth) no hay clave que copiar: la app abre la página de GuiaFlow, entras y eliges los permisos.

Instalación en un clic y paso a paso por app: Integraciones.

Cursor

Pega en ~/.cursor/mcp.json (o Settings → MCP → Add new MCP server). En la primera llamada Cursor pide el login.

{
  "mcpServers": {
    "guiaflow": { "url": "https://app.guiaflow.pro/mcp" }
  }
}

Con clave de API (sin login en el navegador):

{
  "mcpServers": {
    "guiaflow": {
      "url": "https://app.guiaflow.pro/mcp",
      "headers": { "Authorization": "Bearer gf_live_xxxxxxxx" }
    }
  }
}

Claude Code

claude mcp add --transport http guiaflow https://app.guiaflow.pro/mcp

Luego ejecuta /mcp dentro de Claude Code y elige guiaflow para entrar.

Con clave de API (sin login en el navegador):

claude mcp add --transport http guiaflow https://app.guiaflow.pro/mcp \
  --header "Authorization: Bearer gf_live_xxxxxxxx"

Claude.ai, Claude Desktop y ChatGPT

En Claude: Configuración → Conectores → Añadir conector personalizado, pega https://app.guiaflow.pro/mcp y pulsa Conectar. En ChatGPT: Configuración → Apps y conectores → Modo desarrollador → Crear, con la misma URL y autenticación OAuth.

VS Code

Pega en .vscode/mcp.json.

{
  "servers": {
    "guiaflow": { "type": "http", "url": "https://app.guiaflow.pro/mcp" }
  }
}

Claves de API

En el editor, abre el menú de la cuenta → Claves de API. Ponle un nombre, elige permisos y validez (30, 90 o 365 días). La clave empieza con gf_live_ y se muestra una sola vez. Ahí mismo revocas claves, desconectas apps y ves los últimos usos.

Permisos

tours:read lee tours · tours:write crea y edita · publish publica y retira el enlace permanente · ai escribe textos y genera narración con la IA de GuiaFlow (usa tu cuota mensual: 100 textos y 30 min de audio) · analytics:read lee las estadísticas de los enlaces (solo conteos, sin datos personales).

Herramientas del MCP

Herramienta	Permiso	Qué hace
`list_tours`	`tours:read`	Lista los tours de la cuenta.
`get_tour`	`tours:read`	Pasos, tema, captura de leads, CTA final y enlace publicado.
`create_tour`	`tours:write`	Crea un tour vacío (aparece en el editor con la etiqueta “creado por agente”).
`upload_media`	`tours:write`	Guarda una captura (url https o base64) o devuelve una URL de subida de 15 min.
`add_step / update_step`	`tours:write`	Captura, resaltado y clic (0..1), título, texto, guion de narración.
`reorder_steps / delete_step`	`tours:write`	Reordena o elimina pasos.
`set_theme`	`tours:write`	Tema predefinido o colores #RRGGBB.
`set_lead_capture`	`tours:write`	Paso inicial con nombre/e-mail/teléfono y consentimiento.
`set_end_cta`	`tours:write`	Tarjeta final con WhatsApp (E.164) y/o enlace https.
`publish`	`publish`	Publica en el enlace permanente /p y devuelve URL, embed y la portada del enlace (og:image, generada en el servidor). dryRun:true valida y devuelve `preview.url`, un enlace de vista previa válido por 7 días.
`unpublish`	`publish`	Retira el enlace (requiere confirm:true).
`generate_step_text`	`ai` + `tours:write`	La IA mira la captura del paso y escribe título y texto (y, si lo pides, el guion de narración); lo guarda en el paso. 1 texto de la cuota.
`generate_narration`	`ai` + `tours:write`	Genera la narración (MP3 mono 64 kbps) y la guarda como audio del paso; el paso dura al menos la narración. Cuenta en la cuota de audio.
`get_analytics`	`analytics:read`	Vistas, finalizaciones, clics en el CTA, leads (conteo), serie diaria y embudo por paso; sin tourId, un resumen por enlace.

Coordenadas

Resaltado y clic usan fracciones de la imagen: x, y, width, height entre 0 y 1, desde la esquina superior izquierda. Solo con click, el resaltado se crea alrededor. Los valores fuera de rango se ajustan y la respuesta lo avisa.

API REST

Base https://app.guiaflow.pro/v1, autenticación Authorization: Bearer. Contrato completo en openapi.json. Envía Idempotency-Key en los POST para reintentar con seguridad.

# 1. criar o tour
curl -s https://app.guiaflow.pro/v1/tours \
  -H "Authorization: Bearer $GUIAFLOW_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: demo-checkout-1" \
  -d '{"name":"Demo do checkout"}'

# 2. um passo por captura (coordenadas em fração 0..1 da imagem)
curl -s https://app.guiaflow.pro/v1/tours/$TOUR/steps \
  -H "Authorization: Bearer $GUIAFLOW_KEY" -H "Content-Type: application/json" \
  -d '{"image":{"url":"https://exemplo.com/tela1.png"},
       "title":"Abra o carrinho","text":"Tudo o que o cliente escolheu fica aqui.",
       "highlight":{"x":0.72,"y":0.05,"width":0.2,"height":0.08},
       "click":{"x":0.82,"y":0.09}}'

# 3. publicar (atualiza o mesmo link nas próximas vezes)
curl -s -X POST https://app.guiaflow.pro/v1/tours/$TOUR/publish \
  -H "Authorization: Bearer $GUIAFLOW_KEY"

# 4. (opcional) la IA escribe el texto y la narración del paso
curl -s -X POST https://app.guiaflow.pro/v1/tours/$TOUR/steps/$STEP/generate-text \
  -H "Authorization: Bearer $GUIAFLOW_KEY" -H "Content-Type: application/json" -d '{"narrationScript":true}'
curl -s -X POST https://app.guiaflow.pro/v1/tours/$TOUR/steps/$STEP/narration \
  -H "Authorization: Bearer $GUIAFLOW_KEY"

# 5. estadísticas del enlace (últimos 30 días)
curl -s https://app.guiaflow.pro/v1/tours/$TOUR/analytics -H "Authorization: Bearer $GUIAFLOW_KEY"

Límites

60 llamadas por minuto por clave/app, 600 cambios y 30 publicaciones por hora por cuenta. Imágenes hasta 15 MB (PNG, JPEG, WebP, GIF); el tour publicado hasta 12 MB. Respuestas: 401 credencial inválida o revocada, 402 sin plan Pro, 403 sin el permiso, 429 límite (mira Retry-After).

Seguridad y privacidad

Solo guardamos el hash de claves y tokens. El registro de uso (app, acción, hora, IP con hash) se guarda 90 días y lo ves en Claves de API. Las URLs de imagen solo se descargan por https público. Detalles en Privacidad.

Para agentes: Resumen en texto plano: /llms.txt.