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:

config.json

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

Claude Code

Terminal

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

bash

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

Option	Environment variable	Default	Purpose
	`KAIDN_API_KEY`	required	Your secret key. Environment only — never a flag, never a tool argument.
	`KAIDN_API_URL`	`https://api.kaidn.io`	API base URL
`--allow-writes`	`KAIDN_MCP_ALLOW_WRITES=1`	off	Register the mutating tools
	`KAIDN_MCP_MAX_QUOTA_CALLS`	`100`	Quota ceiling per process
`--http`	`KAIDN_MCP_TRANSPORT=http`	`stdio`	Serve Streamable HTTP
`--host <addr>`	`KAIDN_MCP_HOST`	`127.0.0.1`	HTTP bind address
`--port <n>`	`KAIDN_MCP_PORT`	`8765`	HTTP port
	`KAIDN_MCP_HTTP_TOKEN`	unset	Require `Authorization: Bearer` on HTTP
`--help`			Show usage
`--version`			Show the version

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

Transport	Use it for	Endpoint
stdio (default)	local clients that spawn a subprocess	—
Streamable HTTP	remote agents, containers, anything off-machine	`POST /mcp`

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

Streamable HTTP

Terminal

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

Terminal

docker build -t kaidn-mcp .

bash

# 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

Tool	Cost	What it does
`get_stats`	free	Verdict, score and reason rollups over a rolling window. Start here.
`list_events`	free	Scored events, newest first, filterable by verdict or type, searchable by fingerprint or user id
`explain_event`	free	Every check that fired on one event, with the raw evidence
`triage_queue`	free	Everything on `review`, highest score first
`get_config`	free	Effective weights and thresholds for this tenant
`investigate_entity`	1 row¹	Enrichment, network reputation and related events for one entity
`check_email`	1 row	Disposable domain, deliverability, fraud score, abuse history
`check_ip`	1 row	Proxy, VPN, Tor, datacenter ASN, geo, abuse history
`check_phone`	1 row	Validity, line type, carrier, fraud score
`score_event`	1 row	Score a new event (also records it)

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

Mutating — require `--allow-writes`

Tool	What it does
`add_to_list`	Add an entity to the allow or block list
`label_outcome`	Report a confirmed fraud / chargeback / legit outcome

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.

You see	Meaning	Fix
`KAIDN_API_KEY is not set`	Server started without a key	Set it in the client's `env` block
`Kaidn error: 401 …`	Key rejected	Rotate or re-copy it from the dashboard
`Kaidn error: 429 …`	Rate limited	Slow down; per-key throttling is by the minute
`Session quota ceiling reached (100/100 …)`	The guard stopped an expensive run	Raise `KAIDN_MCP_MAX_QUOTA_CALLS` deliberately, or restart
`No event <id> in the most recent 200 events`	Event is older than the scan window	Page back with `list_events` using `offset`
`Supply exactly one of email, ip or device_id`	Ambiguous investigation	Ask about one entity at a time
`Refusing to bind <host> without authentication`	Non-loopback HTTP with no token	Set `KAIDN_MCP_HTTP_TOKEN`, or bind `127.0.0.1`

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:

bash

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

bash

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

Terminal

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:

bash

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

Kaidn MCP

Requirements

Getting started

Configuration

Transports

Streamable HTTP

Docker

Security

Tools

Read-only — available by default

Mutating — require --allow-writes

Worked examples

Morning triage

"Why was this customer blocked?"

Working outward from one signal

Checking a rule change before making it

Error handling

Troubleshooting

Support

Run from source

Why the evidence matters

Project

Licence

Mutating — require `--allow-writes`