Recon · API & MCP

Acceso programático de solo-lectura a los datos de inteligencia competitiva. Todo son endpoints GET; no hay escritura.

Autenticación

Pasa el API_TOKEN (definido en .env) por cabecera, de cualquiera de las dos formas:

Authorization: Bearer <API_TOKEN>
X-API-Key: <API_TOKEN>

Endpoints base

Método	Ruta	Auth	Qué devuelve
GET	/api/health	pública	{ ok: true } — prueba de conectividad
GET	/api/db	token	Lista de colecciones con sus counts
GET	/api/db/:collection	token	Filas de una colección (paginado)
GET	/api/export/:coll.:fmt	token	Descarga .json o .csv de una colección

/api/db/:collection — parámetros

• site — privoytruco | dominotrancao (opcional)
• limit — default 100, máx 1000 · offset — default 0
• sort — campo (default ts si existe, si no _id) · order — asc | desc

Respuesta: { collection, site, count, limit, offset, rows }.

Colecciones

Endpoints analíticos

Vistas derivadas ya calculadas. Todas aceptan el token y el parámetro site.

Ruta	Params	Qué devuelve
/api/presence	site, hours	Serie de conectados / mesas / manos
/api/heatmap	site, days	Promedio de conectados por hora×día (zona Caracas)
/api/tournaments/liquidity	site	Humanos vs bots e inscritos vs jugaron (no-show) por torneo
/api/bots-por-modo	site	% de bots por modo de juego
/api/tournaments/bot-by-hour	site	% de bots por hora del día
/api/torneos-economia	site, days	Pozos ofrecido/repartido, fees, nº torneos por día
/api/activity	site, limit	Partidas/activos/nuevos por corrida de ranking
/api/whales	site, limit	Top jugadores y su tendencia de actividad
/api/whale/:key/history	site	Serie temporal de un jugador
/api/users/stats	site	Padrón total + nuevos 24h / 7d
/api/users/new	site, days, limit	Últimos usuarios nuevos

Ejemplos (curl)

TOKEN=<API_TOKEN>   # está en tu .env

curl -s http://localhost:4000/api/health

curl -s -H "X-API-Key: $TOKEN" \
  http://localhost:4000/api/db

curl -s -H "X-API-Key: $TOKEN" \
  "http://localhost:4000/api/db/tournaments_liq?site=dominotrancao&limit=5"

curl -s -H "Authorization: Bearer $TOKEN" \
  "http://localhost:4000/api/tournaments/liquidity?site=dominotrancao"

MCP remoto (recomendado)

La propia API sirve el MCP. No hace falta clonar el repo ni instalar nada del proyecto: basta la URL y el token.

Qué	Valor
Endpoint	POST https://161-97-121-214.sslip.io/mcp
Transporte	Streamable HTTP, sin estado (GET/DELETE responden 405)
Auth	El mismo API_TOKEN de la API: Authorization: Bearer <API_TOKEN> o X-API-Key: <API_TOKEN>
Tools	Las mismas del MCP local, todas de solo lectura (lista abajo)

Claude Code — Ubuntu / macOS (bash)

claude mcp add --transport http recon https://161-97-121-214.sslip.io/mcp \
  --header "Authorization: Bearer <API_TOKEN>"

Añade --scope user para tenerlo en todos tus proyectos. Comprueba con claude mcp list (debe salir ✓ Connected).

Claude Code — Windows (PowerShell)

claude mcp add --transport http recon https://161-97-121-214.sslip.io/mcp `
  --header "Authorization: Bearer <API_TOKEN>"

En cmd.exe va en una sola línea (o con ^ al final de cada línea en lugar de `).

Claude Desktop — Ubuntu

Requiere Node 18+ (para npx). Edita ~/.config/Claude/claude_desktop_config.json y agrega dentro de "mcpServers":

{
  "mcpServers": {
    "recon": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://161-97-121-214.sslip.io/mcp",
        "--header", "X-API-Key:${RECON_TOKEN}"
      ],
      "env": { "RECON_TOKEN": "<API_TOKEN>" }
    }
  }
}

Si usas nvm, Claude Desktop no ve tu PATH: pon la ruta completa, por ejemplo "command": "/home/<tu-usuario>/.nvm/versions/node/v22.14.0/bin/npx" (sácala con which npx). Reinicia Claude Desktop después de guardar.

Claude Desktop — Windows

Requiere Node 18+ instalado (nodejs.org). Abre %APPDATA%\Claude\claude_desktop_config.json (pégalo en la barra de Explorer, o en Claude Desktop: Settings › Developer › Edit Config) y agrega:

{
  "mcpServers": {
    "recon": {
      "command": "cmd",
      "args": [
        "/c", "npx", "-y", "mcp-remote",
        "https://161-97-121-214.sslip.io/mcp",
        "--header", "X-API-Key:${RECON_TOKEN}"
      ],
      "env": { "RECON_TOKEN": "<API_TOKEN>" }
    }
  }
}

Cierra Claude Desktop del todo (también desde la bandeja del sistema) y vuelve a abrirlo. Se usa X-API-Key en lugar de Authorization: Bearer … porque no lleva espacios: en Windows los espacios dentro de args se rompen.

Probar con curl

TOKEN=<API_TOKEN>
URL=https://161-97-121-214.sslip.io/mcp

# initialize -> debe traer "serverInfo":{"name":"recon",...}
curl -sS "$URL" -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

# tools/list
curl -sS "$URL" -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# sin token -> 401
curl -i -X POST "$URL" -H "Content-Type: application/json" -d '{}'

Con interfaz gráfica: npx @modelcontextprotocol/inspector, transporte Streamable HTTP, la URL de arriba y la cabecera Authorization: Bearer <API_TOKEN>.

MCP local (desarrollo)

Alternativa por stdio para desarrollo: vive en mcp/, corre en tu máquina y llama a la API con el mismo token (como RECON_API_TOKEN). Usa exactamente las mismas tools que el remoto.

claude mcp add recon-local \
  --env RECON_API_TOKEN=<API_TOKEN> \
  --env RECON_API_BASE=http://localhost:4000 \
  -- node /ruta/al/repo/scrapper/mcp/server.js

Instalar una vez: cd mcp && npm install. Más detalle en mcp/README.md.