Index Agentica

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

indexagentica-mcp

Servidor MCP remoto somente leitura (Streamable HTTP) e API de busca REST para Index Agentica, o diretório agent-first de habilidades, harnesses, servidores MCP, ferramentas, protocolos e APIs, além de seus guias longos, comparações, stacks e Agent Skills para download. Roda em Cloudflare Workers (plano gratuito), sem estado, sem Durable Objects, sem autenticação, CORS aberto.

Instalação

Servidor remoto: sem instalação, sem chave de API. Streamable HTTP em https://mcp.indexagentica.com/mcp (ao vivo).

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

Outros clientes: adicione a URL como um servidor Streamable HTTP sem autenticação (veja llms-install.md). O mesmo Worker também responde em https://indexagentica-mcp.indexagentica.workers.dev/mcp (veja DEPLOY.md).

Endpoints

Método	Caminho	O quê
POST	/mcp	Endpoint MCP Streamable HTTP (JSON-RPC 2.0, respostas JSON)
GET/DELETE	/mcp	405 (sem stream SSE independente, sem sessões)
GET	/	Autodescrição em JSON com links para o endpoint MCP, REST, llms.txt, docs
GET	/search?q=&type=&category=&tags=a,b&limit=	Busca ranqueada sobre entradas e conteúdo longo (type: entry, guide, comparison, stack, skill ou all (padrão); category aplica-se a entradas; limite 1-50, padrão 10; tags são combinadas com AND)
GET	/entries/<id> (ou <id>.json)	Uma entrada completa; 404 inclui suggestions
GET	/entries	Todos os ids
GET	/content/<type>/<id> (ou <id>.json)	Um guia, comparação, stack ou habilidade: metadados + markdown (?include_html=1 adiciona HTML); 404 inclui suggestions
GET	/content?type=	Itens longos publicados (metadados)
GET	/categories	Categorias com contagens
GET	/openapi.json	OpenAPI 3.1 para a API REST
GET	/.well-known/mcp/server-card.json	Cartão de servidor estático (fallback de varredura Smithery): serverInfo, authentication: {required: false}, o mesmo tools que tools/list, resources/prompts vazios
GET	/stats	Estatísticas públicas de uso (JSON): visualizações de página do site, cliques de saída, downloads de habilidades, chamadas de ferramentas MCP por ferramenta, requisições REST, divisão agente/humano; últimas 24h, últimos 7 dias, todo o período desde os timestamps since. Cache de 10 min. Veja Estatísticas de uso
GET	/v1/usage	Alias de /stats (usado pelo site; menos provável de ser bloqueado por filtros de bloqueio de conteúdo)
POST	/v1/e	Alias de /hit (usado pelo site)
POST	/hit	Beacon de uso do site a partir do script inline de indexagentica.com (verificação de origem, validação estrita, 204). Veja Beacons do site
GET	/health	Liveness (sem limite de taxa)

Erros são sempre JSON: {"error":{"status":400,"code":"bad_request","message":"..."}} (códigos: bad_request, not_found, method_not_allowed, rate_limited, upstream_error).

Ferramentas MCP

Ferramenta	Entrada	Saída (structuredContent)
search	query (string), type? (entry|guide|comparison|stack|skill|all, padrão todos), category? (slug; apenas entradas), tags? (string[], todos devem corresponder), limit? (1-50)	{query, type, category?, tags, limit, total, results[]}; cada resultado tem type, id, name, summary, url, tags, score, links, além de category (entradas) ou author, last_verified, entries (conteúdo longo)
get_entry	id (kebab-case)	{entry} (a entrada completa conforme o esquema de entrada + referências cruzadas links + longform)
get_content	type (guide|comparison|stack|skill), id, include_html?	{content}: front matter, metadados, markdown (links de esquema resolvidos para URLs absolutas), links; comparações adicionam comparison (critérios, tabela, veredito), stacks adicionam stack (caso de uso, componentes), habilidades adicionam skill_md (SKILL.md completo) e links.zip / links.skill_md
list_categories	nenhum	{total, generated, categories[{slug,name,description,count,html,json}]}

Toda ferramenta tem um inputSchema JSON-Schema, um outputSchema, anotações readOnlyHint, e retorna tanto structuredContent quanto o mesmo JSON como um bloco de conteúdo text. Argumentos inválidos e ids desconhecidos retornam como resultados de ferramenta isError: true (para que o modelo possa se corrigir); um nome de ferramenta desconhecido é JSON-RPC -32602.

Pontuação: por palavra da consulta, correspondência exata de id/nome 12, segmento de id 6, substring de nome 5, tag exata 4 (tag parcial 2), resumo 2, categoria 1.5, descrição 1; +8 se a frase inteira estiver no nome; multiplicado pela fração de palavras correspondidas.

Suporte a protocolo (duas eras, sem estado)

• 2026-07-28 (spec atual, "moderna"): sem handshake. Cada POST carrega _meta["io.modelcontextprotocol/protocolVersion"] e os cabeçalhos MCP-Protocol-Version, Mcp-Method (e para tools/call, Mcp-Name, sentinela base64 suportada). O servidor valida cabeçalhos contra o corpo (-32020 HeaderMismatch), rejeita versões desconhecidas com -32022 + lista supported, implementa server/discover, retorna resultType: "complete", serverInfo no resultado _meta, e dicas de cache ttlMs/cacheScope em tools/list e server/discover. Métodos desconhecidos -> HTTP 404 + -32601.
• 2025-11-25 / 2025-06-18 / 2025-03-26 ("legado"): initialize é respondido (versão negociada, com fallback para 2025-11-25), notifications/initialized -> 202, ping, tools/list, tools/call; lotes de 2025-03-26 são aceitos. Nenhum Mcp-Session-Id é emitido, então cada requisição é independente e qualquer isolado do Worker pode atendê-la.
• Respostas são sempre application/json (nunca SSE). Origin é verificado contra ALLOWED_ORIGINS (padrão * porque os dados são públicos e somente leitura).

Refs da spec: Streamable HTTP 2026-07-28, Versionamento / duas eras, server/discover.

Dados e cache

A fonte da verdade é o site estático publicado: GET https://indexagentica.com/api/index.json (todas as entradas + categorias) e GET /api/longform.json (metadados de conteúdo longo), buscados juntos; se o índice de conteúdo longo não puder ser carregado, as entradas continuam funcionando. get_content busca /api/longform/<route>/<id>.json sob demanda (mesmo cache), sempre de DATA_BASE_URL. O Worker mantém os índices na memória do isolado por CACHE_TTL_SECONDS (600 s), também os armazena na Cloudflare Cache API (eficaz em um domínio personalizado; um no-op em workers.dev), coalesce atualizações concorrentes e serve a cópia obsoleta se a busca upstream falhar. Novas categorias adicionadas pelo build do site aparecem automaticamente. Nada é gravado em lugar algum.

Registro de uso (Workers Analytics Engine)

Cada requisição (exceto OPTIONS, /health, /robots.txt, /favicon.ico, /hit, /stats) grava um ponto de dados no dataset do Analytics Engine indexagentica_mcp (binding ANALYTICS em wrangler.toml), para que possamos contar o uso de agentes por ferramenta e cliente. Se o binding estiver ausente (testes locais, env ratelimit-test), o registro é um no-op, e uma gravação com falha nunca afeta a resposta. Workers Free inclui 100.000 pontos de dados gravados por dia (preços); os dados são mantidos por 3 meses (limites).

Coluna	Campo	Notas
index1	<route>:<tool or method or endpoint>	ex.: mcp:search, rest:get_entry
blob1	rota	mcp ou rest
blob2	endpoint	normalizado: /mcp, /search, /entries/{id}, /content/{type}/{id}, ..., other
blob3	método JSON-RPC	initialize, tools/call, batch, ... (somente MCP)
blob4	ferramenta	nome da ferramenta MCP, ou o equivalente REST (search, get_entry, get_content, list_content, list_categories)
blob5, blob6	nome do cliente, versão	de initialize clientInfo ou 2026-07-28 _meta["io.modelcontextprotocol/clientInfo"]; truncado para 64/32 caracteres
blob7	User-Agent	truncado para 128 caracteres
blob8, blob9	versão do protocolo, era	modern / legacy
blob10	resultado	ok, error (HTTP ≥ 400, erro JSON-RPC ou resultado de ferramenta isError), rate_limited
blob11	detalhe	código de erro JSON-RPC, tool_error ou status HTTP
blob12, blob13	país, colo	de request.cf
blob14, blob15, blob16	filtro de tipo, filtro de categoria, id alvo	apenas valores kebab-case (slugs/ids do catálogo público); qualquer outra coisa é armazenada como invalid
blob17	classe de UA	human (User-Agent de navegador mainstream) ou agent (todo o resto: clientes MCP, SDKs, curl, crawlers, navegadores headless); veja src/ua.js. Adicionado em 2026-10-03; linhas anteriores são classificadas a partir de blob7 no momento da consulta
blob18	tráfego	internal (nossos próprios testes/agentes, veja Tráfego interno) ou outside; vazio antes de 2026-10-12
blob19	regra interna	header, ua ou ip (vazio para tráfego externo)
double1	status HTTP
double2	latência (ms)	tempo real dentro do Worker (os relógios do Workers avançam em I/O)
double3	ASN	de request.cf.asn (rede, não pessoa)
double4	contagem de resultados	total da busca
double5, double6	comprimento da consulta em caracteres, palavras

Privacidade: sem endereços IP, sem texto de consulta de busca, sem argumentos de ferramenta em texto livre, sem cookies ou tokens (o servidor não tem nenhum), e para beacons do site sem referrers, strings de consulta ou identificadores de cliente. Clientes são identificados apenas pelo nome/versão autodeclarados e um User-Agent truncado. Exemplo de consulta (SQL API): 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.

Beacons do site (POST /hit)

Cada página de indexagentica.com carrega um pequeno script inline (sem cookies, sem localStorage, sem identificadores, sem código de terceiros). Ele é ignorado quando navigator.webdriver está definido ou o navegador envia Do Not Track ou Global Privacy Control. Ele envia, com navigator.sendBeacon (como text/plain, então sem preflight CORS):

Evento	Corpo	Quando
visualização de página	{"t":"pageview","p":"/entries/x402/"}	carregamento da página; p é o caminho canônico da página (sem string de consulta, sem referrer)
clique de saída	{"t":"click","p":"/entries/x402/","id":"x402","h":"www.x402.org"}	clique no link de site/repo/docs/fonte de uma listagem em sua página de entrada
download	{"t":"download","p":"/skills/<id>/","id":"<id>","k":"zip"|"skill_md"}	clique em um zip de habilidade ou link bruto SKILL.md

O site envia para o alias /v1/e em mcp.indexagentica.com e faz fallback para o mesmo caminho em indexagentica-mcp.indexagentica.workers.dev se isso falhar (mesmo Worker, mesmas verificações). O Worker aceita apenas Origin: https://indexagentica.com (HIT_ORIGINS), corpos de até 512 bytes, os três tipos de evento com exatamente seus campos, p do conjunto de páginas que o site publica, ids que existem no índice publicado e hosts para os quais a entrada realmente linka. Qualquer outra coisa recebe 400 e não é armazenada. /hit tem seu próprio contador de limite de taxa (mesmos 120/min por IP). Hits aceitos vão para o dataset separado indexagentica_hits (binding HITS), índice hit:<event>:

Coluna	Campo
blob1	evento: pageview, click, download
blob2	caminho da página
blob3	ID da entrada ou habilidade (clique, download)
blob4	host de destino (clique)
blob5	tipo de download: zip, skill_md
blob6	classe de UA (human / agent)
blob7	país (de request.cf)
blob8	tráfego: internal / outside (vazio antes de 2026-10-12)
blob9	regra interna: header, ua, ip
double1	1

Estatísticas de uso (GET /stats)

Agrega ambos os conjuntos de dados por meio da API SQL do Analytics Engine usando o segredo CF_ANALYTICS_TOKEN (Account Analytics Read) e CF_ACCOUNT_ID. As contagens são SUM(_sample_interval). Janelas: last_24h, last_7d (contínua) e all_time. Como o Analytics Engine mantém 3 meses, um cron diário (30 0 * * *) armazena os totais de cada dia UTC concluído no Workers KV (STATS_KV, chave day:YYYY-MM-DD); all_time = dias armazenados + uma consulta ao vivo desde o primeiro dia ainda não armazenado (/stats também recupera dias ausentes de forma preguiçosa). since.mcp_api (STATS_API_SINCE, primeiro deploy com registro de solicitações) e since.site_beacon (STATS_BEACON_SINCE, deploy do beacon) marcam onde a contagem começa; nada anterior é estimado ou preenchido retroativamente. Apenas os nomes das próprias ferramentas do servidor são publicados (qualquer outra coisa é unknown_tool). As respostas são armazenadas em cache por 10 minutos (Cache API + em memória, Cache-Control: public, max-age=600). Sem o token, o endpoint responde {"status":"collecting", ...} sem números; se a API SQL falhar, 503 {"status":"unavailable"}.

Cada janela conta apenas tráfego externo e adiciona: site.downloads.by_skill, site.outbound_clicks_by_entry, mcp.top_clients (nomes de clientes MCP autorrelatados, em minúsculas e reduzidos a [a-z0-9._ -], top 10, apenas nomes vistos ≥ 3 vezes), top_user_agent_families (nome do bot, browser, headless-chrome ou primeiro token de produto; top 10, ≥ 3) e internal_excluded (o que foi deixado de fora, por regra). Os dias do KV carregam uma versão de rollup (v); dias de uma versão mais antiga são recalculados enquanto os dados brutos ainda são retidos, então mudanças de regras se aplicam retroativamente. A recuperação preguiçosa recalcula no máximo 2 dias por chamada de /stats e o cron 5 por execução (cada dia é ~7 subconsultas SQL; Workers Free permite 50).

Tráfego interno

Nossos próprios testes, monitores e agentes são registrados, mas excluídos de /stats. Uma solicitação ou beacon é interno se qualquer regra corresponder (src/internal.js):

Regra	Correspondência
header	X-Indexagentica-Internal: 1 (permitido em CORS; test/e2e.mjs o envia em toda solicitação)
ua	User-Agent contém indexagentica (nossos clientes usam indexagentica-<agent>/1)
ip	IP do cliente dentro de um CIDR listado no segredo opcional INTERNAL_IPS (separado por vírgulas, IPv4/IPv6). Não definido: nosso box compartilhado sai por endereços rotativos em um intervalo de relay compartilhado, então uma regra de IP também descartaria estranhos

Linhas registradas antes da existência da flag (2026-10-12) são correspondidas retroativamente em SQL pela assinatura de nossas próprias sessões (API_RETRO / HITS_RETRO em src/stats.js): linhas da API cujo nome de cliente MCP é e2e (nossa suíte de testes), ou dos EUA com um User-Agent curl/node/python/headless-Chrome dentro das janelas documentadas de lançamento e verificação (2026-10-02 20:15–20:45 e 2026-10-03 04:55–05:50 UTC), e beacons do site dos EUA entre 05:00 e 05:50 UTC em 2026-10-03. Isso é melhor esforço: sessões internas que pareciam tráfego externo ainda podem ser contadas, e solicitações externas com os mesmos clientes genéricos dentro dessas janelas são excluídas.

Como nossos próprios agentes devem chamar o servidor:

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

Limitação de taxa

• Padrão: 120 solicitações / 60 s por IP de cliente, por localização Cloudflare, via binding de Rate Limiting do Workers ([[ratelimits]] em wrangler.toml, GA desde setembro de 2025; o período deve ser 10 ou 60 s). É intencionalmente aproximado (consistência eventual, por localização).
• Se o binding estiver ausente ou com erros, um token bucket por isolado com os mesmos números (RATE_LIMIT_REQUESTS / RATE_LIMIT_PERIOD_SECONDS) é usado como alternativa.
• Exceder retorna HTTP 429 com Retry-After; em /mcp o corpo é um erro JSON-RPC (-32000), em outros lugares o envelope de erro JSON. /health e OPTIONS não são medidos. As respostas carregam x-ratelimit-limit / x-ratelimit-period.
• Teto do plano gratuito a ter em mente: Workers Free permite 100.000 solicitações/dia por conta e 10 ms de CPU por solicitação (limites). Uma busca a frio custa ~1-3 ms de CPU (analisando o índice de ~135 KB); solicitações quentes bem abaixo de 1 ms.

Desenvolvimento local e testes

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

Os testes E2E de formato longo se adaptam aos dados: com itens publicados, eles buscam um de cada tipo via REST e MCP; com nenhum (todos rascunhos), eles verificam as listagens vazias e caminhos não encontrados. Para exercitar o caminho completo antes de qualquer publicação, construa o site com rascunhos publicados (por exemplo, INCLUDE_DRAFTS=1 SITE_URL=http://127.0.0.1:8089 node scripts/build.mjs no repositório do site), sirva dist/ nessa porta e execute npm test com DATA_BASE_URL definido.

scripts/test-local.sh inicia o Worker normal em :8797 e uma cópia de limite baixo (--env ratelimit-test, 5 req / 10 s) em :8798, executa test/e2e.mjs e depois verifica o servidor com @modelcontextprotocol/inspector --cli na era legada padrão e fixado na era moderna (config protocolEra: "modern").

Verificações manuais:

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"}}}'

Conectando um cliente

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

Config JSON (por exemplo, o .mcp.json do Claude Code; o Claude Code exige "type": "http" para servidores remotos):

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

Outros clientes usam seus próprios nomes para Streamable HTTP (Cline: "type": "streamableHttp"; alguns aceitam apenas "url").

Configuração (wrangler.toml [vars])

Variável	Padrão	Significado
DATA_BASE_URL	https://indexagentica.com	De onde /api/index.json é buscado
CACHE_TTL_SECONDS	600	TTL em memória / Cache API
RATE_LIMIT_REQUESTS, RATE_LIMIT_PERIOD_SECONDS	120, 60	Limite documentado + bucket de fallback (manter em sincronia com [ratelimits.simple])
ALLOWED_ORIGINS	*	Lista de permissões de Origin separada por vírgulas para chamadores de navegador
PUBLIC_BASE_URL	origem da solicitação	Base canônica para links em GET /
CF_ACCOUNT_ID	(nenhum)	Conta para a API SQL do Analytics Engine (/stats)
STATS_API_SINCE, STATS_BEACON_SINCE	2026-10-02T20:21:47Z, (hora do deploy)	Onde a contagem de MCP/REST e beacon do site começa (mostrado como since em /stats)
INTERNAL_IPS (segredo, opcional)	(nenhum)	CIDRs separados por vírgulas cujas solicitações contam como tráfego interno
HIT_ORIGINS	https://indexagentica.com,https://www.indexagentica.com	Origens permitidas para POST /hit

Segredo: CF_ANALYTICS_TOKEN (Account Analytics Read), definido com wrangler secret put CF_ANALYTICS_TOKEN. Bindings: ANALYTICS e HITS (Analytics Engine), STATS_KV (KV), RATE_LIMITER; cron 30 0 * * *.

Deploy

Veja DEPLOY.md para as opções de mcp.indexagentica.com e o acesso exato necessário ao Cloudflare/GoDaddy. Versão curta:

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

Estrutura

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

Licença: código MIT; conteúdo do diretório CC BY 4.0.

Metadados do registro

• server.json: entrada oficial do Registro MCP (com.indexagentica/mcp, esquema 2025-12-11), validada com mcp-publisher validate. A publicação usa autenticação de domínio HTTP contra https://indexagentica.com/.well-known/mcp-registry-auth; é uma etapa separada e manual, uma vez que o endpoint esteja ativo.
• glama.json: reivindicação de propriedade do Glama (mantenedor Drudley).
• llms-install.md: notas de instalação para instaladores orientados por agente, como o Cline.

Licença

MIT para o código. O conteúdo do diretório servido pelas ferramentas é CC BY 4.0.