Kaidn

Kaidn MCP

Servidor de Protocolo de Contexto de Modelo (MCP) para a API de pontuação de fraude Kaidn.

Investigue fraudes em linguagem simples — "por que este cadastro foi bloqueado?", "o que mais este dispositivo tocou?", "o que está na fila de revisão esta manhã?"

• Evidência, não apenas uma pontuação. Cada motivo carrega os números brutos por trás dele, para que um modelo possa explicar um veredito em vez de adivinhar.
• Somente leitura por padrão. Nada altera seu tenant, a menos que você opte por isso.
• Protegido por cota. Um agente em loop não pode gastar seu mês em dez minutos.
• Qualquer cliente. MCP é um protocolo aberto — stdio localmente, HTTP Streamable para agentes remotos e hospedados.

Requisitos

Node.js 18 ou mais recente e uma chave de API do seu painel Kaidn.

Começando

Primeiro, instale o servidor Kaidn MCP com seu cliente. A configuração padrão funciona na maioria das ferramentas:

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

Configuração

Precedência: flags de CLI sobrescrevem variáveis de ambiente.

A chave de API é deliberadamente somente ambiente. Uma chave passada como flag vaza em listagens de processos e histórico de shell.

Transportes

HTTP+SSE está deliberadamente ausente: descontinuado na especificação de 2025-03-26 e encerrado em junho de 2026.

HTTP Streamable

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

Sem estado — um servidor novo por requisição, nada compartilhado entre chamadores — então fica atrás de um balanceador de carga sem surpresas. GET /health não é autenticado para que um orquestrador possa verificar a vivacidade sem segurar o 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

Build multi-estágio, executa como o usuário não privilegiado node, com healthcheck.

Segurança

O servidor guarda sua chave de API. Quem puder alcançá-lo pode gastar sua cota, então os padrões são conservadores e as proteções falham fechadas em vez de avisar.

• Faz bind em 127.0.0.1 e se recusa a iniciar em uma interface mais ampla a menos que KAIDN_MCP_HTTP_TOKEN esteja definido. Ele para com uma explicação em vez de expor silenciosamente sua conta.
• Somente leitura por padrão. add_to_list e label_outcome existem apenas com --allow-writes.
• set_config e forget_subject nunca são expostos, em nenhum modo. Um muda silenciosamente o veredito em cada evento futuro; o outro é apagamento irreversível de GDPR. Ambos pertencem ao painel, diante de um humano.
• Teto de cota por processo, com orçamento restante relatado em cada resposta com custo. Uma reserva que ultrapassaria é recusada diretamente em vez de parcialmente gasta.
• A chave nunca cruza o limite da ferramenta — não como parâmetro, não na saída, não em um erro.

Ferramentas

Duas coisas governam cada ferramenta: se ela gasta cota e se ela muda algo.

Somente leitura — disponível por padrão

¹ Grátis quando a entidade é um device_id; enriquecimento só custa em email ou IP.

Mutação — exige --allow-writes

Exemplos práticos

As ferramentas são projetadas para serem encadeadas. Estes são os fluxos para os quais foram construídas.

Triagem matinal

Você: O que aconteceu durante a noite e o que precisa de mim?

O modelo chama get_stats para o formato das últimas 24 horas, depois triage_queue para os eventos em review, depois explain_event no pior. Você recebe uma lista classificada com o raciocínio anexado, em vez de um painel que ainda precisa ler.

"Por que este cliente foi bloqueado?"

Você: Evento evt_8f21c — um cliente diz que foi bloqueado erroneamente.

explain_event retorna cada verificação que disparou com sua evidência bruta — o ASN de datacenter que correspondeu, quantas contas compartilharam o dispositivo, a contagem de velocidade. Suficiente para responder ao cliente ou concluir que a regra estava errada e precisa de ajuste.

Trabalhando para fora a partir de um sinal

Você: 194.x.x.x é um caso isolado ou parte de um anel?

investigate_entity retorna enriquecimento e reputação de rede para o IP mais cada evento recente em que aparece. Se os mesmos ids de dispositivo continuam recorrentes, isso é um anel em vez de uma coincidência.

Verificando uma mudança de regra antes de fazê-la

Você: Se eu reduzisse o peso de velocidade, o que deixaria de ser bloqueado?

get_config lê os pesos atuais; list_events com verdict: "block" mostra o que está sendo capturado atualmente. O modelo pode dizer quais desses dependem da verificação que você está prestes a enfraquecer.

Tratamento de erros

Falhas retornam como erros de ferramenta com uma mensagem legível, não exceções — o modelo pode agir sobre elas.

Erros nunca contêm sua chave de API.

Solução de problemas

O cliente não mostra ferramentas. Verifique o log MCP do cliente para a linha de inicialização. kaidn-mcp: ready (stdio, …) no stderr significa que o servidor está ativo e o problema está no lado do cliente. Nada geralmente significa que npx não conseguiu resolver o pacote ou o Node é mais antigo que 18.

Inicia e sai imediatamente. Quase sempre um KAIDN_API_KEY ausente. A mensagem diz isso no stderr; alguns clientes ocultam o stderr, então execute em um terminal para vê-lo.

add_to_list e label_outcome estão ausentes. Funcionando como projetado. Eles precisam de --allow-writes.

set_config e forget_subject estão ausentes. Também por design, e não estão disponíveis em nenhum modo. Veja SECURITY.md.

O modo HTTP se recusa a iniciar. Você fez bind em algo diferente de loopback sem um token de portador. Isso é a proteção funcionando — o processo guarda sua chave de API.

Tudo está lento. As verificações de enriquecimento fazem chamadas upstream ao vivo. get_stats, list_events, explain_event e triage_queue são grátis e rápidas; prefira-as ao ler histórico.

Verifique o servidor independentemente do cliente:

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

Suporte

• Bugs e solicitações de recursos: Issues do GitHub
• Segurança: security@kaidn.io — veja SECURITY.md
• Privacidade e tratamento de dados: PRIVACY.md
• A própria API: kaidn.io

Executar a partir do código-fonte

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 se inicia sem um cliente:

KAIDN_API_KEY=your_key npm start

Imprime kaidn-mcp: ready (stdio, read-only, quota ceiling 100) no stderr e então espera no stdin — isso é o transporte MCP, então o silêncio está correto.

Por que a evidência importa

O motor do Kaidn é baseado em regras e explicável: cada motivo carrega os números brutos por trás dele. Uma pontuação nua não dá nada para um modelo raciocinar, enquanto checks[] com evidência anexada dá algo para explicar. Essa é a diferença entre explain_event ser útil e ser decorativo.

As regras decidem. O modelo narra.

Projeto

• CONTRIBUTING.md — o que pertence aqui e as garantias que uma mudança não deve quebrar
• SECURITY.md — relato, modelo de ameaça, limitações conhecidas
• PRIVACY.md — o que passa, o que é armazenado, o que não é
• CODE_OF_CONDUCT.md

Licença

MIT