MCP 端点
IronFlock 是一个 MCP 服务器。Claude 以及任何支持 Model Context Protocol 的其他客户端,都可以在您的 API 密钥允许的范围内,列出您的项目,读取其中的设备、应用和数据,并使用 IronFlock 提供的工具对它们进行操作。该端点与 REST API 属于同一个 API 服务,并使用相同的 API 密钥。
地址与身份认证
| IronFlock 云端的 URL | https://api.ironflock.com/mcp |
| Appliance 上的 URL | https://api. 加上 Appliance 的域名,再加上 /mcp;前提是 Appliance 运行 IronFlock API 服务 |
| 传输方式 | Streamable HTTP |
| 身份认证 | Authorization: Bearer <your API key> |
按照创建 API 密钥中的说明在 Studio 中创建 API 密钥。每个请求都携带该密钥。没有密钥的请求,或密钥无效(已删除、已过期或来自另一个 IronFlock)的请求,会得到 HTTP 401。服务器不提供通过浏览器登录(OAuth):密钥是唯一的访问方式。
服务器不保留会话。每个请求都单独应答,因此客户端可以自由地连接、断开和重新连接。它对每个请求都以一个 JSON 正文应答,没有可供监听的事件流。
连接 Claude
密钥由您自己在 Claude 自身的设置中输入。绝不要将其粘贴到对话中。
Claude Code
Claude Code 通过 ironflock 插件连接,该插件声明了 IronFlock 的 MCP 服务器。它可以在终端、IDE 扩展以及 Claude 桌面应用的 Code 选项卡中使用。
-
在 Claude Code 会话中添加插件市场并安装插件:
/plugin marketplace add IronFlock/agent-skills /plugin install ironflock@ironflock -
安装时会打开一个包含两项设置的对话框。IronFlock API address 对于云端是
https://api.ironflock.com,对于 Appliance 是https://api.加上 Appliance 的域名,两种情况下都不带/mcp,末尾也不带斜杠。IronFlock API key 是来自 Studio 的密钥。Claude Code 将其保存在系统的安全凭据存储中,而不是设置文件中。 -
重启 Claude Code。之后
/mcp会将服务器plugin:ironflock:ironflock列为已连接。
以后可以使用 /plugin configure ironflock@ironflock 更改设置,然后重启 Claude Code。在设置密钥之前,服务器不会启动。从 shell 安装(claude plugin install)不会打开该对话框,因此请在会话中使用 /plugin configure ironflock@ironflock 完成设置。使用 Claude Code 构建应用介绍了这些插件及其技能。
网页版、桌面版和手机版 Claude,以及 Cowork
插件自身的连接只适用于 Claude Code。在 Claude 应用的聊天和 Cowork 中,您需要将 IronFlock 作为自定义连接器添加一次,并将密钥作为请求头。自定义连接器上的请求头是一项 Beta 功能,仅向部分组织开放。如果下面的对话框中没有 Request headers 部分,说明您的组织尚未获得该功能,目前无法在那里连接 IronFlock:Claude Code 可以正常使用。
- 打开 Customize > Connectors,选择 Add,然后选择 Add custom connector。
- 输入名称
IronFlock和服务器 URLhttps://api.ironflock.com/mcp。 - 将 Authentication 设置为 No sign-in。
- 在 Request headers 下,添加请求头
Authorization,值为Bearer加上您的密钥:即单词 Bearer、一个空格,然后是密钥。没有Bearer时,IronFlock 会拒绝请求。 - 选择 Add。
在 Team 和 Enterprise 套餐中,由所有者在 Organization settings > Connectors 下依次选择 Add 和 Custom 来添加连接器;请求头可能位于 Advanced 下。使用该连接器的每个人都以所有者输入的那一个密钥行事,因此只为它授予所有这些人都可以使用的权限范围和项目。
连接器的请求头无法编辑:要更换密钥,请移除连接器并重新添加。连接器从 Anthropic 的服务器发起连接,因此该地址必须能从互联网访问。云端满足这一条件。只能从您公司网络访问的 Appliance 通常无法在那里连接,而该网络中计算机上的 Claude Code 可以连接。
其他 MCP 客户端
任何支持 Streamable HTTP 和请求头的客户端,都可以使用该 URL 和请求头 Authorization: Bearer <your API key> 进行连接。请勿将密钥放入您共享或提交的文件中。
检查连接
让 Claude 列出您的 IronFlock 项目,然后列出其中一个项目的设备。Claude 会调用 list_projects 和 list_devices,它们只读取数据。
工具
服务器在以下领域提供 33 个工具。其中大多数在一个项目中工作,并接受该项目的 swarm_key,它由 list_projects 提供。更改或删除内容的工具会被如此标记,以便 Claude 等客户端可以在调用之前征求您的同意。
项目
| 工具 | 权限范围 | 作用 |
|---|---|---|
list_projects | devices:read | 列出密钥可以使用的项目 |
设备
| 工具 | 权限范围 | 作用 |
|---|---|---|
list_devices | devices:read | 列出项目的设备、每个设备上安装的应用、它们是否在运行以及设备是否在线 |
create_device | devices:write | 在项目中创建一个设备,并返回其键和名称 |
delete_device | devices:write | 从项目中永久删除一个设备 |
项目中的应用
| 工具 | 权限范围 | 作用 |
|---|---|---|
list_project_apps | apps:read | 列出项目中安装的应用,以及每个应用在多少台设备上运行 |
check_app_status | apps:read | 显示应用是否在其设备上运行,以及其数据是否到达 |
install_app | apps:write | 将应用商店中的应用安装到项目中,并可选择安装到设备上 |
set_app_state | apps:write | 在设备上启动或停止已安装的应用 |
update_app | apps:write | 将已安装的应用更新到其最新发布版本 |
uninstall_app | apps:write | 从设备或整个项目中移除应用 |
应用商店与费用
| 工具 | 权限范围 | 作用 |
|---|---|---|
search_apps | apps:read | 按功能搜索应用商店,并返回匹配的应用及其价格 |
get_app_details | apps:read | 读取一到三个商店应用的描述、README 和价格 |
get_install_quote | apps:read | 查询安装某个应用的费用以及会阻止安装的因素 |
estimate_project_cost | apps:read | 估算一种项目配置的年度费用;不会购买任何东西 |
sync_app_to_store | apps:write | 仅限 Appliance:将 IronFlock 云端商店中的应用复制到 Appliance 自己的商店中 |
数据
| 工具 | 权限范围 | 作用 |
|---|---|---|
get_schema | data:read | 描述项目的数据库:其表、视图和列 |
execute_sql | data:read | 在项目的数据库上运行一个只读的 SELECT 查询 |
list_dashboards | data:read | 列出项目的仪表板 |
list_app_files | data:read | 列出并搜索应用在项目中存储的文件 |
read_app_file | data:read | 读取应用存储的一个文件:文本、图像或其他文件 |
save_transform | data:write | 创建或替换一个自定义转换,为仪表板实时保持一个派生数值 |
delete_transform | data:write | 永久删除一个自定义转换 |
告警
| 工具 | 权限范围 | 作用 |
|---|---|---|
list_alarms | alarms:read | 列出项目的告警及其状态、触发条件和接收人 |
create_alarm | alarms:write | 创建一个监视应用数据表的告警 |
update_alarm | alarms:write | 更改告警的触发条件或接收人,或暂停和恢复告警 |
delete_alarm | alarms:write | 永久删除一个告警及其历史记录 |
日志与审计日志
| 工具 | 权限范围 | 作用 |
|---|---|---|
get_app_logs | logs:read | 从应用运行所在的设备上读取应用自身的日志输出 |
get_device_logs | logs:read | 读取设备自身一直在做的事情:应用、下载、磁盘、网络、代理程序更新 |
query_audit_log | logs:read | 在审计日志上运行一个只读查询:谁在何时更改了项目、其设备、设备组和应用 |
get_appliance_health | devices:read | 仅限 Appliance:检查 Appliance 自身平台服务、磁盘、内存、许可证和更新的状态 |
get_appliance_logs | logs:read | 仅限 Appliance:读取 Appliance 平台某个组成部分的日志 |
应用工具
应用随其 AI 智能体带来自己的工具:在设备上运行的应用函数,例如读取机器的状态或更改某项设置。有两个工具可以访问它们。
| 工具 | 权限范围 | 作用 |
|---|---|---|
list_app_tools | apptools:call | 列出已安装应用的工具,包括其参数以及应用智能体的说明 |
call_app_tool | apptools:call | 在项目的一台设备上运行其中一个工具 |
call_app_tool 在设备上运行,应用的工具可能会在设备上更改内容。该设备必须是项目中密钥所有者可以看到的设备之一,并且所有者需要有权使用该应用的数据,就像从其仪表板操作该应用时一样。应用得到的恰好是给定的参数,没有其他内容。只列出已安装发布版本的工具,不列出应用开发版本的工具。工具的文本由应用的开发者编写,并会被截断到固定长度。
权限范围
每个工具都需要上面表格中所示的那一个权限范围。服务器只向客户端提供密钥可以使用的工具,并像其他工具不存在一样拒绝它们。无论密钥允许什么,工具都绝不会超出密钥所有者在 IronFlock 中可以做的事。releases:publish 没有对应的工具:它用于构建发布版本的 REST 操作。全部权限范围参见权限范围,如何在 Studio 中选择它们参见创建 API 密钥。
限定于项目的密钥只能看到这些项目。限定于一个应用的密钥只会获得为应用行事的工具,因此没有 list_projects。两者都不会获得超出单个项目范围的工具:query_audit_log,其查询可以指向所有者可读的任何项目的资产;两个 Appliance 工具,它们不属于任何项目;以及 sync_app_to_store,它会为所有人更改 Appliance 的商店。
部分工具带有额外的规则:
install_app接受向您展示过的get_install_quote的结果;如果此后该报价的价格或其他任何内容发生了变化,它不会安装任何东西。安装付费应用需要花钱。set_app_state和update_app一次调用最多更改 10 台设备。create_device返回新设备的键和名称,绝不返回其配置文件,因为该文件包含设备的凭据。请在 Studio 中设备设置的 设备维护 > 设备配置文件 > 下载配置文件 下载该文件,或者在机器上使用ironflock agent install --project <project> --name <name>设置设备,该命令会创建设备并将文件保留在机器上(登录与设备管理)。- 一个项目一次只保存一个自定义转换。第一个
save_transform运行期间,第二个会被拒绝。 - 一个帐户一次只能运行一个
query_audit_log,每分钟最多六次,因为其背后的数据库是共享的。 - 在调用时间内未完成的更改仍可能生效。结果会如此说明,工具不会重复该更改。
结果
结果是 JSON,既作为结构化内容,也作为文本块中的同一段 JSON。长列表会被截断以适应 50,000 个字符,其 cut 成员会说明省略了多少条目以及如何继续读取。图像(PNG、JPEG、GIF 和 WebP)以图像形式返回,其他文件(例如 PDF)以带有媒体类型的嵌入资源形式返回。
当工具无法完成请求时,其结果会被标记为错误,并用一句话说明原因,例如项目不存在,或平台未及时响应。
限制
以下是每个 API 密钥的默认值:
| 限制 | |
|---|---|
| 请求 | 每分钟 120 个,突发最多 30 个 |
| 同时打开的请求 | 8 个 |
| 请求体 | 1,114,112 字节:1 MiB 的参数加上其外围的消息 |
| 一次工具调用 | 90 秒 |
| 一次数据库查询 | 30 秒;除非您要求更多,execute_sql 返回 100 行,最多 1,000 行 |
| 一个结果 | 50,000 个字符;call_app_tool 的结果在 45,000 处截断 |
错误
| 响应 | 含义 | 处理方法 |
|---|---|---|
401 | 密钥缺失、输入错误或被截断、已删除、已过期,或来自另一个 IronFlock。在连接器中,可能缺少 Bearer | 在您要连接的 IronFlock 的 Studio 中创建一个新密钥,然后重新输入 |
/mcp 上的 404 | 地址中出现了两次 /mcp,或者实例尚未提供该端点,例如未运行 IronFlock API 服务的 Appliance | 修正地址;否则请使用云端 |
405 | 对 /mcp 使用了 GET 和 DELETE:服务器没有事件流,也没有可结束的会话 | 使用 POST |
413 | 请求体过大 | 一次调用中发送更少的内容 |
429 | 密钥发出的请求过多,或同时打开的请求过多。Retry-After 头说明需要等待多少秒 | 等待相应时间,然后以更少的并发调用继续 |
503 | 平台暂时不可用,或服务正在关闭 | 一分钟后重试 |
504 | 平台未及时响应 | 一分钟后重试 |
无法完成请求的工具不会以 HTTP 错误应答:其结果会被标记为错误,并用一句话说明出了什么问题。
保护好您的密钥
- 绝不要将密钥粘贴到对话中。如果已经这样做了,它就成为了该对话的一部分:请在 Studio 中删除该密钥,创建一个新密钥,并在设置中输入它。
- Studio 只在创建新密钥时显示一次。请立即将其保存到客户端的设置中。
- 为每个使用它的地方使用一个密钥,这样删除其中一个时不会影响其他密钥;不再使用的密钥请删除。密钥的有效期为一年。
- 只为密钥授予 Claude 所需的权限范围和项目:在 我的所有项目 中可以做 全部 操作的密钥,会让 Claude 可以做您在 IronFlock 中能做的任何事。更改或删除内容的工具会被如此标记,以便 Claude 等客户端可以先征求您的同意。在您同意之前,请阅读 Claude 将要更改的内容。
- 组织共享的连接器对其所有用户使用同一个密钥。请使用一个只能看到所有这些用户都可以看到的内容的帐户的密钥。