Agenti IA - MCP, REST e OpenAPI

Collega Claude Desktop, Claude Code, claude.ai, ChatGPT o il tuo agente ad Arachnide - tre accessi, 25 strumenti, il prompt di sistema suggerito e il modello di sicurezza.

Tre accessi, un solo set di strumenti

Dalla 3.13, Arachnide è progettato per essere guidato da un agente IA: il tuo, o qualsiasi assistente che parli MCP (Claude) o OpenAPI (Actions di ChatGPT, LangChain, n8n, Make…). L’agente legge l’audit che hai aperto, avvia crawl che compaiono in diretta nell’app, esplora le pagine, ottiene il piano d’azione con priorità e il report sulla prontezza GEO, e, con la tua approvazione, corregge il sito tramite i connettori CMS. Tutto gira sulla tua macchina o sul tuo server; nulla viene inviato a terzi, tranne ciò che riceve il modello del tuo agente.

Questa tabella è generata dal repository ed è disponibile solo in inglese.

Il token viene creato al primo avvio di Arachnide e vive in ~/.arachnide/agent.json (modalità 0600). Leggilo, copialo o rinnovalo in Impostazioni → Agenti IA; su un server, imposta invece ARACHNIDE_AGENT_TOKEN. La stessa schermata mostra le ultime chiamate ricevute dagli agenti, gli URL MCP e OpenAPI, un campo per l’URL pubblico per i tunnel e snippet pronti da incollare. Gli strumenti sono identici sui tre accessi: provengono da un unico registro, src/agent/tools.mjs. crawl_id: "current" indica sempre il crawl aperto nell’app Arachnide.

Claude Desktop e Claude Code (locale, stdio)

claude mcp add arachnide -- node /path/to/arachnide-seo-spider/src/mcp.mjs
# con un segreto per un sito:
claude mcp add arachnide -e ARACHNIDE_WP_APP_PASSWORD="xxxx xxxx xxxx xxxx" -- node /path/to/arachnide-seo-spider/src/mcp.mjs

Claude Desktop: Settings → Developer → Edit Config, poi aggiungi il server e riavvia Claude Desktop:

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

Poi chiedi semplicemente: «Fai l’audit di www.mio-sito.it e correggi i title, le description e i testi alternativi mancanti delle pagine più importanti.», oppure usa il prompt optimize_site. Con l’app in esecuzione puoi usare anche l’accesso HTTP da Claude Desktop: Impostazioni → Agenti IA → Copia la configurazione di Claude Desktop fornisce { "mcpServers": { "arachnide": { "url": "http://127.0.0.1:4000/mcp", "headers": { "Authorization": "Bearer ara_…" } } } }.

Variabili d’ambiente del server MCP: ARACHNIDE_LANG (etichette: en, fr, de, es, it, pt), ARACHNIDE_HOME (configurazione e diario, predefinito ~/.arachnide), ARACHNIDE_CONFIG (file dei siti), ARACHNIDE_CRAWLS (cartella dei crawl, condivisa con l’app web per impostazione predefinita).

Connettore personalizzato claude.ai e agenti ospitati (HTTP)

claude.ai raggiunge solo i server su internet pubblico tramite HTTPS. Esponi l’app:

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

In Arachnide → Impostazioni → Agenti IA, incolla l’URL pubblico (per esempio https://xyz.trycloudflare.com). In claude.ai → Settings → Connectors → Add custom connector: URL https://xyz.trycloudflare.com/mcp, e il token come bearer token. Il token è la tua chiave: non condividerlo mai. Per un agente ospitato costruito con il Claude Agent SDK o la Messages API, aggiungi il server come server MCP con lo stesso URL e lo stesso header Authorization, oppure chiama direttamente l’accesso REST.

ChatGPT (GPT Actions) e agenti OpenAI

Nel builder del GPT → Actions → Import from URL: https://<your-host>/openapi.json. Autenticazione: API Key, tipo Bearer, incolla il token. Ogni strumento diventa un’action (arachnide_get_summary, arachnide_action_plan…); gli strumenti di sola lettura sono contrassegnati come non consequenziali, gli strumenti di scrittura (apply, rollback, configure) chiedono conferma. Con l’API Agents / Responses di OpenAI, punta uno strumento MCP ospitato a https://<your-host>/mcp con l’header bearer, oppure incapsula gli endpoint REST come funzioni a partire dalla specifica OpenAPI.

I 25 strumenti

Questa tabella è generata dal repository ed è disponibile solo in inglese.

Ogni strumento di lettura (arachnide_get_summary, arachnide_list_issues, arachnide_get_issue, arachnide_action_plan, arachnide_search_pages, arachnide_geo_readiness) accetta segment. Google Analytics 4: passa ga4_key_file (e ga4_property) oppure ga4_csv agli strumenti di crawl. Modalità elenco (3.21): mode: "list" con urls o sitemap_url, max_pages fino a 200 000. GET /api/agent/tools restituisce lo stesso elenco con il JSON Schema di ogni input.

Prontezza GEO

arachnide_geo_readiness assegna a un crawl un punteggio su 100 per la visibilità nelle risposte delle IA: crawler IA consentiti o bloccati nel robots.txt (GPTBot, OAI-SearchBot, ClaudeBot, PerplexityBot, Google-Extended…), llms.txt, copertura dei dati strutturati e tipi orientati alle risposte, profondità dei contenuti e pagine con poco contenuto, duplicati, igiene di title / description / H1 / Open Graph, con un punteggio per parte e raccomandazioni ordinate. Gli stessi segnali compaiono nella scheda Robots, IA & sitemap dell’app.

Prompt di sistema suggerito

Incolla questo nel prompt di sistema del tuo agente (istruzioni del progetto Claude, istruzioni del GPT, system dell’Agent SDK):

You are an SEO and GEO (generative engine optimisation) consultant. You work with Arachnide SEO Spider through its tools.
- When the user mentions "the audit", "the site" or "the crawl", use crawl_id "current": it is what they see in the Arachnide app. Call arachnide_list_crawls if unsure.
- Start every analysis with arachnide_get_summary, then arachnide_action_plan (what to do first) and arachnide_geo_readiness (visibility in AI answers). Explain in plain language, cite numbers, never invent data that is not in the tool results.
- To explore, use arachnide_search_pages (sorted by Link Score) and arachnide_get_page; to write content, read the real page with arachnide_fetch_page first.
- A new crawl: arachnide_start_crawl, then poll arachnide_crawl_status every 15-30 s; the user can watch it in the app.
- Changes to the live site: arachnide_suggest_fixes → write the values yourself (same language as the site, natural, unique, within pixel limits) → arachnide_preview_changes → show a before/after table → wait for an explicit "yes" → arachnide_apply_changes → arachnide_verify_changes. Small batches (10-30), most important pages first. Every batch can be undone with arachnide_rollback_changes.
- Never ask the user to paste passwords or API keys in the chat: configure sites with "env:VARIABLE" references.

Collegare un sito (server MCP)

I siti vivono in ~/.arachnide/sites.json. L’agente crea la voce con arachnide_configure_site; i segreti non passano mai per la chat: il file memorizza env:VARIABLE e il valore proviene dall’ambiente del server MCP. Campi che l’agente può modificare: title SEO, meta description, H1, canonical, noindex, testo alternativo delle immagini, reindirizzamenti 301.

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

Le impostazioni e i prerequisiti dei connettori sono elencati in Correggi in 1 clic.

Modello di sicurezza

• Il token è obbligatorio su /mcp e /api/agent/*; /openapi.json è pubblico (non contiene segreti) perché i builder dei GPT possano importarlo. /api/agent/settings (token, registro) risponde solo all’interfaccia locale.
• Le richieste sono limitate (240 al minuto per IP) e le ultime 50 chiamate sono mostrate nell’app.
• Disattiva gli agenti in qualsiasi momento con l’interruttore in Impostazioni → Agenti IA; rinnova il token se viene compromesso.
• Esponi Arachnide solo tramite HTTPS (tunnel o reverse proxy). Dietro un proxy, inoltra X-Forwarded-Proto / X-Forwarded-Host oppure imposta l’URL pubblico nell’app (ARACHNIDE_PUBLIC_URL).
• Gli strumenti di scrittura passano per le stesse regole del server MCP: campi consentiti per sito, dimensione dei lotti, modalità di sola lettura, diario e ripristino. Gli strumenti di applicazione e ripristino sono contrassegnati come destructive, così Claude Code e Claude Desktop chiedono il permesso. Viene accettato solo l’host del sito stesso.

Esempi

# riepilogo dell’audit aperto nell’app
curl -X POST https://<host>/api/agent/arachnide_get_summary -H "Authorization: Bearer ara_…" -H "Content-Type: application/json" -d '{}'
# le 10 pagine con il Link Score più alto sotto /blog/
curl -X POST https://<host>/api/agent/arachnide_search_pages -H "Authorization: Bearer ara_…" -H "Content-Type: application/json" -d '{"folder":"/blog/","limit":10}'
# prontezza GEO di un crawl salvato
curl -X POST https://<host>/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"}'

Gli errori sono in JSON: 400 argomenti non validi (con il percorso del campo), 401 token mancante o non valido, 404 strumento, crawl, problema o pagina sconosciuti, 409 un crawl è già in esecuzione.