@ centrali-io/ centrali- mcp

Centrali平台的MCP(模式上下文协议)服务器. 让AI助手(Claude,Cursor等)与Centri工作空间互动——查询数据,管理记录,搜索,触发函数,检查执行结果,构建管弦乐,等等.

完整文档: (原始内容存档于2018-09-29) (英语). docs.centeri.io ——SDK向导,API参考,计算函数,管弦乐等等.

文件上传

提供主机和Stdio服务器 upload_file。它上传一个独立的存储器 通过现有的SDK和存储 API,使用认证的工作空间 及其现有的文件夹权限。 节点(Node.js 22)或更新的需要为stdio.

{
  "filename": "hello.txt",
  "contentType": "text/plain",
  "contentEncoding": "utf8",
  "content": "Hello from MCP"
}

用于二进制文件 contentEncoding: "base64" 以警犬加固基座64 (没有数据 URL 前缀或白空). 解码限制是 256基贝,包括: 文本的 UTF-8 字节长度 。 支持空文件 。 连载 content JSON弦还有一个 768 基贝 所以JSON离开 空间在 主机服务器的 1 MB 请求限制 。 对于重逃的文本( 如控件) 字符),将准确的UTF-8字节编码为base64. location 默认为 /root/shared; 自定义文件夹 必须已经存在。 文件是私有的,除非 isPublic: true 明确设置. 公共上传只允许 PNG, JPEG, GIF, WebP, 纯文本, JSON, MPEG/OGG/ WAV 音频,以及MP4/WebM视频MIME类型. HTML、SVG、XML 和其他活动文档 类型不能通过此工具公开, 因为存储服务 在 API 来源上提供了 MIME 类型 。 私人上传保留支持 用于任意的 MIME 类型。 SDK 前缀在工作空间中存储文件名 和时间戳.

结果包含 renderId, (中文(简体) ), sizeBytes, (中文(简体) ), contentType, (中文(简体) ), isPublic, (中文(简体) ), renderUrl 财务报告和审定财务报表 downloadUrl。私人 URL 仍然需要正常的认证。 附上 返回时使用单独的记录更新渲染 ID; 附件失败离开 存储中上传的文件。 重复上传可以创建另一个文件.

该工具接受客户端提供的内容. 它不能读取本地路径, 获取源代码 URL,或访问隐藏的聊天附件/生成的图像 主持人。 永远不要通过模型复制重建图像字节. 更大的文件 比起256 KiB,必须使用现有的SDK/HTTP多段上传API.

连接选项

备选案文1:主机MCP服务器(建议)

将任何AI客户端连接到Centrali的最简单方式. 添加一个单一的URL——认证通过OAuth在浏览器中发生.

Claude桌面 / Claude 代码/ 光标 :

{
  "mcpServers": {
    "centrali": {
      "type": "url",
      "url": "https://mcp.centrali.io"
    }
  }
}

首先使用时,您的AI客户端打开浏览器进行登录和工作空间选择. 不需要客户身份 秘密或工作空间的子弹.

备选案文2:带有服务账户的系统(CI/自动化)

对于无头环境(CI管线,自动化脚本,cron jobs),浏览器无法登录. 使用有RBAC权限的服务账户证书.

{
  "mcpServers": {
    "centrali": {
      "command": "npx",
      "args": ["@centrali-io/centrali-mcp"],
      "env": {
        "CENTRALI_URL": "https://centrali.io",
        "CENTRALI_CLIENT_ID": "<service-account-client-id>",
        "CENTRALI_CLIENT_SECRET": "<service-account-secret>",
        "CENTRALI_WORKSPACE": "my-workspace"
      }
    }
  }
}

从 OAuth stdio 迁移到主机

如果你之前使用过 CENTRALI_OAUTH_CLIENT_ID 与 stdio 软件包一起,切换到主机 URL :

1. 删除旧的 command编号 :args编号 :env 配置
2. 替换为: { "type": "url", "url": "https://mcp.centrali.io" }
3. 下次连接时, 在浏览器中认证

环境变量(仅限astio模式)

服务账户权限

新创建的服务账户 默认没有权限。在 MCP 服务器做任何有用的事情之前, 您必须指定它的角色, 否则每个工具呼叫都会返回 403 Forbidden。 。 。 .

最快的设置——全管理员访问:

1. 在指挥台,去 设置 > 服务账户
2. 创建您的服务账户并保存客户端秘密
3. 打开服务账户,转到 组 选项卡
4. 把它加进 工作空间( a) 组

最低特权设置: 创建自定义组,其策略范围设定为您需要的资源 。 见 政策和权限指南 详细情况.

开始

连接后, 拨打 describe_centrali 首先——它返回全能映射,特征矩阵,和SDK集成指导. 然后使用特定 describe_* 用于任何域的更深层次计划细节的工具.

可用工具

发现(先叫这些)

收款

记录

计算

已保存的查询

已保存的查询存储库 QueryDefinition 加可选变量和可选多集 joins[] 条款.

已键入参数发现 ~ 执行. 使用已键入参数编写的已保存的查询通过参数形状曝光 describe_saved_queries (schema参考)和 get_saved_query 编号 : list_saved_queries (逐行数) variables 声明)。 预期发现时执行流量 :

1. 发现计划 (一发 describe_saved_queries 返回时 QueryVariableDefinition 形状( e)type, (中文(简体) ), required?, (中文(简体) ), default?, (中文(简体) ), description?和受支助者 VariableType 工会string | number | boolean | datetime | id | { array: T } | { reference: collectionSlug }) (中文(简体) ).
2. 发现查询 —— 说 get_saved_query 返回包含 variables。读取每个条目以学习什么是束缚。 犬类反应包括: queryDefinition.resource (总是等于行 recordSlug:

   {
     "id": "…",
     "name": "Monthly revenue",
     "recordSlug": "orders",
     "queryDefinition": {
       "resource": "orders",
       "where": { "and": [
         { "data.month": { "eq": "${month}" } },
         { "data.region": { "eq": "${region}" } }
       ]},
       "sort": [{ "field": "data.amount", "direction": "desc" }],
       "page": { "limit": 100 }
     },
     "variables": {
       "month":  { "type": "datetime", "required": true, "description": "Month bucket (UTC)" },
       "region": { "type": "string",   "required": true }
     }
   }
   

3. 已执行 - 通过 execute_saved_query是因为 variables rg. 服务器对照其声明的类型验证每个值( 不强制 ) - "123" 将不接受 number ,然后替换. datetime 接受 ISO-8601 字符串 :

   {
     "recordSlug": "orders",
     "queryId": "…",
     "variables": { "month": "2026-04-01T00:00:00Z", "region": "us-east" }
   }
   

   输入错误表面为 variable_type_mismatch, (中文(简体) ), missing_required_variable,或 extra_variable未类型(遗留)行有 variables: null ,并接受任何密钥;在替换前,数值会被字符串。 未打入的倒置也由后填行取取出(canonical body,尚未声明),直到作者推广.

多边方案 test_saved_query 工具故意这样做 没有 曝光 variableDeclarations ——它的干燥路径又回到了遗留的字符串替代,不执行打出的声明. 绕行 create_saved_query + 键 execute_saved_query 以验证输入参数的端到端.

多收相会入. 保存的查询支持可选 joins[] 条款 queryDefinition (最多4个条目). 每个条目加入另一个集合到主记录集中:

{
  "resource": "orders",
  "where": { "data.status": { "eq": "open" } },
  "joins": [
    {
      "foreignSlug": "customers",
      "localField": "data.customerId",
      "foreignField": "id",
      "joinType": "left",
      "select": ["id", "data.name", "data.email"],
      "alias": "customer"
    }
  ],
  "sort": [{ "field": "createdAt", "direction": "desc" }],
  "page": { "limit": 50 }
}

制约因素(经 @centrali/query:

• joinType 必须是 'inner' 或者说 'left' —— 说 'right' 财务报告和审定财务报表 'full' 被执行人拒绝 unsupported_clause。 。 。 .
• text 财务报告和审定财务报表 joins 无法在同一查询中显示( n)unsupported_combination) (中文(简体) ).
• 别名( 或隐含) foreignSlug在其中必须是独一无二的 joins[] (单位:千美元)duplicate_join_alias) (中文(简体) ).
• 4个条目的封顶( C)joins_length_exceeded) (中文(简体) ).
• localField 可使用 <priorAlias>.<field> 通过先前的化名将一个加入物链起来.

execute_saved_query 返回时 { rows, meta, fields }。每个条目 rows 在顶层下携带关联数据 _joined 键 :

{
  "rows": [
    {
      "id": "order-123",
      "data": { "status": "open" },
      "_joined": {
        "customer": { "id": "cust-1", "data": { "name": "Acme" } }
      }
    }
  ],
  "meta": { "limit": 50, "offset": 0, "total": 1 },
  "fields": [{ "name": "id" }, { "name": "data" }, { "name": "_joined" }]
}

LEFT 加入表面 null 用于无与伦比的行.

授权(SECURITY DEFINER,锁入2026-05-04). 保存的查询是作者绑定的 —— AUTHOR 权限定义查询可以读取的内容; 执行者只需要一个 execute 运行时检查保存的- query 资源 .

• 作者时间 (单位:千美元)create_saved_query 编号 : update_saved_query 编号 : test_saved_query:呼叫者必须坚持 records:list 主要收藏品和每份参考文献 joins[]。如果缺少任何访问,数据服务返回403.
• 执行时间 (单位:千美元)execute_saved_query: 仅限 execute 在保存的-query资源上检查;没有每次收集的再检查,并且字段级的编辑遵循了作者的权限,而不是执行者的权限。 秘密伪装仍然无条件适用.

AI 助手不应针对收藏提出保存的查询(或加入链条) 作者 无法读取 —— 执行会成功给不太特权的呼叫者,但作者会失败.

保留条款. 拒绝保存- query 创建/ 更新/ 测试表面 text (全文搜索)和 include (关系扩大)422 unsupported_clause这些条款可在特设委员会上查阅 POST /records/query 表面 – 不要作者保存使用它们的查询 .

警报

在 cron 上运行保存的查询,并在结果满足条件时通知人们.

条件. 今天有两艘船.. { kind: 'rowCount', op, value } (单位:千美元)op 一个 eq编号 :neq编号 :gt编号 :gte编号 :lt编号 :lte和 { kind: 'rowsChanged' },当行数与前一次评价不同时会起火,并且不会在第一次运行时起火(它只会给基线投下种子). 没有 aggregate 类型 : 提醒原因, 说明有多少行返回, 而不是总和或平均内容。 要在集合上提醒, 编写保存的查询, 从而返回行 为: 例外设置和提醒 rowCount。 。 。 .

日程安排. cronExpression 是一个5-字段克龙表达式,在 timezone (IANA名称,默认) UTC) (中文(简体) ). 通知被节制到每个接收者每15分钟1个警报,所以一个分15分钟的克龙比它所能通知的更频繁的评价.

受取者. recipients 这是一份明确的清单—— [{ type: 'user', id: '<userId>' }] - 不是订阅名单。 没有 MCP 工具列出工作空间用户,所以一个助手必须向用户询问ID而不是构建它们.

绑定变量——比执行更严格. 如果保存的查询宣布参数,请通过 variables。服务器在创建和提交时验证地图,并需要 每次声明查询机构引用没有 default,无论 required数字 :

{
  "savedQueryId": "…",
  "name": "Failed payments spiked",
  "cronExpression": "0 * * * *",
  "condition": { "kind": "rowCount", "op": "gt", "value": 10 },
  "recipients": [{ "type": "user", "id": "…" }],
  "variables": { "status": "failed" }
}

execute_saved_query 接受无约束的可选选项并留下原始 ${name} ;然后在字面占位符上过滤,不匹配,并报告没有出错。 互动可见——呼叫者看到空出结果. 所以警报不会开火 lastEvaluatedAt 继续前进,好像健康。 写作是最后一点 差距是显著的, 所以它失败了 在那里一个400 命名每个违法的变量.

诊断"它从来没有发射". get_alert 曝光情况 lastEvaluatedAt, (中文(简体) ), lastTriggeredAt, (中文(简体) ), lastRowCount,以及卫生领域 consecutiveFailures, (中文(简体) ), lastError, (中文(简体) ), lastErrorAt。 。 。 .

检查 consecutiveFailures 先说 非零表示警报后所保存的查询是出错的,因此警报是预定和启用的,但不能开火; 2; lastError 带着消毒的理由 lastErrorAt 当它最后一次发生。 最常见的原因是从查询下重新命名的集合或字段. 计数器是一个运行长度,在第一次成功评价时重置,所以 0 规则整个失败阶层 而不是仅仅暗示健康.

与 consecutiveFailures 时间 0,无效或陈旧 lastEvaluatedAt 表示提醒已禁用或从未安排 。 当前 lastEvaluatedAt 无效 lastTriggeredAt 表示查询运行良好且条件不匹配 – 比较提醒 variables 根据保存的查询声明.

管弦乐

透视(异常检测)

校验(数据质量)

服务账户和IAM

网页订阅

可出版密钥( 前线)

身份

结构(已折旧)

资源

发展

# Install dependencies
npm install

# Build
npm run build

# Test with MCP inspector
CENTRALI_URL=https://centrali.io \
CENTRALI_CLIENT_ID=... \
CENTRALI_CLIENT_SECRET=... \
CENTRALI_WORKSPACE=my-workspace \
npx @modelcontextprotocol/inspector node dist/index.js

二. 服务账户识别符

账户路径工具使用字符串 clientId 返回时间 create_service_account 编号 : list_service_accounts,包括获取,更新,旋转,撤销,删除,dev-token,角色/组成员,以及权限扫描/模拟. 他们不再接受数字 serviceAccountId 投入。 支持现有的遗留客户ID. 在部署客户端ID路由更改时, 将这个软件包与 IAM 一起升级 .

分开 generate_remediation, (中文(简体) ), preview_remediation,以及 apply_remediation 工具保留其数字 serviceAccountId aPI的访问参数 targetId 合同。 账户应对措施继续包括两个方面 id 财务报告和审定财务报表 clientId。 。 。 .

开发测试

npm test 首先在单列中运行时建立兄弟式 SDK, 然后构建 MCP和运行它的测试。 健康回归使用真正的SDK正常化, 因此,它的运行时间分布必须存在,即使是在新离职时。 在外边 取而代之的是安装的 SDK 分布.