Kaidn

Kaidn MCP

面向 Kaidn 欺诈评分 API 的 Model Context Protocol 服务。

用日常语言调查欺诈——“为什么这次注册被拦截了？”、“这个设备还关联过什么？”、“今天早上的审核队列里有什么？”

• 提供证据，而不只是评分。 每条原因都附带背后的原始数据，让模型能够解释判定，而不是猜测。
• 默认只读。 除非你主动启用，否则不会对你的租户做任何更改。
• 配额保护。 Agent 即使陷入循环，也无法在 10 分钟内耗尽你整个月的配额。
• 支持任何客户端。 MCP 是开放协议——本地使用 stdio，远程和托管 Agent 使用 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

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

配置

优先级： CLI 标志优先于环境变量。

API 密钥特意限制为仅通过环境变量设置。将密钥作为标志传入会使其出现在进程列表和 shell 历史记录中。

传输方式

特意不提供 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，否则拒绝在更宽泛的网络接口上启动。 它会停止运行并说明原因，而不会悄悄暴露您的账户。
• 默认只读。 只有启用 --allow-writes 后，才会提供 add_to_list 和 label_outcome。
• 任何模式下都不会公开 set_config 和 forget_subject。 前者会静默更改所有未来事件的判定；后者会执行不可逆的 GDPR 数据擦除。两者都应在有人工参与的情况下通过控制面板操作。
• 每个进程都设有配额上限，每次计费响应都会报告剩余额度。若预留配额会超出上限，请求将被直接拒绝，不会部分扣费。
• 密钥绝不会跨越工具边界——不会作为参数传递、不会出现在输出中，也不会出现在错误信息里。

工具

每个工具都受两个因素约束：是否消耗配额，以及是否会更改内容。

只读——默认可用

¹ 实体为 device_id 时免费；只有查询邮箱或 IP 时才会产生补充信息费用。

会修改数据——需要 --allow-writes

使用示例

这些工具旨在串联使用。以下是它们专为实现的工作流。

早间分诊

你： 昨晚发生了什么？有什么需要我处理？

模型会调用 get_stats 查看过去 24 小时的整体情况，然后调用 triage_queue 查看待审核的事件，最后对最严重的一起调用 explain_event。 你会得到一份附有推理依据的排序列表，而不是还需要你自行查看的仪表板。

###“为什么这个客户被拦截了？”

你： 事件 evt_8f21c——一位客户称自己被错误拦截。

explain_event 会返回触发的所有检查及其原始证据，包括匹配到的数据中心 ASN、共用该设备的账户数以及速率计数。信息足以回复客户，也足以判断规则是否有误、是否需要调整。

从一个信号向外调查

你： 194.x.x.x 是个例，还是某个团伙的一部分？

investigate_entity 会返回该 IP 的补充信息和网络信誉，以及其中出现过的所有近期事件。如果同一设备 ID 反复出现，那就是一个团伙，而非巧合。

修改规则前进行检查

你： 如果降低速率权重，哪些内容将不再被拦截？

get_config 会读取当前权重；使用 verdict: "block" 调用 list_events，可以查看当前拦截的事件。模型可以告诉你，其中哪些事件依赖于你即将弱化的检查。

错误处理

失败会以带有易读消息的工具错误形式返回，而非异常，因此模型可以据此采取行动。

错误中绝不会包含你的 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 模式拒绝启动。 你绑定的地址不是回环地址，且未提供承载令牌。这是防护机制在发挥作用——该进程持有你的 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

支持

• Bug 和功能请求： GitHub 问题
• 安全： [email protected] — 请参阅 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 test

claude 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 — 哪些内容会经过、哪些会存储、哪些不会
• CODE_OF_CONDUCT.md

许可证

MIT