Agents IA - MCP, REST et OpenAPI

Connectez Claude Desktop, Claude Code, claude.ai, ChatGPT ou votre propre agent à Arachnide - trois portes, 25 outils, le prompt système suggéré et le modèle de sécurité.

Trois portes, un seul jeu d’outils

Depuis la 3.13, Arachnide est conçu pour être piloté par un agent IA : le vôtre, ou tout assistant qui parle MCP (Claude) ou OpenAPI (Actions ChatGPT, LangChain, n8n, Make…). L’agent lit l’audit que vous avez ouvert, lance des crawls visibles en direct dans l’application, explore des pages, récupère le plan d’action priorisé et le rapport de préparation GEO, et, avec votre accord, corrige le site via les connecteurs CMS. Tout tourne sur votre machine ou votre serveur ; rien n’est envoyé à un tiers, sauf ce que reçoit le modèle de votre propre agent.

Le jeton est créé au premier démarrage d’Arachnide et vit dans ~/.arachnide/agent.json (mode 0600). Lisez-le, copiez-le ou renouvelez-le dans Réglages → Agents IA ; sur un serveur, définissez plutôt ARACHNIDE_AGENT_TOKEN. Le même écran montre les derniers appels reçus des agents, les URL MCP et OpenAPI, un champ d’URL publique pour les tunnels et des extraits prêts à coller. Les outils sont identiques sur les trois portes : ils viennent d’un seul registre, src/agent/tools.mjs. crawl_id: "current" désigne toujours le crawl ouvert dans l’application Arachnide.

Claude Desktop et Claude Code (local, stdio)

claude mcp add arachnide -- node /chemin/vers/arachnide-seo-spider/src/mcp.mjs
# avec un secret pour un site :
claude mcp add arachnide -e ARACHNIDE_WP_APP_PASSWORD="xxxx xxxx xxxx xxxx" -- node /chemin/vers/arachnide-seo-spider/src/mcp.mjs

Claude Desktop : Settings → Developer → Edit Config, puis ajoutez le serveur et redémarrez Claude Desktop :

{
  "mcpServers": {
    "arachnide": {
      "command": "node",
      "args": ["C:\\Users\\vous\\arachnide-seo-spider\\src\\mcp.mjs"],
      "env": { "ARACHNIDE_WP_APP_PASSWORD": "xxxx xxxx xxxx xxxx", "ARACHNIDE_LANG": "fr" }
    }
  }
}

Puis demandez simplement : « Audite www.mon-site.fr et corrige les titres, descriptions et textes alternatifs manquants des pages les plus importantes. », ou utilisez le prompt optimize_site. Avec l’application lancée, vous pouvez aussi utiliser la porte HTTP depuis Claude Desktop : Réglages → Agents IA → Copier la configuration Claude Desktop donne { "mcpServers": { "arachnide": { "url": "http://127.0.0.1:4000/mcp", "headers": { "Authorization": "Bearer ara_…" } } } }.

Variables d’environnement du serveur MCP : ARACHNIDE_LANG (libellés : en, fr, de, es, it, pt), ARACHNIDE_HOME (configuration et journal, par défaut ~/.arachnide), ARACHNIDE_CONFIG (fichier des sites), ARACHNIDE_CRAWLS (dossier des crawls, partagé avec l’application web par défaut).

Connecteur personnalisé claude.ai et agents hébergés (HTTP)

claude.ai n’atteint que des serveurs sur l’internet public en HTTPS. Exposez l’application :

npm start                                        # Arachnide sur http://localhost:4000
cloudflared tunnel --url http://localhost:4000   # ou : ngrok http 4000 · tailscale funnel 4000

Dans Arachnide → Réglages → Agents IA, collez l’URL publique (par exemple https://xyz.trycloudflare.com). Dans claude.ai → Paramètres → Connecteurs → Ajouter un connecteur personnalisé : URL https://xyz.trycloudflare.com/mcp, et le jeton comme bearer token. Le jeton est votre clé : ne le partagez jamais. Pour un agent hébergé construit avec le Claude Agent SDK ou l’API Messages, ajoutez le serveur comme serveur MCP avec la même URL et l’en-tête Authorization, ou appelez directement la porte REST.

ChatGPT (Actions GPT) et agents OpenAI

Dans le GPT builder → Actions → Import from URL : https://<votre-hôte>/openapi.json. Authentification : API Key, type Bearer, collez le jeton. Chaque outil devient une action (arachnide_get_summary, arachnide_action_plan…) ; les outils en lecture sont marqués non conséquents, les outils d’écriture (appliquer, annuler, configurer) demandent confirmation. Avec l’API OpenAI Agents / Responses, pointez un outil MCP hébergé sur https://<votre-hôte>/mcp avec l’en-tête bearer, ou enveloppez les points d’entrée REST comme fonctions depuis la spécification OpenAPI.

Les 25 outils

Chaque outil de lecture (arachnide_get_summary, arachnide_list_issues, arachnide_get_issue, arachnide_action_plan, arachnide_search_pages, arachnide_geo_readiness) accepte segment. Google Analytics 4 : passez ga4_key_file (et ga4_property) ou ga4_csv aux outils de crawl. Mode liste (3.21) : mode: "list" avec urls ou sitemap_url, max_pages jusqu’à 200 000. GET /api/agent/tools renvoie la même liste avec le JSON Schema de chaque entrée.

Préparation GEO

arachnide_geo_readiness note un crawl sur 100 pour la visibilité dans les réponses des IA : crawlers IA autorisés ou bloqués dans robots.txt (GPTBot, OAI-SearchBot, ClaudeBot, PerplexityBot, Google-Extended…), llms.txt, couverture des données structurées et types orientés réponse, profondeur du contenu et pages pauvres, doublons, hygiène des titles / descriptions / H1 / Open Graph, avec un score par partie et des recommandations ordonnées. Les mêmes signaux apparaissent dans l’onglet Robots, IA & sitemaps de l’application.

Prompt système suggéré

Collez ceci dans le prompt système de votre agent (instructions de projet Claude, instructions GPT, system de l’Agent SDK) :

Tu es consultant SEO et GEO (optimisation pour les moteurs génératifs). Tu travailles avec Arachnide SEO Spider via ses outils.
- Quand l’utilisateur parle de « l’audit », « le site » ou « le crawl », utilise crawl_id "current" : c’est ce qu’il voit dans l’application Arachnide. Appelle arachnide_list_crawls en cas de doute.
- Commence toute analyse par arachnide_get_summary, puis arachnide_action_plan (quoi faire en premier) et arachnide_geo_readiness (visibilité dans les réponses des IA). Explique simplement, cite les chiffres, n’invente jamais une donnée absente des résultats.
- Pour explorer : arachnide_search_pages (tri par Link Score) et arachnide_get_page ; pour rédiger, lis d’abord la vraie page avec arachnide_fetch_page.
- Nouveau crawl : arachnide_start_crawl, puis arachnide_crawl_status toutes les 15-30 s ; l’utilisateur peut le suivre dans l’application.
- Modifications du site : arachnide_suggest_fixes → rédige toi-même les valeurs (langue du site, naturel, unique, dans les limites en pixels) → arachnide_preview_changes → montre un tableau avant/après → attends un « oui » explicite → arachnide_apply_changes → arachnide_verify_changes. Petits lots (10-30), pages les plus importantes d’abord. Chaque lot s’annule avec arachnide_rollback_changes.
- Ne demande jamais de coller un mot de passe ou une clé API dans le chat : configure les sites avec des références "env:VARIABLE".

Connecter un site (serveur MCP)

Les sites vivent dans ~/.arachnide/sites.json. L’agent crée l’entrée avec arachnide_configure_site ; les secrets ne passent jamais par le chat : le fichier stocke env:VARIABLE et la valeur vient de l’environnement du serveur MCP. Champs que l’agent peut modifier : title SEO, meta description, H1, canonical, noindex, texte alternatif des images, redirections 301.

{
  "sites": {
    "mon-blog": {
      "url": "https://www.mon-blog.fr",
      "connector": "wordpress",
      "user": "admin",
      "appPassword": "env:ARACHNIDE_WP_APP_PASSWORD",
      "policy": { "allowedFields": ["seo_title", "meta_description", "image_alt"], "maxChangesPerBatch": 30 }
    }
  }
}

Les réglages et prérequis des connecteurs sont listés dans Corriger en 1 clic.

Modèle de sécurité

• Le jeton est exigé sur /mcp et /api/agent/* ; /openapi.json est public (il ne contient aucun secret) pour que les GPT builders puissent l’importer. /api/agent/settings (jeton, journal) ne répond qu’à l’interface locale.
• Les requêtes sont limitées (240 par minute et par IP) et les 50 derniers appels sont affichés dans l’application.
• Désactivez les agents à tout moment avec l’interrupteur dans Réglages → Agents IA ; renouvelez le jeton s’il fuit.
• N’exposez Arachnide qu’en HTTPS (tunnel ou reverse proxy). Derrière un proxy, transmettez X-Forwarded-Proto / X-Forwarded-Host ou définissez l’URL publique dans l’application (ARACHNIDE_PUBLIC_URL).
• Les outils d’écriture suivent la même politique que le serveur MCP : champs autorisés par site, taille des lots, mode lecture seule, journal et annulation. Les outils d’application et d’annulation sont marqués destructifs, si bien que Claude Code et Claude Desktop demandent la permission. Seul l’hôte du site est accepté.

Exemples

# résumé de l’audit ouvert dans l’application
curl -X POST https://<hôte>/api/agent/arachnide_get_summary -H "Authorization: Bearer ara_…" -H "Content-Type: application/json" -d '{}'
# les 10 pages au Link Score le plus élevé sous /blog/
curl -X POST https://<hôte>/api/agent/arachnide_search_pages -H "Authorization: Bearer ara_…" -H "Content-Type: application/json" -d '{"folder":"/blog/","limit":10}'
# préparation GEO d’un crawl enregistré
curl -X POST https://<hôte>/api/agent/arachnide_geo_readiness -H "Authorization: Bearer ara_…" -H "Content-Type: application/json" -d '{"crawl_id":"www.example.com_2026-10-19T09-00-00"}'

Les erreurs sont en JSON : 400 arguments invalides (avec le chemin du champ), 401 jeton manquant ou invalide, 404 outil, crawl, problème ou page inconnu, 409 un crawl est déjà en cours.