MCP 接入

从 v1.0.0 开始，Kaloscope 内置了 MCP 服务，方便你从外部 AI 客户端直接查媒体、管下载、编辑工作流草稿，或者在确认后调整各类任务。服务直接复用 Web 界面地址，不需要另外跑桥接进程，也不要求先配置内置模型提供商。

创建访问令牌

访问权限	可用范围
只读	读取当前账号有权访问的数据、工作流、日志和草稿，执行校验或预览变更
读写	在账号权限范围内编辑草稿、执行搜索或 HTTP 探测、试运行，以及提交确认后的任务与媒体变更

注意，读写令牌只能使用当前账号本来就有的权限，不会突破角色限制。像编辑草稿、HTTP 探测、试运行、查看模型提供商信息以及各类系统管理操作，依然只有管理员账号创建的令牌才能调用。

在支持 Streamable HTTP 传输和 Bearer 认证的 MCP 客户端里添加一条服务器配置：

配置项	值
传输协议	`Streamable HTTP`
MCP 地址	`http://127.0.0.1:8000/_api/mcp`（外部客户端请换成实际访问地址）
认证请求头	`Authorization: Bearer <token>`（将 `<token>` 替换为完整令牌）

启用 TLS 时协议记得改成 https；客户端和 Kaloscope 不在同一台机器上时，要把 127.0.0.1 换成实际的局域网 IP 或域名。如果客户端单独提供了 Bearer Token 输入框，直接填写令牌本身就行，不要再带 Bearer 前缀。

在令牌页面可以直接复制当前实例的地址和认证格式。连好之后建议先让客户端试一句「列出我能访问的媒体库」，确认地址、认证和权限都正常。

功能	说明
读取应用状态	查询媒体库与条目、下载任务与计划、工作流与日志、定时任务，以及管理员可见的模型连接信息
编写工作流	读取节点定义和编写参考，校验模板、预览修改，支持创建、保存草稿及从历史版本恢复
调试工作流	探测 HTTP 请求，试运行已保存草稿，并排查节点错误与输出
管理下载	调用已发布索引器搜索，校验后创建单次下载或下载计划，改删计划，暂停、恢复、重试或删除下载任务
管理定时任务	预览并确认创建、修改、暂停、恢复或删除工作流定时任务
影视库操作	预览并确认扫描、重新刮削，以及更改绑定的工作流、语言和重命名模板

影视库操作目前同样只支持电影和电视剧。另外，通过 MCP 查到的下载状态是 Kaloscope 本地保存的同步状态，可能会和下载器端即时进度有短暂延迟。

建议让外部客户端先读取目标对象和当前状态，检查清楚差异后再执行变更。保存草稿时系统会校验版本号，防止覆盖其他窗口刚保存的修改；如果改乱了，也可以把历史版本恢复成新草稿。出于安全考虑，MCP 暂不提供发布、删除工作流或强行取消正在运行工作流的工具。

搜索、HTTP 探测、刮削候选查询和试运行都会真实访问外部服务；试运行还可能执行脚本、文件写入和 AI 节点。哪怕前面的校验和预览都通过了，也不代表实际执行一定不出错。

对于下载、计划、定时调度和媒体变更，MCP 工具都配有「先预览、再确认」的步骤。如果执行后提示结果待确认，可以让客户端再去查一下同一次请求的结果，或直接去对应页面查看状态，不要连续发起重复请求；任务进入「已排队」状态后，也记得去后台或页面上确认最终执行结果。

在令牌列表里能看到每个令牌的到期时间和最近使用时间。删掉令牌后，持有它的客户端就会立刻失去访问权限；如果不小心弄丢了完整令牌，删掉重建一个即可。