Skip to Content

MCP 端点

IronFlock 是一个 MCP 服务器。Claude 以及任何支持 Model Context Protocol 的其他客户端,都可以在您的 API 密钥允许的范围内,列出您的项目,读取其中的设备、应用和数据,并使用 IronFlock 提供的工具对它们进行操作。该端点与 REST API 属于同一个 API 服务,并使用相同的 API 密钥。

地址与身份认证

IronFlock 云端的 URLhttps://api.ironflock.com/mcp
Appliance 上的 URLhttps://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 选项卡中使用。

  1. 在 Claude Code 会话中添加插件市场并安装插件:

    /plugin marketplace add IronFlock/agent-skills /plugin install ironflock@ironflock
  2. 安装时会打开一个包含两项设置的对话框。IronFlock API address 对于云端是 https://api.ironflock.com,对于 Appliance 是 https://api. 加上 Appliance 的域名,两种情况下都不带 /mcp,末尾也不带斜杠。IronFlock API key 是来自 Studio 的密钥。Claude Code 将其保存在系统的安全凭据存储中,而不是设置文件中。

  3. 重启 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 可以正常使用。

  1. 打开 Customize > Connectors,选择 Add,然后选择 Add custom connector。
  2. 输入名称 IronFlock 和服务器 URL https://api.ironflock.com/mcp。
  3. 将 Authentication 设置为 No sign-in。
  4. 在 Request headers 下,添加请求头 Authorization,值为 Bearer 加上您的密钥:即单词 Bearer、一个空格,然后是密钥。没有 Bearer 时,IronFlock 会拒绝请求。
  5. 选择 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_projectsdevices:read列出密钥可以使用的项目

设备

工具权限范围作用
list_devicesdevices:read列出项目的设备、每个设备上安装的应用、它们是否在运行以及设备是否在线
create_devicedevices:write在项目中创建一个设备,并返回其键和名称
delete_devicedevices:write从项目中永久删除一个设备

项目中的应用

工具权限范围作用
list_project_appsapps:read列出项目中安装的应用,以及每个应用在多少台设备上运行
check_app_statusapps:read显示应用是否在其设备上运行,以及其数据是否到达
install_appapps:write将应用商店中的应用安装到项目中,并可选择安装到设备上
set_app_stateapps:write在设备上启动或停止已安装的应用
update_appapps:write将已安装的应用更新到其最新发布版本
uninstall_appapps:write从设备或整个项目中移除应用

应用商店与费用

工具权限范围作用
search_appsapps:read按功能搜索应用商店,并返回匹配的应用及其价格
get_app_detailsapps:read读取一到三个商店应用的描述、README 和价格
get_install_quoteapps:read查询安装某个应用的费用以及会阻止安装的因素
estimate_project_costapps:read估算一种项目配置的年度费用;不会购买任何东西
sync_app_to_storeapps:write仅限 Appliance:将 IronFlock 云端商店中的应用复制到 Appliance 自己的商店中

数据

工具权限范围作用
get_schemadata:read描述项目的数据库:其表、视图和列
execute_sqldata:read在项目的数据库上运行一个只读的 SELECT 查询
list_dashboardsdata:read列出项目的仪表板
list_app_filesdata:read列出并搜索应用在项目中存储的文件
read_app_filedata:read读取应用存储的一个文件:文本、图像或其他文件
save_transformdata:write创建或替换一个自定义转换,为仪表板实时保持一个派生数值
delete_transformdata:write永久删除一个自定义转换

告警

工具权限范围作用
list_alarmsalarms:read列出项目的告警及其状态、触发条件和接收人
create_alarmalarms:write创建一个监视应用数据表的告警
update_alarmalarms:write更改告警的触发条件或接收人,或暂停和恢复告警
delete_alarmalarms:write永久删除一个告警及其历史记录

日志与审计日志

工具权限范围作用
get_app_logslogs:read从应用运行所在的设备上读取应用自身的日志输出
get_device_logslogs:read读取设备自身一直在做的事情:应用、下载、磁盘、网络、代理程序更新
query_audit_loglogs:read在审计日志上运行一个只读查询:谁在何时更改了项目、其设备、设备组和应用
get_appliance_healthdevices:read仅限 Appliance:检查 Appliance 自身平台服务、磁盘、内存、许可证和更新的状态
get_appliance_logslogs:read仅限 Appliance:读取 Appliance 平台某个组成部分的日志

应用工具

应用随其 AI 智能体带来自己的工具:在设备上运行的应用函数,例如读取机器的状态或更改某项设置。有两个工具可以访问它们。

工具权限范围作用
list_app_toolsapptools:call列出已安装应用的工具,包括其参数以及应用智能体的说明
call_app_toolapptools: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 将要更改的内容。
  • 组织共享的连接器对其所有用户使用同一个密钥。请使用一个只能看到所有这些用户都可以看到的内容的帐户的密钥。
Last updated on