MCP : un assistant IA dans le tracker
À partir de la version 0.9.5.0 vous pouvez connecter un assistant IA (Claude Desktop et autres clients MCP) à Orbitra à travers le serveur MCP — il vit dans le dossier mcp/. Une fois connecté, le tracker se pilote en langage naturel :
« Comment mes campagnes ont-elles performé sur les 7 derniers jours ? »
« Crée 10 campagnes pour l'offre #4 — une par GEO : US, CA, GB, DE, FR. »
« Ajoute le domaine track.example.com et mets la campagne 12 sur sa racine. »
Le serveur parle à votre tracker en HTTPS avec une clé API personnelle. Il ne stocke rien de son côté, et une clé en lecture seule ne peut physiquement pas modifier des données.
Comment ça marche
Claude Desktop ──stdio──► mcp/src/index.js ──HTTPS + API key──► ваш Orbitra (api.php)
Le serveur MCP est un client fin au-dessus de l'API ordinaire du tracker (api.php). Il se contente d'envelopper les actions de l'API en tools compréhensibles par une IA et ajoute un garde-fou (les clés read ne peuvent pas écrire).
Étape 1. Obtenir une clé API
Dans le panneau : ⚙ → AI / MCP ou ⚙ → Users → API keys (les clés sont créées par un admin).
- Read key — analytics seulement (métriques, listes, rapports).
- Write key — plus la gestion (création/édition/suppression de campagnes, offres, domaines…).
La clé n'est affichée qu'une fois — copiez-la.
Étape 2. Installer les dépendances
Quand l'installation passe par install.sh, les dépendances MCP sont installées automatiquement. À la main :
cd mcp
npm install
Auto-vérification (démarre le serveur et imprime la liste des tools ; pas besoin de tracker en live) :
npm run smoke
Vérification contre un tracker en live :
ORBITRA_URL=https://tracker.example.com ORBITRA_API_KEY=your_key npm run smoke -- --ping
Étape 3. Connecter Claude Desktop
Le fichier de config de Claude Desktop :
- macOS :
~/Library/Application Support/Claude/claude_desktop_config.json - Windows :
%APPDATA%\Claude\claude_desktop_config.json
Option A. Connexion à distance par URL (depuis la version 0.9.6.2)
L'option la plus rapide, et la seule qui marche dans la version navigateur de Claude : le tracker sert lui-même le MCP en HTTP à travers mcp.php.
- ⚙ → Users → API keys, créez une clé (Read — analytics seulement, Write — plus la gestion).
- Cliquez le bouton lien à côté de la clé — une URL toute faite est copiée dans le presse-papiers :
https://ваш-трекер.example.com/mcp.php?k=ВАШ_КЛЮЧ
- Dans Claude : Settings → Connectors → Add custom connector, collez l'URL, donnez un nom, « Add ».
Rien à installer — ni Node ni le dépôt sur votre machine.
🔑 La clé voyage directement dans l'URL, parce que le dialogue du connecteur n'a pas de champ pour une clé et ne supporte qu'OAuth. Traitez une telle URL comme un mot de passe : ne la publiez pas, et pour couper l'accès supprimez la clé dans ⚙ → Users → API keys — l'URL cesse de fonctionner immédiatement. Une clé read ne peut physiquement rien changer.
Comment ça marche. mcp.php implémente le MCP Streamable HTTP sans session : chaque POST est un échange JSON-RPC autosuffisant. Il prend la liste des tools dans mcp/tools.json, qui est générée depuis le serveur Node (node mcp/src/manifest.js), donc les deux types de connexion montrent exactement le même set de 41 tools. Un appel de tool tourne comme un court processus CLI cli/api_invoke.php — le tracker ne s'appelle pas lui-même en HTTP, ce qui sinon, sur un VPS avec deux workers PHP-FPM, pourrait bloquer tout le site.
Prérequis : PHP CLI (déjà nécessaire pour le cron) et proc_open autorisé. Si proc_open est désactivé dans php.ini, l'endpoint vous le dira en clair — utilisez l'option B dans ce cas. Le chemin PHP peut être réglé à la main via le réglage mcp_php_binary.
Option B. Serveur local pour Claude Desktop
⚠️ Ce n'est pas le dialogue « Add custom connector ». La section Connectors de Claude n'accepte que des serveurs MCP distants en HTTPS et les autorise via OAuth — c'est pourquoi il n'y a pas de champ de clé API là. Le serveur Orbitra tourne en stdio : il démarre localement à côté de l'assistant et s'enregistre dans le fichier de config ci-dessous. Une URL de tracker collée dans le dialogue du connecteur ne marchera pas.
Vous pouvez ouvrir le fichier directement depuis l'app : Settings → Developer → Edit Config.
Ajoutez un serveur orbitra (utilisez le chemin absolu vers 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-ключ"
}
}
}
}
Redémarrez Claude Desktop complètement (⌘Q sur macOS) — les tools Orbitra apparaîtront dans la liste. Fermer la fenêtre ne suffit pas ; la config n'est lue qu'au démarrage.
Si le serveur n'apparaît pas :
- Chemin de Node.
commanda besoin d'un chemin absolu : l'app ne démarre pas depuis votre shell, donc Node de nvm ou Homebrew n'atteint jamais sonPATHet le serveur échoue à démarrer en silence. Trouvez le chemin avecwhich node(macOS/Linux) ouwhere node(Windows). - Dépendances non installées.
cd mcp && npm install. - Clé ou URL erronée. Vérifiez séparément :
ORBITRA_URL=... ORBITRA_API_KEY=... npm run smoke -- --ping. 403 API key is read-onlyà la création ou à la mise à jour — il vous faut une clé Write ; une clé Read ne renvoie que de l'analytics.
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.
Gestion (nécessite une clé 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.
Avancé : orbitra_api_request — appeler n'importe quelle action api.php directement (l'option de repli).
Grands comptes. orbitra_list_campaigns et orbitra_list_domains renvoient des listes compactes (id, nom, alias, domaine, lien) avec des filtres par plage d'IDs et par domaine et de la pagination — la réponse reste petite même avec des milliers de campagnes. Les stats de toutes les campagnes viennent de orbitra_campaigns_stats (une réponse lourde), pour une seule — orbitra_campaign_report. Pour changer le domaine de beaucoup de campagnes d'un coup — orbitra_bulk_set_campaign_domain : seul le domaine change, les streams et postbacks ne sont pas touchés, et la réponse porte le vieux et le nouveau lien de chaque campagne. orbitra_update_campaign préserve les IDs des streams, leurs noms, la logique des filtres, la sélection d'offres et le Bot Challenge.
Une référence complète des paramètres vit dans mcp/README.md.
Sécurité
- Traitez la clé API comme un mot de passe. Utilisez par défaut une clé read ; write seulement
quand la gestion est nécessaire.
- La clé ne part que vers votre
ORBITRA_URL(en-têtesAuthorization: Bearer/X-Api-Key). - Les actions d'écriture passent par l'API ordinaire et atterrissent dans les logs d'audit comme toute autre opération.
- Une clé read reçoit un
403sur les tentatives d'écriture et ne change rien. ORBITRA_INSECURE=1désactive la vérification TLS — pour le développement local uniquement.
Mises à jour
Le MCP est livré avec le projet, donc la mise à jour ordinaire (⚙ → Update ou git pull) tire les nouveaux fichiers automatiquement. Après une mise à jour qui a changé les dépendances, lancez cd mcp && npm install. Si la liste des tools a changé dans la nouvelle version, reconnectez le connecteur dans le client pour qu'il relise les tools.
Démarrage rapide : votre première campagne
Le chemin court : installez le tracker, créez une campagne et obtenez vos premiers clics et conversions en moins d'une heure.
Lire le guide →DocsInstallation et mises à jour
Installez Orbitra sur un serveur Ubuntu ou Debian tout neuf en une commande, et passez aux nouvelles versions sans risque.
Lire le guide →DocsMigrer depuis Keitaro
Déplacez campagnes, offres, sources et domaines de Keitaro vers Orbitra : ce qui est transféré et quoi vérifier après l'import.
Lire le guide →DocsMigrer depuis Binom
Déplacez campagnes et streams de Binom vers Orbitra via l'API publique v2 : ce qui est transféré automatiquement et quoi régler à la main.
Lire le guide →DocsAperçu des fonctionnalités
Tout ce qu'Orbitra sait faire : campaigns et streams, cloaking, landings, PWA, postbacks, coûts, rapports et intégrations.
Lire le guide →DocsCampaigns et streams
La référence complète : réglages de campagne, types de streams, schémas, rotation, filtres, test links et chaque option expliquée.
Lire le guide →DocsCloaking
La référence complète du cloaking : couches de détection, réglages globaux, filtres par stream, verdicts et rapports.
Lire le guide →DocsBrowser check
Comment la vérification JS attrape bots, VM et émulateurs à travers les contradictions de l'environnement du navigateur.
Lire le guide →DocsLanding pages
Types de landings, la macro {offer}, l'adaptateur JS, LeadForge et les landings multi-offres — la référence complète.
Lire le guide →DocsPWA et Web Push
Construisez des apps PWA installables et collectez des abonnés push : réglages, icônes, événements et notifications.
Lire le guide →DocsFunnel de visite PWA
Le funnel configurable des landings PWA : étapes ordonnées, store, instructions et carte push, tracking par écran, statistiques de transitions et éditeur.
Lire le guide →DocsPopups de conversion
Un popup avec bouton d'offre sur vos landings : templates par vertical, déclencheurs, designs, une vraie étape du funnel et les métriques Popup CTR.
Lire le guide →DocsEnregistrements de session
Replay des visites façon vidéo, heatmap de clics et carte de scroll : activation, sites entiers, consentement cookies, stockage et dépannage.
Lire le guide →DocsContent Gallery : référence complète
La médiathèque partagée du tracker : dossiers, uploads, limites de formats, MediaPicker et contrat de taille dans les éditeurs PWA, landing et offre.
Lire le guide →DocsBibliothèque de créas
L'onglet Creatives de la galerie : sync Facebook/TikTok, dépense et ROI par créa, rattachement des brouillons, alertes burnout et rapports.
Lire le guide →DocsPWA externes et chaînes Telegram
Builders PWA tiers comme cibles de stream avec installs et postbacks attribués, et offres chaîne Telegram via funnel bots avec conversions tg_join.
Lire le guide →DocsPostbacks et conversions
Postbacks entrants, types de conversion et devises, postbacks S2S sortants, macros, file de livraison, testeur, import et Conversions API.
Lire le guide →DocsCoûts : import de la dépense
Import de la dépense Facebook, TikTok, Google Ads et réseaux push/pop : matching par IDs, diagnostics, agences, métriques plateforme et agrégateur de revenus.
Lire le guide →DocsRéseaux push et pop
Import de dépense AdMaven, PropellerAds, Kadam et autres, et le Zone Killer : règles dry-run/auto pour bloquer les zones qui brûlent de l'argent.
Lire le guide →DocsFacebook / Meta
Les deux intégrations Facebook : import de coûts avec mapping des paramètres, et Conversions API avec matching navigateur, consentement et dépannage.
Lire le guide →DocsDolphin / Fbtool
Recevoir les coûts Facebook de Dolphin et Fbtool.pro sur l'endpoint compatible Keitaro : clé API, matching par adset/ad et répartition de la dépense sur les clics.
Lire le guide →DocsNettoyage des commentaires FB
Modération planifiée des commentaires spam sous vos pubs Facebook : dry-run, stop words, regexes admin, whitelist, journal et restauration en un clic.
Lire le guide →DocsSources de trafic et réseaux d'affiliation
Les deux annuaires du funnel : templates de sources avec paramètres et macros, postback vers la source, réseaux d'affiliation et paramètres d'offre.
Lire le guide →DocsRapports, logs et métriques
Dashboard, liste des campagnes, rapport à dimensions, tendances et cohortes, journal du trafic, carte du clic et le détail du calcul de chaque métrique.
Lire le guide →DocsDomaines et SSL
Ajouter des domaines, réglages par domaine, certificats Let's Encrypt et Cloudflare, registrars connectés et surveillance Backorder.
Lire le guide →DocsCloudflare
Connecter Cloudflare via l'API : parking DNS automatique, proxy orange, modes SSL de zone, import des zones et réécriture des enregistrements A.
Lire le guide →DocsAdministration
Utilisateurs, rôles et permissions, clés API, réglages du tracker, bases geo, mises à jour et menu ⚙ : archive, statuts, logs et extension Ads Manager.
Lire le guide →DocsBot Telegram
Statistiques, conversions et digest quotidien dans Telegram : connexion par token, webhook ou polling, commandes, notifications et alertes vers les chaînes.
Lire le guide →DocsMCP : un assistant IA dans le tracker
Connecter Claude Desktop ou tout client MCP à Orbitra via le serveur MCP : clés API, options de connexion et les 41 tools disponibles.
Lire le guide →