Kaidn-mcp
OfficialKaidn MCP
用于 Kaidn 欺诈评分 API 的 Model Context Protocol 服务器。
用通俗语言调查欺诈——"这个注册为什么被拦截?"、"这个设备还接触过什么?"、"今天早上的审核队列里有什么?"
证据,而不仅仅是分数。 每条原因都附带其背后的原始数据,因此模型可以解释判定结果,而不是凭空猜测。
默认只读。 除非你主动选择,否则不会更改你的租户中的任何内容。
配额保护。 循环中的代理无法在十分钟内耗尽你一个月的配额。
任意客户端。 MCP 是开放协议——本地使用 stdio,远程和托管代理使用 Streamable HTTP。
环境要求
Node.js 18 或更高版本,以及来自你的 Kaidn 控制台 的 API 密钥。
快速开始
首先,在你的客户端中安装 Kaidn MCP 服务器。标准配置适用于大多数工具:
{
"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将标准配置添加到 claude_desktop_config.json,然后重启 Claude。设置 → 开发者 → 编辑配置即可打开该文件。
设置 → MCP → 添加新的 MCP 服务器,或将标准配置添加到项目中的 .cursor/mcp.json(或对所有项目使用 ~/.cursor/mcp.json)。
code --add-mcp '{"name":"kaidn","command":"npx","args":["@kaidn/mcp@latest"],"env":{"KAIDN_API_KEY":"your_key"}}'将标准配置添加到 ~/.codeium/windsurf/mcp_config.json。
通过 MCP 服务器图标 → 配置 MCP 服务器,将标准配置添加到 cline_mcp_settings.json。
在 settings.json 的 context_servers 下添加,使用与标准配置相同的命令、参数和环境变量。
任何 MCP 客户端都接受命令、参数和环境变量块。使用上面的标准配置。如果客户端只能通过网络访问服务器而无法启动进程,请参阅 Streamable HTTP。
Related MCP server: Maskbreak MCP Server
配置
选项 | 环境变量 | 默认值 | 用途 |
| 必填 | 你的密钥。仅限环境变量——绝不用作标志,绝不用作工具参数。 | |
|
| API 基础 URL | |
|
| 关闭 | 注册变更类工具 |
|
| 每个进程的配额上限 | |
|
|
| 提供 Streamable HTTP 服务 |
|
|
| HTTP 绑定地址 |
|
|
| HTTP 端口 |
| 未设置 | 要求 HTTP 请求携带 | |
| 显示用法 | ||
| 显示版本 |
优先级: CLI 标志覆盖环境变量。
API 密钥特意仅限环境变量。通过标志传递的密钥会泄露到进程列表和 shell 历史中。
传输方式
传输方式 | 适用场景 | 端点 |
stdio (默认) | 生成子进程的本地客户端 | — |
Streamable HTTP | 远程代理、容器、任何非本机场景 |
|
HTTP+SSE 被有意排除:在 2025-03-26 规范中已弃用,并于 2026 年 6 月停止服务。
Streamable HTTP
npx @kaidn/mcp@latest --http --port 8765无状态——每个请求都是全新的服务器,调用方之间不共享任何内容——因此它可以放在负载均衡器后面而不会出现意外。GET /health 无需认证,因此编排器可以在不持有令牌的情况下检查存活状态。
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多阶段构建,以非特权 node 用户运行,并带有健康检查。
安全
服务器持有你的 API 密钥。 任何能访问它的人都能消耗你的配额,因此默认设置是保守的,防护措施采用失败关闭而非仅发出警告。
绑定
127.0.0.1,并拒绝在更宽的接口上启动,除非设置了KAIDN_MCP_HTTP_TOKEN。它会附带说明停止,而不是悄悄暴露你的账户。默认只读。
add_to_list和label_outcome仅在启用--allow-writes时存在。set_config和forget_subject在任何模式下都不会暴露。前者会静默改变未来每个事件的判定结果;后者是不可逆的 GDPR 数据擦除。两者都应放在控制台中,由人工操作。每个进程有配额上限,每次计费响应都会报告剩余预算。会导致超额的预留请求会被直接拒绝,而不是部分执行。
密钥永远不会跨越工具边界——不会作为参数、不会出现在输出中、不会出现在错误中。
工具
每个工具都由两件事决定:是否消耗配额,以及是否更改任何内容。
只读——默认可用
工具 | 成本 | 功能 |
| 免费 | 滚动时间窗口内的判定、分数和原因汇总。从这里开始。 |
| 免费 | 已评分事件,最新优先,可按判定或类型筛选 |
| 免费 | 单个事件上触发的每项检查,附原始证据 |
| 免费 |
|
| 免费 | 当前租户的有效权重和阈值 |
| 1 行¹ | 单个实体的丰富信息、网络信誉和相关事件 |
| 1 行 | 一次性域名、可投递性、欺诈分数、滥用历史 |
| 1 行 | 代理、VPN、Tor、数据中心 ASN、地理位置、滥用历史 |
| 1 行 | 有效性、线路类型、运营商、欺诈分数 |
| 1 行 | 对新事件评分(同时记录该事件) |
¹ 当实体是 device_id 时免费;丰富信息仅在邮箱或 IP 上计费。
变更类——需要 --allow-writes
工具 | 功能 |
| 将实体添加到允许或阻止列表 |
| 报告已确认的欺诈 / 拒付 / 合法结果 |
实际示例
这些工具设计为可串联使用。以下是为它们构建的流程。
早晨审核
你: 昨晚发生了什么,有什么需要我处理的?
模型先调用 get_stats 了解过去 24 小时的整体情况,然后调用 triage_queue 查看处于 review 状态的事件,再对最严重的事件调用 explain_event。你会得到一个附带推理依据的排序列表,而不是一个仍需自己阅读的控制台。
"为什么这个客户被拦截?"
你: 事件
evt_8f21c——一位客户说他们被错误拦截了。
explain_event 返回触发的每项检查及其原始证据——匹配到的数据中心 ASN、共享该设备的账户数量、速度计数。足以回答客户的问题,或得出结论认为规则有误需要调整。
从单一信号向外扩展
你:
194.x.x.x是孤立事件还是团伙的一部分?
investigate_entity 返回该 IP 的丰富信息和网络信誉,以及它出现的每个近期事件。如果相同的设备 ID 反复出现,那就是团伙而非巧合。
在修改规则前先检查
你: 如果我降低速度权重,哪些内容将不再被拦截?
get_config 读取当前权重;使用 verdict: "block" 的 list_events 显示当前被捕获的内容。模型可以告诉你其中哪些依赖于你即将弱化的检查。
错误处理
失败以带可读消息的工具错误形式返回,而非异常——模型可以据此采取行动。
你看到的 | 含义 | 修复 |
| 服务器在未设置密钥的情况下启动 | 在客户端的 |
| 密钥被拒绝 | 从控制台轮换或重新复制 |
| 请求频率受限 | 放慢速度;按密钥的限流是按分钟计算的 |
| 防护机制阻止了一次昂贵的运行 | 有意提高 |
| 事件早于扫描窗口 | 使用 |
| 调查目标不明确 | 一次只询问一个实体 |
| 非回环 HTTP 且无令牌 | 设置 |
错误中永远不会包含你的 API 密钥。
故障排查
客户端不显示任何工具。
检查客户端的 MCP 日志中的启动行。stderr 上的 kaidn-mcp: ready (stdio, …) 表示服务器已启动,问题出在客户端。完全没有输出通常意味着 npx 无法解析包,或者 Node 版本低于 18。
它启动后立即退出。
几乎总是缺少 KAIDN_API_KEY。消息会在 stderr 上说明;有些客户端会隐藏 stderr,所以请在终端中运行以查看。
缺少 add_to_list 和 label_outcome。
按设计工作。它们需要 --allow-writes。
缺少 set_config 和 forget_subject。
同样按设计,且在任何模式下都不可用。请参阅 SECURITY.md。
HTTP 模式拒绝启动。 你在没有 bearer token 的情况下绑定了非回环地址。这是防护机制在起作用——进程持有你的 API 密钥。
一切都很慢。
富化检查会进行实时的上游调用。get_stats、list_events、explain_event 和 triage_queue 是免费且快速的;在读取历史记录时优先使用它们。
独立于客户端检查服务器:
node dist/index.js --help # no key required
KAIDN_API_KEY=your_key npm start # should print a ready line支持
错误和功能请求: GitHub issues
安全: security@kaidn.io — 参见 SECURITY.md
隐私与数据处理: PRIVACY.md
API 本身: kaidn.io
从源码运行
git clone https://github.com/Kaidn-io/kaidn-mcp.git
cd kaidn-mcp
npm install
npm run build
npm testclaude mcp add kaidn --env KAIDN_API_KEY=your_key -- node /absolute/path/to/kaidn-mcp/dist/index.js要检查它是否能在没有客户端的情况下启动:
KAIDN_API_KEY=your_key npm start它会向 stderr 打印 kaidn-mcp: ready (stdio, read-only, quota ceiling 100),然后等待 stdin——这就是 MCP 传输,所以静默是正确的。
为什么证据很重要
Kaidn 的引擎以规则为先且可解释:每个理由都带有其背后的原始数字。一个裸分数让模型无从推理,而带有证据的 checks[] 则让它有东西可解释。这就是 explain_event 有用与装饰性之间的区别。
规则决定。模型叙述。
项目
CONTRIBUTING.md — 这里包含什么,以及变更不得破坏的保证
SECURITY.md — 报告、威胁模型、已知限制
PRIVACY.md — 什么会经过、什么会被存储、什么不会
许可证
MIT
Available Tools
10 toolscheck_emailCheck an email addressA
Enrichment and in-network reputation for one email address: disposable/ throwaway domain, deliverability, fraud score, plus how often the address has been seen abusing other operators. Also returns canonical, the identity key: every alias that reaches one mailbox (+tags, gmail dot tricks, googlemail.com) collapses to the same string, so compare THAT across accounts to tell whether two signups are one person. is_aliased and alias_tricks say which trick was used, and reject_reason says why an address is unusable. Consumes one row of monthly quota.
Inputs: email (required).
check_ipCheck an IP addressA
Enrichment and in-network reputation for one IP: proxy/VPN/Tor, datacenter ASN, geo, fraud score, and cross-operator abuse history. Consumes one row of monthly quota.
Inputs: ip (required).
check_phoneCheck a phone numberA
Validity, line type, carrier and fraud score for one phone number. Consumes one row of monthly quota.
Inputs: phone (required), country.
explain_eventExplain why an event scored the way it didA
The 'why was this blocked?' tool. Returns the event with every check that fired, its weight, and the raw evidence behind it, so the reasoning can be narrated with receipts rather than guessed at. Free.
Inputs: event_id (required).
get_configGet scoring configurationA
This tenant's weight and threshold overrides plus the effective merged engine config. Free. Useful for explaining why a score landed where it did.
Inputs: no named parameters.
get_statsVerdict and reason rollupsA
Aggregate view over a rolling window: totals by verdict, average score and the most common reasons. Free — does not consume quota. Start here to see what changed before drilling into individual events.
Inputs: window_hours.
investigate_entityInvestigate an entity and the ring around itA
One call for what a fraud analyst actually wants. Returns enrichment for the entity, its reputation across the CROSS-OPERATOR abuse network (whether this email, IP or device has already burned other businesses, not just yours), and every recent event it appears in — which is how you get from one suspicious signup to the whole ring of accounts sharing its device, IP or inbox. Supply exactly one of email, ip or device_id. Enrichment consumes one row of monthly quota (device_id lookups are free).
Inputs: ip, email, limit, device_id.
list_eventsList scored eventsA
Scored events for this tenant, newest first. Free — does not consume quota. Filter by verdict or event type to narrow an investigation.
Inputs: event, limit, offset, verdict.
score_eventScore an eventA
Run an event through the scoring engine and get {score, verdict, reasons, checks}. When the event carries an email, the response also has an identity block whose email_canonical is the dedupe key for that address — so one call both scores the event and tells you whether the mailbox is one you have already seen. Consumes one row of monthly quota AND records an event — prefer the read-only tools when investigating history rather than testing new input.
Inputs: event (required), ip, email, phone, +3 more.
triage_queueReview queue, highest risk firstA
Every event sitting on the 'review' verdict, sorted by score descending — the daily triage job. Free.
Inputs: limit.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool has a clearly distinct purpose: check_email/check_ip/check_phone target different entity types, the read-only analytics tools (list_events, get_stats, get_config, explain_event, triage_queue) each serve a unique function, investigate_entity combines enrichment and history, and score_event is the only action that records an event. No two tools are easily confused.
All tool names follow a consistent verb_noun snake_case pattern (check_email, list_events, get_config, score_event, etc.). The verbs (check, list, get, explain, investigate, triage, score) clearly indicate the action, and the nouns (email, events, stats, config, entity, queue) indicate the resource.
10 tools is well within the ideal range for a fraud investigation MCP. Each tool covers a distinct need — enrichment, event browsing, stats, config, explanation, investigation, triage, and scoring — without unnecessary redundancy or bloat.
The tool set covers the full investigation lifecycle: enrichment for email/IP/phone/device, listing and triaging events, understanding scores via stats and config, explaining individual verdicts, investigating entity history, and testing new events. There are no obvious missing operations for the stated purpose.
Maintenance
Related MCP Connectors
Score an IP, email, phone, domain or device for fraud in one call, with the signals behind it.
Signup fraud checks: score emails and IPs, look up IPs and manage your blocklist.
Fraud risk score for signups and orders from email, IP, phone and user-agent
Verify companies, domains and counterparties before transacting. Sanctions, UBO, fraud scoring.
Related MCP Servers
- FlicenseAqualityDmaintenanceEnables real-time fraud detection and transaction analysis by integrating with Claude through MCP, providing tools to analyze transactions, flag suspicious activity, and manage fraud rules.9-
- AlicenseNot gradedqualityBmaintenanceEnables checking any IP address for VPN, proxy, Tor, datacenter hosting, anonymity, and fraud risk signals, plus API service status, directly from MCP-capable clients like Claude and Cursor.118 npm2MIT
- AlicenseAqualityBmaintenanceEnables AI agents to investigate synthetic fraud cases by pulling transactions, running deterministic rules evaluations, pivoting across devices, and recording auditable case files with provenance.4MIT
- AlicenseCqualityBmaintenanceEnables Claude Desktop, Cursor, and other MCP clients to inspect a Remnawave 3.x panel through natural-language chat, covering users, nodes, traffic, devices, connections, and GeoCheck, with tools generated from the official backend contract to match the panel version. Read-only by default and privacy-filtered, so secrets, keys, and client identifiers are hidden or replaced with aliases before reaching the chat.9125MIT