Kaidn MCP

**Model Context Protocol server for the Kaidn fraud-scoring API.**

Investigate fraud in plain English — *"why was this signup blocked?"*, *"what

else has this device touched?"*, *"what's in the review queue this morning?"*

• Evidence, not just a score. Every reason carries the raw numbers behind

it, so a model can explain a verdict rather than guess at it.

• Read-only by default. Nothing changes your tenant unless you opt in.
• Quota-guarded. An agent in a loop cannot spend your month in ten minutes.
• Any client. MCP is an open protocol — stdio locally, Streamable HTTP for

remote and hosted agents.

Requirements

Node.js 18 or newer, and an API key from your Kaidn dashboard.

Getting started

First, install the Kaidn MCP server with your client. Standard config works in

most of the tools:

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

Claude Code

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

Claude Desktop

Add the standard config to `claude_desktop_config.json`, then restart Claude.

Settings → Developer → Edit Config opens the file.

Cursor

Settings → MCP → Add new MCP Server, or add the standard config to

`.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` for every project).

VS Code

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

Windsurf

Add the standard config to `~/.codeium/windsurf/mcp_config.json`.

Cline

Add the standard config to `cline_mcp_settings.json` via the MCP Servers icon →

Configure MCP Servers.

Zed

Add to `settings.json` under `context_servers`, using the same command, args and

env as the standard config.

Anything else

Any MCP client takes a command, args and an env block. Use the

standard config above. If the client can only reach the server over the network

rather than spawning a process, see Streamable HTTP.

Configuration

Precedence: CLI flags override environment variables.

The API key is deliberately env-only. A key passed as a flag leaks into process

listings and shell history.

Transports

`HTTP+SSE` is deliberately absent: deprecated in the 2025-03-26 spec and sunset

in June 2026.

Streamable HTTP

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

Stateless — a fresh server per request, nothing shared between callers — so it

sits behind a load balancer without surprises. `GET /health` is unauthenticated

so an orchestrator can check liveness without holding the 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

Multi-stage build, runs as the unprivileged `node` user, with a healthcheck.

Security

The server holds your API key. Whoever can reach it can spend your quota, so

the defaults are conservative and the guards fail closed rather than warning.

• Binds `127.0.0.1`, and refuses to start on a wider interface unless

`KAIDN_MCP_HTTP_TOKEN` is set. It stops with an explanation rather than

quietly exposing your account.

• Read-only by default. `add_to_list` and `label_outcome` exist only with

`--allow-writes`.

• `set_config` and `forget_subject` are never exposed, in any mode. One

silently changes the verdict on every future event; the other is irreversible

GDPR erasure. Both belong in the dashboard, in front of a human.

• Quota ceiling per process, with remaining budget reported on every costing

response. A reservation that would overshoot is refused outright rather than

partially spent.

• The key never crosses the tool boundary — not as a parameter, not in

output, not in an error.

Tools

Two things govern every tool: whether it spends quota, and whether it

changes anything.

Read-only — available by default

¹ Free when the entity is a `device_id`; enrichment only costs on email or IP.

Mutating — require `--allow-writes`

Worked examples

The tools are designed to be chained. These are the flows they were built for.

Morning triage

> You: What happened overnight, and what needs me?

The model calls `get_stats` for the shape of the last 24 hours, then

`triage_queue` for the events sitting on `review`, then `explain_event` on the

worst one. You get a ranked list with the reasoning attached, rather than a

dashboard you still have to read.

"Why was this customer blocked?"

> You: Event `evt_8f21c` — a customer says they were wrongly blocked.

`explain_event` returns every check that fired with its raw evidence — the

datacenter ASN it matched, how many accounts shared the device, the velocity

count. Enough to answer the customer, or to conclude the rule was wrong and

needs tuning.

Working outward from one signal

> You: Is `194.x.x.x` a one-off or part of a ring?

`investigate_entity` returns enrichment and network reputation for the IP plus

every recent event it appears in. If the same device ids keep recurring, that is

a ring rather than a coincidence.

Checking a rule change before making it

> You: If I dropped the velocity weight, what would stop being blocked?

`get_config` reads the current weights; `list_events` with `verdict: "block"`

shows what is currently caught. The model can tell you which of those hang on

the check you are about to weaken.

Error handling

Failures come back as tool errors with a readable message, not exceptions — the

model can act on them.

Errors never contain your API key.

Troubleshooting

The client shows no tools.

Check the client's MCP log for the startup line. `kaidn-mcp: ready (stdio, …)`

on stderr means the server is up and the problem is on the client side. Nothing

at all usually means `npx` could not resolve the package or Node is older than 18.

It starts, then exits immediately.

Almost always a missing `KAIDN_API_KEY`. The message says so on stderr; some

clients hide stderr, so run it in a terminal to see it.

`add_to_list` and `label_outcome` are missing.

Working as designed. They need `--allow-writes`.

`set_config` and `forget_subject` are missing.

Also by design, and they are not available in any mode. See

SECURITY.md.

HTTP mode refuses to start.

You bound something other than loopback without a bearer token. That is the

guard working — the process holds your API key.

Everything is slow.

The enrichment checks make live upstream calls. `get_stats`, `list_events`,

`explain_event` and `triage_queue` are free and fast; prefer them when reading

history.

Check the server independently of the client:

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

Support

• Bugs and feature requests: GitHub issues
• Security: security@kaidn.io — see SECURITY.md
• Privacy and data handling: PRIVACY.md
• The API itself: kaidn.io

Run from source

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

To check it starts without a client:

KAIDN_API_KEY=your_key npm start

It prints `kaidn-mcp: ready (stdio, read-only, quota ceiling 100)` to stderr and

then waits on stdin — that is the MCP transport, so the silence is correct.

Why the evidence matters

Kaidn's engine is rules-first and explainable: every reason carries the raw

numbers behind it. A bare score gives a model nothing to reason about, while

`checks[]` with evidence attached gives it something to explain. That is the

difference between `explain_event` being useful and being decorative.

Rules decide. The model narrates.

Project

• CONTRIBUTING.md — what belongs here, and the guarantees a change must not break
• SECURITY.md — reporting, threat model, known limitations
• PRIVACY.md — what passes through, what is stored, what is not
• CODE_OF_CONDUCT.md

Licence

MIT