Index Agentica

npx add-mcp 'https://mcp.indexagentica.com/mcp'

indexagentica-mcp

Servidor MCP remoto de solo lectura (HTTP Streamable) y API de búsqueda REST para Index Agentica, el directorio orientado a agentes de habilidades, harnesses, servidores MCP, herramientas, protocolos y APIs, además de sus guías extensas, comparativas, stacks y Agent Skills descargables. Se ejecuta en Cloudflare Workers (plan gratuito), sin estado, sin Durable Objects, sin autenticación, CORS abierto.

Instalación

Servidor remoto: sin instalación, sin clave API. HTTP Streamable en https://mcp.indexagentica.com/mcp (en vivo).

claude mcp add --transport http indexagentica https://mcp.indexagentica.com/mcp

Otros clientes: añade la URL como servidor HTTP Streamable sin autenticación (ver llms-install.md). El mismo Worker también responde en https://indexagentica-mcp.indexagentica.workers.dev/mcp (ver DEPLOY.md).

Endpoints

Método	Ruta	Qué hace
POST	/mcp	Endpoint MCP HTTP Streamable (JSON-RPC 2.0, respuestas JSON)
GET/DELETE	/mcp	405 (sin flujo SSE independiente, sin sesiones)
GET	/	Autodescripción JSON con enlaces al endpoint MCP, REST, llms.txt, documentación
GET	/search?q=&type=&category=&tags=a,b&limit=	Búsqueda clasificada sobre entradas y contenido extenso (type: entry, guide, comparison, stack, skill o all (predeterminado); category se aplica a entradas; límite 1-50, predeterminado 10; las etiquetas se combinan con AND)
GET	/entries/<id> (o <id>.json)	Una entrada completa; 404 incluye suggestions
GET	/entries	Todos los ids
GET	/content/<type>/<id> (o <id>.json)	Una guía, comparativa, stack o habilidad: metadatos + markdown (?include_html=1 añade HTML); 404 incluye suggestions
GET	/content?type=	Elementos extensos publicados (metadatos)
GET	/categories	Categorías con recuentos
GET	/openapi.json	OpenAPI 3.1 para la API REST
GET	/.well-known/mcp/server-card.json	Tarjeta de servidor estática (respaldo de escaneo Smithery): serverInfo, authentication: {required: false}, el mismo tools que tools/list, resources/prompts vacíos
GET	/stats	Estadísticas de uso públicas (JSON): visitas de páginas del sitio, clics salientes, descargas de habilidades, llamadas a herramientas MCP por herramienta, solicitudes REST, división agente/humano; últimas 24 h, últimos 7 días, todo el tiempo desde las marcas de tiempo since. Caché de 10 min. Ver Estadísticas de uso
GET	/v1/usage	Alias de /stats (usado por el sitio; menos probable de ser bloqueado por filtros de contenido)
POST	/v1/e	Alias de /hit (usado por el sitio)
POST	/hit	Baliza de uso del sitio desde el script inline de indexagentica.com (verificada por origen, validada estrictamente, 204). Ver Balizas del sitio
GET	/health	Liveness (sin límite de tasa)

Los errores siempre son JSON: {"error":{"status":400,"code":"bad_request","message":"..."}} (códigos: bad_request, not_found, method_not_allowed, rate_limited, upstream_error).

Herramientas MCP

Herramienta	Entrada	Salida (structuredContent)
search	query (cadena), type? (entry|guide|comparison|stack|skill|all, predeterminado todos), category? (slug; solo entradas), tags? (cadena[], todas deben coincidir), limit? (1-50)	{query, type, category?, tags, limit, total, results[]}; cada resultado tiene type, id, name, summary, url, tags, score, links, además de category (entradas) o author, last_verified, entries (contenido extenso)
get_entry	id (kebab-case)	{entry} (la entrada completa según el esquema de entrada + links + referencias cruzadas longform)
get_content	type (guide|comparison|stack|skill), id, include_html?	{content}: front matter, metadatos, markdown (enlaces de esquema resueltos a URLs absolutas), links; las comparativas añaden comparison (criterios, tabla, veredicto), los stacks añaden stack (caso de uso, componentes), las habilidades añaden skill_md (SKILL.md completo) y links.zip / links.skill_md
list_categories	ninguno	{total, generated, categories[{slug,name,description,count,html,json}]}

Cada herramienta tiene un inputSchema de JSON-Schema, un outputSchema, anotaciones readOnlyHint, y devuelve tanto structuredContent como el mismo JSON como bloque de contenido text. Los argumentos incorrectos y los ids desconocidos se devuelven como resultados de herramienta isError: true (para que el modelo pueda corregirse); un nombre de herramienta desconocido es JSON-RPC -32602.

Puntuación: por palabra de consulta, coincidencia exacta de id/nombre 12, segmento de id 6, subcadena de nombre 5, etiqueta exacta 4 (etiqueta parcial 2), resumen 2, categoría 1.5, descripción 1; +8 si la frase completa está en el nombre; multiplicado por la fracción de palabras coincidentes.

Soporte de protocolo (doble era, sin estado)

• 2026-07-28 (especificación actual, "moderna"): sin handshake. Cada POST lleva _meta["io.modelcontextprotocol/protocolVersion"] y los encabezados MCP-Protocol-Version, Mcp-Method (y para tools/call, Mcp-Name, se admite el centinela base64). El servidor valida los encabezados contra el cuerpo (-32020 HeaderMismatch), rechaza versiones desconocidas con -32022 + lista supported, implementa server/discover, devuelve resultType: "complete", serverInfo en el resultado _meta, y sugerencias de caché ttlMs/cacheScope en tools/list y server/discover. Métodos desconocidos -> HTTP 404 + -32601.
• 2025-11-25 / 2025-06-18 / 2025-03-26 ("legado"): se responde initialize (versión negociada, con respaldo a 2025-11-25), notifications/initialized -> 202, ping, tools/list, tools/call; se aceptan lotes de 2025-03-26. Nunca se emite Mcp-Session-Id, por lo que cada solicitud es independiente y cualquier instancia de Worker puede atenderla.
• Las respuestas siempre son application/json (nunca SSE). Origin se verifica contra ALLOWED_ORIGINS (predeterminado * porque los datos son públicos y de solo lectura).

Referencias de especificación: Streamable HTTP 2026-07-28, Versionado / doble era, server/discover.

Datos y caché

La fuente de verdad es el sitio estático publicado: GET https://indexagentica.com/api/index.json (todas las entradas + categorías) y GET /api/longform.json (metadatos de contenido extenso), obtenidos juntos; si el índice de contenido extenso no se puede cargar, las entradas siguen funcionando. get_content obtiene /api/longform/<route>/<id>.json bajo demanda (misma caché), siempre desde DATA_BASE_URL. El Worker mantiene los índices en memoria de la instancia durante CACHE_TTL_SECONDS (600 s), también los almacena en la API de caché de Cloudflare (efectiva en un dominio personalizado; sin efecto en workers.dev), combina las actualizaciones concurrentes y sirve la copia obsoleta si la obtención ascendente falla. Las nuevas categorías añadidas por la compilación del sitio aparecen automáticamente. No se escribe nada en ningún lugar.

Registro de uso (Workers Analytics Engine)

Cada solicitud (excepto OPTIONS, /health, /robots.txt, /favicon.ico, /hit, /stats) escribe un punto de datos en el conjunto de datos de Analytics Engine indexagentica_mcp (enlace ANALYTICS en wrangler.toml), para poder contar el uso de agentes por herramienta y cliente. Si el enlace falta (pruebas locales, entorno ratelimit-test), el registro es una operación sin efecto, y una escritura fallida nunca afecta la respuesta. Workers Free incluye 100,000 puntos de datos escritos por día (precios); los datos se conservan durante 3 meses (límites).

Columna	Campo	Notas
index1	<route>:<tool or method or endpoint>	p. ej. mcp:search, rest:get_entry
blob1	ruta	mcp o rest
blob2	endpoint	normalizado: /mcp, /search, /entries/{id}, /content/{type}/{id}, ..., other
blob3	método JSON-RPC	initialize, tools/call, batch, ... (solo MCP)
blob4	herramienta	nombre de herramienta MCP, o el equivalente REST (search, get_entry, get_content, list_content, list_categories)
blob5, blob6	nombre del cliente, versión	de initialize clientInfo o 2026-07-28 _meta["io.modelcontextprotocol/clientInfo"]; truncado a 64/32 caracteres
blob7	User-Agent	truncado a 128 caracteres
blob8, blob9	versión del protocolo, era	modern / legacy
blob10	resultado	ok, error (HTTP ≥ 400, error JSON-RPC o resultado de herramienta isError), rate_limited
blob11	detalle	código de error JSON-RPC, tool_error o estado HTTP
blob12, blob13	país, colo	de request.cf
blob14, blob15, blob16	filtro de tipo, filtro de categoría, id objetivo	solo valores kebab-case (slugs/ids del catálogo público); cualquier otra cosa se almacena como invalid
blob17	clase de UA	human (User-Agent de navegador convencional) o agent (todo lo demás: clientes MCP, SDKs, curl, rastreadores, navegadores sin interfaz); ver src/ua.js. Añadido 2026-10-03; las filas anteriores se clasifican desde blob7 en el momento de la consulta
blob18	tráfico	internal (nuestras propias pruebas/agentes, ver Tráfico interno) o outside; vacío antes de 2026-10-12
blob19	regla interna	header, ua o ip (vacío para tráfico externo)
double1	estado HTTP
double2	latencia (ms)	tiempo real dentro del Worker (los relojes de Workers avanzan en E/S)
double3	ASN	de request.cf.asn (red, no persona)
double4	recuento de resultados	total de búsqueda
double5, double6	longitud de consulta en caracteres, palabras

Privacidad: sin direcciones IP, sin texto de consultas de búsqueda, sin argumentos de herramientas de texto libre, sin cookies ni tokens (el servidor no tiene ninguno), y para balizas del sitio sin referrers, cadenas de consulta ni identificadores de cliente. Los clientes se identifican solo por su nombre/versión autoinformados y un User-Agent truncado. Ejemplo de consulta (API SQL): SELECT blob4 AS tool, blob5 AS client, SUM(_sample_interval) AS requests FROM indexagentica_mcp WHERE timestamp > NOW() - INTERVAL '1' DAY GROUP BY tool, client ORDER BY requests DESC.

Balizas del sitio (POST /hit)

Cada página de indexagentica.com lleva un pequeño script inline (sin cookies, sin localStorage, sin identificadores, sin código de terceros). Se omite cuando navigator.webdriver está configurado o el navegador envía Do Not Track o Global Privacy Control. Envía, con navigator.sendBeacon (como text/plain, por lo que no hay preflight CORS):

Evento	Cuerpo	Cuándo
vista de página	{"t":"pageview","p":"/entries/x402/"}	carga de página; p es la ruta canónica de la página (sin cadena de consulta, sin referrer)
clic saliente	{"t":"click","p":"/entries/x402/","id":"x402","h":"www.x402.org"}	clic en el enlace de sitio web/repositorio/documentación/fuente de una entrada en su página de entrada
descarga	{"t":"download","p":"/skills/<id>/","id":"<id>","k":"zip"|"skill_md"}	clic en un zip de habilidad o enlace SKILL.md sin procesar

El sitio publica en el alias /v1/e en mcp.indexagentica.com y recurre a la misma ruta en indexagentica-mcp.indexagentica.workers.dev si eso falla (mismo Worker, mismas comprobaciones). El Worker acepta solo Origin: https://indexagentica.com (HIT_ORIGINS), cuerpos de hasta 512 bytes, los tres tipos de eventos con exactamente sus campos, p del conjunto de páginas que el sitio publica, ids que existen en el índice publicado y hosts a los que la entrada realmente enlaza. Cualquier otra cosa recibe 400 y no se almacena. /hit tiene su propio contador de límite de tasa (mismo 120/min por IP). Los hits aceptados van al conjunto de datos separado indexagentica_hits (enlace HITS), índice hit:<event>:

Columna	Campo
blob1	evento: pageview, click, download
blob2	ruta de página
blob3	id de entrada o habilidad (clic, descarga)
blob4	host de destino (clic)
blob5	tipo de descarga: zip, skill_md
blob6	clase de UA (human / agent)
blob7	país (de request.cf)
blob8	tráfico: internal / outside (vacío antes de 2026-10-12)
blob9	regla interna: header, ua, ip
double1	1

Estadísticas de uso (GET /stats)

Agrega ambos conjuntos de datos a través de la API SQL de Analytics Engine usando el secreto CF_ANALYTICS_TOKEN (Account Analytics Read) y CF_ACCOUNT_ID. Los conteos son SUM(_sample_interval). Ventanas: last_24h, last_7d (móvil) y all_time. Debido a que Analytics Engine conserva 3 meses, un cron diario (30 0 * * *) almacena los totales de cada día UTC completado en Workers KV (STATS_KV, clave day:YYYY-MM-DD); all_time = días almacenados + una consulta en vivo desde el primer día aún no almacenado (/stats también recupera días faltantes de forma diferida). since.mcp_api (STATS_API_SINCE, primer despliegue con registro de solicitudes) y since.site_beacon (STATS_BEACON_SINCE, despliegue del beacon) etiquetan dónde comienza el conteo; nada anterior se estima o se rellena. Solo se publican los nombres de herramientas del propio servidor (cualquier otra cosa es unknown_tool). Las respuestas se almacenan en caché durante 10 minutos (Cache API + en memoria, Cache-Control: public, max-age=600). Sin el token, el endpoint responde {"status":"collecting", ...} sin números; si la API SQL falla, 503 {"status":"unavailable"}.

Cada ventana cuenta solo tráfico externo y añade: site.downloads.by_skill, site.outbound_clicks_by_entry, mcp.top_clients (nombres de clientes MCP autoinformados, en minúsculas y recortados a [a-z0-9._ -], top 10, solo nombres vistos ≥ 3 veces), top_user_agent_families (nombre de bot, browser, headless-chrome o primer token de producto; top 10, ≥ 3) y internal_excluded (lo que se dejó fuera, por regla). Los días de KV llevan una versión de resumen (v); los días de una versión anterior se recalculan mientras los datos sin procesar aún se conservan, por lo que los cambios de reglas se aplican retroactivamente. La recuperación diferida recalcula como máximo 2 días por llamada a /stats y el cron 5 por ejecución (cada día es ~7 subconsultas SQL; Workers Free permite 50).

Tráfico interno

Nuestras propias pruebas, monitores y agentes se registran pero se excluyen de /stats. Una solicitud o beacon es interno si alguna regla coincide (src/internal.js):

Regla	Coincidencia
header	X-Indexagentica-Internal: 1 (permitido en CORS; test/e2e.mjs lo envía en cada solicitud)
ua	User-Agent contiene indexagentica (nuestros clientes usan indexagentica-<agent>/1)
ip	IP del cliente dentro de un CIDR listado en el secreto opcional INTERNAL_IPS (separado por comas, IPv4/IPv6). Sin configurar: nuestro box compartido sale a través de direcciones rotativas en un rango de relay compartido, por lo que una regla de IP también eliminaría a extraños

Las filas registradas antes de que existiera la bandera (2026-10-12) se comparan retroactivamente en SQL por la firma de nuestras propias sesiones (API_RETRO / HITS_RETRO en src/stats.js): filas de API cuyo nombre de cliente MCP es e2e (nuestro suite de pruebas), o desde EE. UU. con un User-Agent de curl/node/python/headless-Chrome dentro de las ventanas documentadas de lanzamiento y verificación (2026-10-02 20:15–20:45 y 2026-10-03 04:55–05:50 UTC), y beacons del sitio desde EE. UU. entre 05:00 y 05:50 UTC el 2026-10-03. Esto es un esfuerzo máximo: las sesiones internas que parecían tráfico externo pueden contarse, y las solicitudes externas con los mismos clientes genéricos dentro de esas ventanas se excluyen.

Cómo deben llamar nuestros propios agentes al servidor:

curl -H 'X-Indexagentica-Internal: 1' -A 'indexagentica-steward/1' https://mcp.indexagentica.com/stats

Límite de velocidad

• Predeterminado: 120 solicitudes / 60 s por IP de cliente, por ubicación de Cloudflare, a través del enlace de límite de velocidad de Workers ([[ratelimits]] en wrangler.toml, GA desde septiembre de 2025; el período debe ser 10 o 60 s). Es intencionalmente aproximado (consistencia eventual, por ubicación).
• Si el enlace está ausente o falla, se usa un bucket de tokens por aislado con los mismos números (RATE_LIMIT_REQUESTS / RATE_LIMIT_PERIOD_SECONDS).
• Excederlo devuelve HTTP 429 con Retry-After; en /mcp el cuerpo es un error JSON-RPC (-32000), en otros lugares el sobre de error JSON. /health y OPTIONS no se miden. Las respuestas llevan x-ratelimit-limit / x-ratelimit-period.
• Límite del plan gratuito a tener en cuenta: Workers Free permite 100,000 solicitudes/día por cuenta y 10 ms de CPU por solicitud (límites). Una búsqueda en frío cuesta ~1-3 ms de CPU (analizando el índice de ~135 KB); las solicitudes en caliente muy por debajo de 1 ms.

Desarrollo local y pruebas

npm install
npm run dev                  # wrangler dev on http://127.0.0.1:8787 (no Cloudflare login needed)
npm test                     # unit tests + 2x wrangler dev + E2E (REST, MCP both eras, rate limit) + MCP Inspector CLI
npm run test:unit            # pure unit tests (no network)
BASE=https://<deployed-host> npm run test:e2e   # E2E against any deployment
DATA_BASE_URL=http://127.0.0.1:8089 npm test   # point the local Workers at another copy of the site

Las comprobaciones E2E de formato largo se adaptan a los datos: con elementos publicados, obtienen uno de cada tipo a través de REST y MCP; con ninguno (todos borradores), verifican los listados vacíos y las rutas no encontradas. Para ejercitar la ruta completa antes de que se publique algo, construye el sitio con borradores publicados (por ejemplo, INCLUDE_DRAFTS=1 SITE_URL=http://127.0.0.1:8089 node scripts/build.mjs en el repositorio del sitio), sirve dist/ en ese puerto y ejecuta npm test con DATA_BASE_URL configurado.

scripts/test-local.sh inicia el Worker normal en :8797 y una copia con límite bajo (--env ratelimit-test, 5 solicitudes / 10 s) en :8798, ejecuta test/e2e.mjs, luego verifica el servidor con @modelcontextprotocol/inspector --cli en la era heredada predeterminada y fijado a la era moderna (configuración protocolEra: "modern").

Comprobaciones manuales:

npx mcp-inspector --cli http://127.0.0.1:8787/mcp --transport http --method tools/list
npx mcp-inspector --cli http://127.0.0.1:8787/mcp --transport http --method tools/call \
  --tool-name search --tool-args-json '{"query":"browser automation","limit":3}'
curl -s http://127.0.0.1:8787/mcp -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_entry","arguments":{"id":"x402"}}}'

Conexión de un cliente

claude mcp add --transport http indexagentica https://mcp.indexagentica.com/mcp

Configuración JSON (por ejemplo, el .mcp.json de Claude Code; Claude Code requiere "type": "http" para servidores remotos):

{ "mcpServers": { "indexagentica": { "type": "http", "url": "https://mcp.indexagentica.com/mcp" } } }

Otros clientes usan su propio nombre para Streamable HTTP (Cline: "type": "streamableHttp"; algunos aceptan solo "url").

Configuración (wrangler.toml [vars])

Variable	Predeterminado	Significado
DATA_BASE_URL	https://indexagentica.com	De dónde se obtiene /api/index.json
CACHE_TTL_SECONDS	600	TTL en memoria / Cache API
RATE_LIMIT_REQUESTS, RATE_LIMIT_PERIOD_SECONDS	120, 60	Límite documentado + bucket de respaldo (mantener en sincronía con [ratelimits.simple])
ALLOWED_ORIGINS	*	Lista de Orígenes permitidos separada por comas para llamadores de navegador
PUBLIC_BASE_URL	origen de la solicitud	Base canónica para enlaces en GET /
CF_ACCOUNT_ID	(ninguno)	Cuenta para la API SQL de Analytics Engine (/stats)
STATS_API_SINCE, STATS_BEACON_SINCE	2026-10-02T20:21:47Z, (tiempo de despliegue)	Dónde comienza el conteo de MCP/REST y beacons del sitio (mostrado como since en /stats)
INTERNAL_IPS (secreto, opcional)	(ninguno)	CIDRs separados por comas cuyas solicitudes cuentan como tráfico interno
HIT_ORIGINS	https://indexagentica.com,https://www.indexagentica.com	Orígenes permitidos para POST /hit

Secreto: CF_ANALYTICS_TOKEN (Account Analytics Read), configurado con wrangler secret put CF_ANALYTICS_TOKEN. Enlaces: ANALYTICS y HITS (Analytics Engine), STATS_KV (KV), RATE_LIMITER; cron 30 0 * * *.

Despliegue

Consulta DEPLOY.md para las opciones de mcp.indexagentica.com y el acceso exacto a Cloudflare/GoDaddy necesario. Versión corta:

export CLOUDFLARE_ACCOUNT_ID=...   # from the Cloudflare dashboard
export CLOUDFLARE_API_TOKEN=...    # custom token, permissions in DEPLOY.md
npm run deploy:dry                 # build only
npm run deploy                     # -> https://mcp.indexagentica.com (custom domain)
                                   #    + https://indexagentica-mcp.indexagentica.workers.dev
BASE=https://mcp.indexagentica.com npm run test:e2e

Estructura

src/index.js      router, CORS, JSON errors, REST endpoints, rate-limit gate
src/mcp.js        stateless dual-era MCP JSON-RPC handler
src/tools.js      tool definitions (schemas) + implementations shared with REST
src/search.js     scoring / filtering
src/data.js       fetch + cache of /api/index.json
src/ratelimit.js  Workers rate limiting binding + in-isolate fallback
src/openapi.js    OpenAPI document for the REST API
src/analytics.js  per-request usage logging to Workers Analytics Engine (no-op without the binding)
src/ua.js         human (browser) vs agent User-Agent classification
src/hits.js       POST /hit: site beacon validation + logging (dataset indexagentica_hits)
src/stats.js      GET /stats: Analytics Engine SQL aggregation, KV daily rollup (cron), caching
src/internal.js   internal-traffic rules (header, UA, optional IP ranges)
test/             unit tests, E2E script, Inspector config
docs/             proposed copy for llms.txt, /agents and the directory listing

Licencia: código MIT; contenido del directorio CC BY 4.0.

Metadatos del registro

• server.json: entrada oficial del Registro MCP (com.indexagentica/mcp, esquema 2025-12-11), validada con mcp-publisher validate. La publicación usa autenticación de dominio HTTP contra https://indexagentica.com/.well-known/mcp-registry-auth; es un paso separado y manual una vez que el endpoint está en vivo.
• glama.json: reclamo de propiedad de Glama (mantenedor Drudley).
• llms-install.md: notas de instalación para instaladores impulsados por agentes como Cline.

Licencia

MIT para el código. El contenido del directorio servido por las herramientas es CC BY 4.0.