Agentes de IA - MCP, REST y OpenAPI

Conecta Claude Desktop, Claude Code, claude.ai, ChatGPT o tu propio agente a Arachnide - tres vías, 25 herramientas, las instrucciones de sistema sugeridas y el modelo de seguridad.

Tres vías, un solo conjunto de herramientas

Desde la 3.13, Arachnide está diseñado para que lo dirija un agente de IA: el tuyo, o cualquier asistente que hable MCP (Claude) u OpenAPI (Actions de ChatGPT, LangChain, n8n, Make…). El agente lee la auditoría que tienes abierta, lanza rastreos que aparecen en directo en la aplicación, explora páginas, obtiene el plan de acción priorizado y el informe de preparación GEO y, con tu aprobación, corrige el sitio a través de los conectores CMS. Todo se ejecuta en tu equipo o en tu servidor; no se envía nada a terceros, salvo lo que recibe el modelo de tu propio agente.

Esta tabla se genera desde el repositorio y solo está disponible en inglés.

El token se crea la primera vez que arranca Arachnide y vive en ~/.arachnide/agent.json (modo 0600). Léelo, cópialo o renuévalo en Ajustes → Agentes de IA; en un servidor, define ARACHNIDE_AGENT_TOKEN en su lugar. La misma pantalla muestra las últimas llamadas recibidas de los agentes, las URL MCP y OpenAPI, un campo de URL pública para los túneles y fragmentos listos para pegar. Las herramientas son idénticas en las tres vías: salen de un único registro, src/agent/tools.mjs. crawl_id: "current" significa siempre el rastreo abierto en la aplicación Arachnide.

Claude Desktop y Claude Code (local, stdio)

claude mcp add arachnide -- node /path/to/arachnide-seo-spider/src/mcp.mjs
# con un secreto para un sitio:
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, luego añade el servidor y reinicia 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": "es" }
    }
  }
}

Después pídeselo sin más: «Audita www.mi-sitio.com y corrige los títulos, las descripciones y los textos alternativos que faltan en las páginas más importantes.», o usa el prompt optimize_site. Con la aplicación en marcha también puedes usar la vía HTTP desde Claude Desktop: Ajustes → Agentes de IA → Copiar la configuración de Claude Desktop da { "mcpServers": { "arachnide": { "url": "http://127.0.0.1:4000/mcp", "headers": { "Authorization": "Bearer ara_…" } } } }.

Variables de entorno del servidor MCP: ARACHNIDE_LANG (etiquetas: en, fr, de, es, it, pt), ARACHNIDE_HOME (configuración y diario, por defecto ~/.arachnide), ARACHNIDE_CONFIG (archivo de sitios), ARACHNIDE_CRAWLS (carpeta de rastreos, compartida con la aplicación web por defecto).

Conector personalizado de claude.ai y agentes alojados (HTTP)

claude.ai solo llega a servidores en la internet pública por HTTPS. Expón la aplicación:

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

En Arachnide → Ajustes → Agentes de IA, pega la URL pública (por ejemplo https://xyz.trycloudflare.com). En claude.ai → Ajustes → Conectores → Añadir conector personalizado: URL https://xyz.trycloudflare.com/mcp, y el token como bearer token. El token es tu llave: no lo compartas nunca. Para un agente alojado construido con el Claude Agent SDK o la API Messages, añade el servidor como servidor MCP con la misma URL y la cabecera Authorization, o llama directamente a la vía REST.

ChatGPT (GPT Actions) y agentes de OpenAI

En el GPT builder → Actions → Import from URL: https://<tu-host>/openapi.json. Autenticación: API Key, tipo Bearer, pega el token. Cada herramienta se convierte en una acción (arachnide_get_summary, arachnide_action_plan…); las herramientas de solo lectura se marcan como no consecuentes, las herramientas de escritura (aplicar, revertir, configurar) piden confirmación. Con la API Agents / Responses de OpenAI, apunta una herramienta MCP alojada a https://<tu-host>/mcp con la cabecera bearer, o envuelve los endpoints REST como funciones a partir de la especificación OpenAPI.

Las 25 herramientas

Esta tabla se genera desde el repositorio y solo está disponible en inglés.

Todas las herramientas de lectura (arachnide_get_summary, arachnide_list_issues, arachnide_get_issue, arachnide_action_plan, arachnide_search_pages, arachnide_geo_readiness) aceptan segment. Google Analytics 4: pasa ga4_key_file (y ga4_property) o ga4_csv a las herramientas de rastreo. Modo lista (3.21): mode: "list" con urls o sitemap_url, max_pages hasta 200 000. GET /api/agent/tools devuelve la misma lista con el JSON Schema de cada entrada.

Preparación GEO

arachnide_geo_readiness puntúa un rastreo sobre 100 para la visibilidad en las respuestas de las IA: rastreadores de IA permitidos o bloqueados en robots.txt (GPTBot, OAI-SearchBot, ClaudeBot, PerplexityBot, Google-Extended…), llms.txt, cobertura de datos estructurados y tipos orientados a respuestas, profundidad del contenido y páginas con contenido escaso, duplicados, higiene de titles / descriptions / H1 / Open Graph, con una puntuación por apartado y recomendaciones ordenadas. Las mismas señales aparecen en la pestaña Robots, IA y sitemaps de la aplicación.

Instrucciones de sistema sugeridas

Pega esto en las instrucciones de sistema de tu agente (instrucciones de proyecto de Claude, instrucciones del GPT, system del 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.

Conectar un sitio (servidor MCP)

Los sitios viven en ~/.arachnide/sites.json. El agente crea la entrada con arachnide_configure_site; los secretos nunca pasan por el chat: el archivo guarda env:VARIABLE y el valor viene del entorno del servidor MCP. Campos que el agente puede cambiar: title SEO, meta description, H1, canonical, noindex, texto alternativo de las imágenes, redirecciones 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 }
    }
  }
}

Los ajustes y requisitos de los conectores están listados en Corregir en 1 clic.

Modelo de seguridad

• El token es obligatorio en /mcp y /api/agent/*; /openapi.json es público (no contiene ningún secreto) para que los GPT builders puedan importarlo. /api/agent/settings (token, registro) solo responde a la interfaz local.
• Las peticiones están limitadas (240 por minuto y por IP) y las últimas 50 llamadas se muestran en la aplicación.
• Desactiva los agentes en cualquier momento con el interruptor de Ajustes → Agentes de IA; renueva el token si se filtra.
• Expón Arachnide solo por HTTPS (túnel o proxy inverso). Detrás de un proxy, reenvía X-Forwarded-Proto / X-Forwarded-Host o define la URL pública en la aplicación (ARACHNIDE_PUBLIC_URL).
• Las herramientas de escritura pasan por la misma política que el servidor MCP: campos permitidos por sitio, tamaño de lote, modo de solo lectura, diario y reversión. Las herramientas de aplicación y reversión se marcan como destructivas, de modo que Claude Code y Claude Desktop piden permiso. Solo se acepta el host del propio sitio.

Ejemplos

# resumen de la auditoría abierta en la aplicación
curl -X POST https://<host>/api/agent/arachnide_get_summary -H "Authorization: Bearer ara_…" -H "Content-Type: application/json" -d '{}'
# las 10 páginas con mayor Link Score bajo /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}'
# preparación GEO de un rastreo guardado
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"}'

Los errores son JSON: 400 argumentos no válidos (con la ruta del campo), 401 token ausente o no válido, 404 herramienta, rastreo, problema o página desconocidos, 409 ya hay un rastreo en curso.