Kaidn

Kaidn MCP

Servidor de Protocolo de Contexto de Modelo (MCP) para la API de puntuación de fraude Kaidn.

Investiga fraudes en lenguaje natural — "¿por qué se bloqueó este registro?", "¿qué más ha tocado este dispositivo?", "¿qué hay en la cola de revisión esta mañana?"

• Evidencia, no solo una puntuación. Cada motivo lleva los números brutos detrás, para que un modelo pueda explicar un veredicto en lugar de adivinarlo.
• Solo lectura por defecto. Nada cambia en tu tenant a menos que optes por ello.
• Protegido por cuota. Un agente en un bucle no puede gastar tu mes en diez minutos.
• Cualquier cliente. MCP es un protocolo abierto: stdio localmente, HTTP Streamable para agentes remotos y alojados.

Requisitos

Node.js 18 o superior, y una clave de API desde tu panel de Kaidn.

Primeros pasos

Primero, instala el servidor MCP de Kaidn con tu cliente. La configuración estándar funciona en la mayoría de las herramientas:

{
  "mcpServers": {
    "kaidn": {
      "command": "npx",
      "args": ["@kaidn/mcp@latest"],
      "env": { "KAIDN_API_KEY": "your_key" }
    }
  }
}

claude mcp add kaidn --env KAIDN_API_KEY=your_key -- npx @kaidn/mcp@latest

code --add-mcp '{"name":"kaidn","command":"npx","args":["@kaidn/mcp@latest"],"env":{"KAIDN_API_KEY":"your_key"}}'

Configuración

Precedencia: Las banderas de CLI anulan las variables de entorno.

La clave de API es deliberadamente solo entorno. Una clave pasada como bandera se filtra en los listados de procesos y el historial del shell.

Transportes

HTTP+SSE está deliberadamente ausente: obsoleto en la especificación del 2025-03-26 y retirado en junio de 2026.

HTTP Streamable

npx @kaidn/mcp@latest --http --port 8765

Sin estado — un servidor nuevo por solicitud, nada compartido entre llamadores — por lo que se coloca detrás de un balanceador de carga sin sorpresas. GET /health no está autenticado para que un orquestador pueda verificar la disponibilidad sin tener el token.

Docker

docker build -t kaidn-mcp .

# stdio — behaves like the npx invocation
docker run -i --rm -e KAIDN_API_KEY=your_key kaidn-mcp

# HTTP — for remote agents
docker run --rm -p 8765:8765 \
  -e KAIDN_API_KEY=your_key \
  -e KAIDN_MCP_TRANSPORT=http \
  -e KAIDN_MCP_HOST=0.0.0.0 \
  -e KAIDN_MCP_HTTP_TOKEN=your_token \
  kaidn-mcp

Compilación de múltiples etapas, se ejecuta como el usuario no privilegiado node, con un healthcheck.

Seguridad

El servidor contiene tu clave de API. Quien pueda alcanzarlo puede gastar tu cuota, por lo que los valores predeterminados son conservadores y las protecciones fallan de forma cerrada en lugar de advertir.

• Se enlaza a 127.0.0.1, y se niega a iniciar en una interfaz más amplia a menos que KAIDN_MCP_HTTP_TOKEN esté configurado. Se detiene con una explicación en lugar de exponer silenciosamente tu cuenta.
• Solo lectura por defecto. add_to_list y label_outcome existen solo con --allow-writes.
• set_config y forget_subject nunca se exponen, en ningún modo. Una cambia silenciosamente el veredicto en cada evento futuro; la otra es un borrado irreversible según el GDPR. Ambas pertenecen al panel, frente a un humano.
• Límite de cuota por proceso, con el presupuesto restante informado en cada respuesta con costo. Una reserva que excedería se rechaza directamente en lugar de gastarse parcialmente.
• La clave nunca cruza el límite de la herramienta — no como parámetro, no en la salida, no en un error.

Herramientas

Dos cosas gobiernan cada herramienta: si gasta cuota, y si cambia algo.

Solo lectura — disponible por defecto

¹ Gratis cuando la entidad es un device_id; el enriquecimiento solo cuesta en correo electrónico o IP.

Mutación — requiere --allow-writes

Ejemplos prácticos

Las herramientas están diseñadas para encadenarse. Estos son los flujos para los que fueron construidas.

Triage matutino

Tú: ¿Qué pasó durante la noche, y qué necesita mi atención?

El modelo llama a get_stats para la forma de las últimas 24 horas, luego triage_queue para los eventos en review, luego explain_event en el peor. Obtienes una lista clasificada con el razonamiento adjunto, en lugar de un panel que aún tienes que leer.

"¿Por qué se bloqueó a este cliente?"

Tú: Evento evt_8f21c — un cliente dice que fue bloqueado incorrectamente.

explain_event devuelve cada verificación que se activó con su evidencia bruta — el ASN de centro de datos que coincidió, cuántas cuentas compartieron el dispositivo, el conteo de velocidad. Suficiente para responder al cliente, o para concluir que la regla era incorrecta y necesita ajuste.

Trabajando hacia afuera desde una señal

Tú: ¿Es 194.x.x.x un caso aislado o parte de un anillo?

investigate_entity devuelve enriquecimiento y reputación de red para la IP más cada evento reciente en el que aparece. Si los mismos ID de dispositivo se repiten, eso es un anillo en lugar de una coincidencia.

Verificando un cambio de regla antes de hacerlo

Tú: Si redujera el peso de velocidad, ¿qué dejaría de bloquearse?

get_config lee los pesos actuales; list_events con verdict: "block" muestra lo que se captura actualmente. El modelo puede decirte cuáles de esos dependen de la verificación que estás a punto de debilitar.

Manejo de errores

Los fallos vuelven como errores de herramienta con un mensaje legible, no excepciones — el modelo puede actuar sobre ellos.

Los errores nunca contienen tu clave de API.

Solución de problemas

El cliente no muestra herramientas. Revisa el registro MCP del cliente para la línea de inicio. kaidn-mcp: ready (stdio, …) en stderr significa que el servidor está activo y el problema está en el lado del cliente. Nada en absoluto generalmente significa que npx no pudo resolver el paquete o Node es anterior a 18.

Se inicia, luego sale inmediatamente. Casi siempre falta KAIDN_API_KEY. El mensaje lo dice en stderr; algunos clientes ocultan stderr, así que ejecútalo en una terminal para verlo.

add_to_list y label_outcome faltan. Funciona como está diseñado. Necesitan --allow-writes.

set_config y forget_subject faltan. También por diseño, y no están disponibles en ningún modo. Consulta SECURITY.md.

El modo HTTP se niega a iniciar. Enlazaste algo que no es loopback sin un token de portador. Esa es la protección funcionando — el proceso contiene tu clave de API.

Todo es lento. Las verificaciones de enriquecimiento hacen llamadas upstream en vivo. get_stats, list_events, explain_event y triage_queue son gratis y rápidas; prefíelas al leer historial.

Verifica el servidor independientemente del cliente:

node dist/index.js --help                 # no key required
KAIDN_API_KEY=your_key npm start          # should print a ready line

Soporte

• Errores y solicitudes de funciones: Problemas de GitHub
• Seguridad: security@kaidn.io — consulta SECURITY.md
• Privacidad y manejo de datos: PRIVACY.md
• La API en sí: kaidn.io

Ejecutar desde el código fuente

git clone https://github.com/Kaidn-io/kaidn-mcp.git
cd kaidn-mcp
npm install
npm run build
npm test

claude mcp add kaidn --env KAIDN_API_KEY=your_key -- node /absolute/path/to/kaidn-mcp/dist/index.js

Para verificar que se inicia sin un cliente:

KAIDN_API_KEY=your_key npm start

Imprime kaidn-mcp: ready (stdio, read-only, quota ceiling 100) en stderr y luego espera en stdin — ese es el transporte MCP, por lo que el silencio es correcto.

Por qué la evidencia importa

El motor de Kaidn es primero en reglas y explicable: cada motivo lleva los números brutos detrás. Una puntuación desnuda no le da nada al modelo para razonar, mientras que checks[] con evidencia adjunta le da algo que explicar. Esa es la diferencia entre que explain_event sea útil y que sea decorativo.

Las reglas deciden. El modelo narra.

Proyecto

• CONTRIBUTING.md — qué pertenece aquí, y las garantías que un cambio no debe romper
• SECURITY.md — reporte, modelo de amenazas, limitaciones conocidas
• PRIVACY.md — qué pasa a través, qué se almacena, qué no
• CODE_OF_CONDUCT.md

Licencia

MIT