MCP: un asistente de IA en el tracker
Desde la versión 0.9.5.0 puedes conectar un asistente de IA (Claude Desktop y otros clientes MCP) a Orbitra a través del servidor MCP — vive en la carpeta mcp/. Una vez conectado, el tracker se maneja en lenguaje natural:
"¿Cómo les fue a mis campañas en los últimos 7 días?"
"Crea 10 campañas para la oferta #4 — una por GEO: US, CA, GB, DE, FR."
"Añade el dominio track.example.com y pon la campaña 12 en su raíz."
El servidor habla con tu tracker por HTTPS usando una clave de API personal. No guarda nada de su lado, y las claves de solo lectura físicamente no pueden modificar datos.
Cómo funciona
Claude Desktop ──stdio──► mcp/src/index.js ──HTTPS + API key──► ваш Orbitra (api.php)
El servidor MCP es un cliente delgado sobre la API regular del tracker (api.php). Simplemente envuelve las acciones de la API en tools que una IA entiende y añade una salvaguarda (las claves read no pueden escribir).
Paso 1. Consigue una clave de API
En el panel: ⚙ → AI / MCP o ⚙ → Users → API keys (las claves las crea un admin).
- Read key — solo analítica (métricas, listas, informes).
- Write key — además gestión (crear/editar/borrar campañas, ofertas, dominios…).
La clave se muestra una sola vez — cópiala.
Paso 2. Instala las dependencias
Cuando la instalación es vía install.sh, las dependencias de MCP se instalan automáticamente. A mano:
cd mcp
npm install
Autochequeo (arranca el servidor y muestra la lista de tools; no hace falta un tracker vivo):
npm run smoke
Comprobación contra un tracker vivo:
ORBITRA_URL=https://tracker.example.com ORBITRA_API_KEY=your_key npm run smoke -- --ping
Paso 3. Conecta Claude Desktop
El archivo de configuración de Claude Desktop:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
Opción A. Conexión remota por URL (desde la versión 0.9.6.2)
La opción más rápida, y la única que funciona en la versión de navegador de Claude: el propio tracker sirve MCP por HTTP a través de mcp.php.
- ⚙ → Users → API keys, crea una clave (Read — solo analítica, Write — además gestión).
- Pulsa el botón de enlace junto a la clave — una URL lista se copia al portapapeles:
https://ваш-трекер.example.com/mcp.php?k=ВАШ_КЛЮЧ
- En Claude: Settings → Connectors → Add custom connector, pega la URL, pon un nombre, "Add".
Nada que instalar — ni Node ni el repositorio en tu máquina.
🔑 La clave viaja justo dentro de la URL, porque el diálogo del conector no tiene campo para una clave y solo soporta OAuth. Trata esa URL como una contraseña: no la publiques, y para cortar el acceso borra la clave en ⚙ → Users → API keys — la URL deja de funcionar de inmediato. Una clave read físicamente no puede cambiar nada.
Cómo funciona. mcp.php implementa MCP Streamable HTTP sin sesiones: cada POST es un intercambio JSON-RPC autosuficiente. Toma la lista de tools de mcp/tools.json, que se genera desde el servidor Node (node mcp/src/manifest.js), así que ambos tipos de conexión muestran exactamente el mismo conjunto de 41 tools. Una llamada a un tool corre como un proceso CLI corto cli/api_invoke.php — el tracker no se llama a sí mismo por HTTP, lo que en un VPS con dos workers de PHP-FPM podría bloquear el sitio entero.
Requisitos: PHP CLI (ya hace falta para el cron) y proc_open permitido. Si proc_open está deshabilitado en el php.ini, el endpoint te lo dirá en texto plano — usa la opción B en ese caso. La ruta de PHP se puede fijar a mano con el ajuste mcp_php_binary.
Opción B. Servidor local para Claude Desktop
⚠️ Este no es el diálogo "Add custom connector". La sección Connectors de Claude solo acepta servidores MCP remotos por HTTPS y los autoriza vía OAuth — por eso ahí no hay campo de clave de API. El servidor de Orbitra corre por stdio: arranca localmente junto al asistente y se registra en el archivo de configuración de abajo. Una URL de tracker pegada en el diálogo del conector no funcionará.
Puedes abrir el archivo directamente desde la app: Settings → Developer → Edit Config.
Añade un servidor orbitra (usa la ruta absoluta a mcp/src/index.js):
{
"mcpServers": {
"orbitra": {
"command": "/usr/local/bin/node",
"args": ["/absolute/path/to/Orbitra/mcp/src/index.js"],
"env": {
"ORBITRA_URL": "https://tracker.example.com",
"ORBITRA_API_KEY": "ваш-api-ключ"
}
}
}
}
Reinicia Claude Desktop por completo (⌘Q en macOS) — las tools de Orbitra aparecerán en la lista. Cerrar la ventana no basta; la configuración solo se lee al arrancar.
Si el servidor no aparece:
- Ruta de Node.
commandnecesita una ruta absoluta: la app no arranca desde tu shell, así que el Node de nvm o Homebrew nunca llega a suPATHy el servidor falla en arrancar en silencio. Encuentra la ruta conwhich node(macOS/Linux) owhere node(Windows). - Dependencias sin instalar.
cd mcp && npm install. - Clave o URL equivocadas. Verifica aparte:
ORBITRA_URL=... ORBITRA_API_KEY=... npm run smoke -- --ping. 403 API key is read-onlyal crear o actualizar — necesitas una clave Write; una clave Read solo devuelve analítica.
Tools (41)
Read: orbitra_ping, orbitra_get_metrics, orbitra_get_chart, orbitra_list_campaigns, orbitra_campaigns_stats, orbitra_get_campaign, orbitra_campaign_report, orbitra_list_offers, orbitra_get_offer, orbitra_all_offers, orbitra_list_domains, orbitra_ssl_environment, orbitra_get_integration_code, orbitra_list_app_configs, orbitra_telegram_status, orbitra_integrations_status, orbitra_list_traffic_sources, orbitra_list_landings, orbitra_list_affiliate_networks, orbitra_list_conversions, orbitra_recent_clicks, orbitra_system_status.
Gestión (requiere una clave write): orbitra_create_campaign, orbitra_update_campaign, orbitra_bulk_create_campaigns, orbitra_bulk_set_campaign_domain, orbitra_delete_campaign, orbitra_copy_campaign, orbitra_create_offer, orbitra_update_offer, orbitra_delete_offer, orbitra_create_domain, orbitra_delete_domain, orbitra_check_domain_dns, orbitra_reissue_ssl, orbitra_run_ssl_worker, orbitra_save_app_config, orbitra_create_traffic_source, orbitra_list_traffic_source_templates, orbitra_create_landing.
Avanzado: orbitra_api_request — llama a cualquier acción de api.php directamente (la opción de reserva).
Cuentas grandes. orbitra_list_campaigns y orbitra_list_domains devuelven listas compactas (id, name, alias, domain, link) con filtros por rango de IDs y por dominio y paginación — la respuesta queda pequeña incluso con miles de campañas. Las estadísticas de todas las campañas salen de orbitra_campaigns_stats (una respuesta pesada), para una sola — orbitra_campaign_report. Para cambiar el dominio de muchas campañas a la vez — orbitra_bulk_set_campaign_domain: solo cambia el dominio, los flujos y los postbacks no se tocan, y la respuesta lleva el enlace viejo y el nuevo de cada campaña. orbitra_update_campaign preserva los IDs de flujo, sus nombres, la lógica de filtros, la selección de ofertas y el Bot Challenge.
La referencia completa de parámetros vive en mcp/README.md.
Seguridad
- Trata la clave de API como una contraseña. Usa una clave read por defecto; write solo
cuando haga falta gestión.
- La clave va solo a tu
ORBITRA_URL(cabecerasAuthorization: Bearer/X-Api-Key). - Las acciones de escritura pasan por la API regular y aterrizan en los logs de auditoría como cualquier otra operación.
- Una clave read recibe un
403en los intentos de escritura y no cambia nada. ORBITRA_INSECURE=1desactiva la verificación TLS — solo para desarrollo local.
Actualizaciones
MCP viene con el proyecto, así que la actualización regular (⚙ → Update o git pull) trae los archivos nuevos automáticamente. Tras una actualización que cambió dependencias, ejecuta cd mcp && npm install. Si la lista de tools cambió en la versión nueva, reconecta el conector en el cliente para que relea las tools.
Inicio rápido: tu primera campaña
El camino corto: instala el tracker, crea la red, la oferta y la campaña, y consigue tus primeros clics y conversiones en menos de una hora.
Leer la guía →DocsInstalación y actualizaciones
Instala Orbitra en un servidor Ubuntu o Debian recién creado con un solo comando, actualiza PHP y las versiones nuevas de forma segura.
Leer la guía →DocsMigrar desde Keitaro
Mueve campañas, ofertas, fuentes y dominios de Keitaro a Orbitra con un dump SQL — qué se transfiere y qué revisar después.
Leer la guía →DocsMigrar desde Binom
Mueve campañas y flujos de Binom v2 a Orbitra vía su Public API — qué se transfiere automáticamente y qué se ajusta a mano.
Leer la guía →DocsResumen de funciones
Todo lo que Orbitra puede hacer: campañas y flujos, cloaking, landings, PWA, postbacks, costos, informes e integraciones.
Leer la guía →DocsCampañas y flujos
La referencia completa: ajustes de campaña, tipos de flujo, esquemas, rotación, filtros, test links y cada opción explicada.
Leer la guía →DocsCloaking: referencia completa
Referencia completa del cloaking: capas de detección, sensibilidad, ajustes globales, veredictos, motivos e informes.
Leer la guía →DocsBrowser check
Cómo el check JS atrapa bots, VMs y emuladores por contradicciones del navegador: modos Off / Observe / Soft / Strict y sus signos.
Leer la guía →DocsLanding pages (referencia)
Tipos de landing, la macro {offer}, el adaptador JS, LeadForge y landings multi-oferta — la referencia completa.
Leer la guía →DocsPWA y Web Push
Crea apps PWA instalables y tu propia base de suscriptores push: constructor, claves VAPID, mensajes, atribución y solución de problemas.
Leer la guía →DocsEmbudo de PWA
Cómo funciona el embudo configurable de una PWA: pasos y tipos de pantalla, tracking por pantalla, estadísticas del embudo y vista previa en el editor.
Leer la guía →DocsPopups de conversión
Muestra conversiones reales como popups en tus landings: activación por campaña, plantillas por vertical, disparadores y ubicación.
Leer la guía →DocsGrabaciones de sesión y mapas de calor
Reproduce visitas reales y consulta el mapa de calor de clics y de scroll. Límites de almacenamiento y notas de privacidad.
Leer la guía →DocsContent Gallery (referencia)
Almacenamiento central de iconos, capturas y creativos usados en PWAs y landings: carpetas, límites y el MediaPicker en los editores.
Leer la guía →DocsBiblioteca de creativos
Almacena creativos con tracking de subid y pruébalos en distintas campañas: métricas por creativo sincronizadas con Facebook y TikTok.
Leer la guía →DocsPWA externas y canales de Telegram
Publica PWAs en dominios externos y usa canales de Telegram como fuente de tráfico con suscriptores atribuidos.
Leer la guía →DocsPostbacks y conversiones
Postbacks entrantes, estados y tipos de conversión, y postbacks S2S salientes hacia tu fuente de tráfico.
Leer la guía →DocsCostos
Importa el gasto de Facebook, TikTok y Google Ads, o actualízalo por API y cron — y cómo funciona el agregador de ingresos.
Leer la guía →DocsRedes push y pop
Trabajo con fuentes de tráfico push y pop: importación de gasto por campaña y zona, optimización de zonas y el Zone Killer.
Leer la guía →DocsFacebook / Meta
Importación de costos desde Meta Ads y Conversions API: eventos del lado del servidor con deduplicación.
Leer la guía →DocsDolphin / Fbtool
Recibe los costos de Facebook vía la API de Dolphin (Fbtool) en tiempo real: clave de API, configuración de cada servicio y cómo se reparte el gasto entre los clics.
Leer la guía →DocsFB Comment Cleaner
Modera en bloque los comentarios bajo tus anuncios de Meta: ocultar, borrar y filtrar por palabras clave, con dry run, journal y auto-pausa.
Leer la guía →DocsFuentes de tráfico y redes de afiliados
Los dos directorios que configuran los bordes del embudo: plantillas y parámetros de fuentes y redes, postback global, macros de oferta y LeadForge.
Leer la guía →DocsInformes, logs y métricas
El constructor de informes, tendencias y cohortes, el log de tráfico y la tarjeta del clic, más la definición de cada métrica.
Leer la guía →DocsDominios y SSL
Añade dominios, apunta el DNS y emite certificados Let's Encrypt gratis: ajustes del dominio, modos SSL, registrars conectados y Backorder.
Leer la guía →DocsCloudflare
Cómo pasar los dominios de campaña por Cloudflare vía API: token, parking automático del registro A, modos SSL de zona y proxy.
Leer la guía →DocsAdministración
Usuarios, roles y permisos, ajustes de seguridad y privacidad, bases de datos geo, actualizaciones y estado del sistema.
Leer la guía →DocsBot de Telegram
Gestiona el tracker desde Telegram: estadísticas, conversiones y alertas en el chat, con webhook o polling.
Leer la guía →DocsMCP: un asistente de IA en el tracker
Conecta Claude o cualquier cliente MCP a Orbitra y maneja campañas con comandos en lenguaje natural: claves de API, conexión y seguridad.
Leer la guía →