帮助中心
目录（点击展开）

MCP / 接入 AI 助手

把 Vara 接进 Claude Code / Codex 等 AI 助手，用大白话读写实验，或让 AI 把论文变成可复现草稿。

面向开发者 / 高级用户。 本页涉及命令行配置与 API key，普通用户可以跳过，日常用网页或客户端就够了。

这是什么

Vara MCP 把 Vara 的 /v1 数据接口包成 27 个 agent 工具，有远程连接和本地 server 两种接法。配好后不用开网页，直接对 AI 助手说人话，它就代你查 / 搜 / 建 / 补充实验，传附件 / 管文献 / 管物料，或把论文导成结构化实验。本地版用的是跟 OpenAI 网关同一个 vara_sk_ key，但走数据接口（无需配 LLM 提供商）。

远程连接（推荐）

不用装 Node，也不用建 key。在 AI 客户端里添加下面这个地址，按提示登录 Vara 并点「允许」就能用，工具和本地版是同一套。面向普通用户的分步说明、权限和数据去向见 在 AI 助手里连接 Vara。

https://varaos.com/api/mcp
  • Claude（claude.ai / 桌面版）：设置 → 连接器 → 添加自定义连接器，填上面的地址，点「连接」后登录 Vara 并点「允许」。
  • Claude Code：运行下面的命令，第一次用时在 /mcp 里选 vara 完成授权。
claude mcp add --transport http vara https://varaos.com/api/mcp
  • Cursor：在 mcp.json 里写入下面的配置，按提示登录授权。
{
  "mcpServers": {
    "vara": { "url": "https://varaos.com/api/mcp" }
  }
}
  • 权限在同意页决定：默认读写，可以勾成只读。连上的客户端会出现在 /settings/api 的「已连接的应用」里，随时可以断开，断开后立刻失效。
  • 附件：远程模式读不到你电脑上的文件，AI 会用文件链接 url（不超过 25MB）或 base64 内容（不超过 3MB）上传。本机上更大的文件请在网页里直接拖入。
  • 任何登录账号都能连接，不需要开通 API 访问。用量和网页一致：免费版最多 3 个实验，建实验撞上限时工具返回 FREE_TIER_EXPERIMENT_LIMIT 和腾出名额的办法；会用到 Vara 自己 AI 的工具（vara_add_reference_from_pdf，以及没有合法 vara 块、要走 AI 解析的 vara_import_experiment）计入 AI 额度，额度用完返回 quota_exhausted 说明。
  • 授权后客户端拿到的访问令牌也能直接调用 /api/v1 数据接口；直接调用 REST 需要开通 API 访问（试用或开通，和 API key 是同一个门），权限和限流与 API key 相同。LLM 网关（/v1/chat/completions、/v1/models）不接受这种令牌。
  • 快捷指令（MCP prompts）：远程端还提供 save_conversation_as_experiment、plan_my_week、log_todays_run、today_in_vara 4 个，参数都可选，只生成一段请求文字交给 AI，本身不读写数据。本地 npx 版没有。ChatGPT 和国内客户端的接法、可直接复制的说法见 在 AI 助手里连接 Vara。

只能填 URL 和请求头的客户端（如 WorkBuddy、豆包等）

客户端的自定义连接器不支持 OAuth 浏览器授权、但能填自定义请求头时，可以用 API key 连远程地址。平台名只是举例，以客户端界面为准。

  • 服务器 URL：https://varaos.com/api/mcp
  • 传输类型：Streamable HTTP（有的客户端叫 HTTP）
  • 请求头：Authorization: Bearer vara_sk_...，key 在/settings/api创建。建 key 时选权限：只读（read）或读写（read_write），默认只读；要写入数据就选读写。每个账号最多保留 20 把未撤销的 key。
  • 不经过同意页，也不会出现在「已连接的应用」里；不需要开通 API 访问，每连接 300 请求/分钟与写入 60 次/分钟的限流、实验数上限和 AI 额度都和 OAuth 连接相同。撤销这个 key 即断开，立刻失效。
  • key 等同于密码，不要发给别人。错误、已撤销或格式不对的 key 一律返回 401；不带 Authorization 时返回 401 并在 WWW-Authenticate 里给出 OAuth 发现地址。

27 个工具

  • 只读（任何有效 key 都能用）：列实验 · 取单个实验全文（子实验 / 步骤 / 参数 / 运行记录 / 复现风险 / 附件 / 挂接文献）· 关键词搜索 · 取导入 schema · 列每日计划 · 列文献库 · 列物料，另有取子实验的孔板（vara_get_plates）
  • 写（需 read_write key）：新建 / 改实验 · 加 / 改子实验 · 记录运行（可带逐孔结果 plateMarks）· 改运行 · 导入 · 计划增 / 改 / 删 · 传 / 删附件 · 文献加 / 从 PDF 加 / 删 / 挂接 / 取消挂接 · 建物料，另有排孔板（vara_design_plate）
  • 孔板：vara_get_plates 读子实验上的孔板（样本、条件、备注，加 includeRuns 还能看到最近运行里标为异常或弃用的孔）；vara_design_plate 按一段简短规格排板，孔位由 Vara 分配；vara_log_run 带上 plateMarks，可以同时记下这次运行里每个孔的结果（正常 / 异常 / 弃用）。通过连接修改已有孔板时，一律另存为一块新孔板，原来那块不会被改动。新孔板的名字会在原名后加后缀：原名含中文时是「（AI 改）」，否则是 (AI edit)。一个子实验最多 10 块孔板。
  • 核心数据（实验 / 子实验 / 运行）仍删不了；可删的仅：附件 · 文献（软删归档）· 文献与实验的挂接。
  • 目标不明时 AI 会先列候选让你确认，不瞎猜 / 不默认新建（"加记录前先问"）。附件支持 png / jpg / gif / webp / pdf / csv / xls / xlsx。本地版单文件约 3MB 以内（文件以 base64 放进请求体，服务端 Vercel 请求体上限 4.5MB），远程连接的上限见下文，更大的文件请在网页里直接拖入。

AI 改已有内容，先让你确认

连接的 AI 或 API 改你已有的实验、子实验、运行记录时（vara_update_experiment、vara_update_step、vara_update_run），默认不会直接改掉，而是先放进待确认改动。AI 会收到「等你在 Vara 里确认」的回复和一个链接，你在网页上看到逐字段的改前改后，点「采用」才生效，也可以点「不要」。

  • 入口：有待确认改动时，首页顶部会出现一行提示；被改的实验页上也有横幅；设置里「外部 AI 改动先让我确认」旁边也有链接。也可以直接打开 /pending-changes。
  • 采用前会核对内容：如果这期间你自己又改过同一处，Vara 不会覆盖，会提示「内容已经变了，没法直接套用」，并把现在的内容和 AI 想改成的内容摆在一起。
  • 新建实验、加子实验、记录运行、导入、加文献、传附件、计划这些不受影响，照常直接写入。
  • 不想每次确认，可以在 /settings/api 关掉「外部 AI 改动先让我确认」，关掉后恢复直接写入。
  • 直接调 REST 的开发者：这三个 PATCH 在开着确认时返回 HTTP 202，status 为 pending_confirmation，附 pendingChange（id、reviewUrl、改了哪些字段）。

本地连接（API key，2 步）

  1. 在 /settings/api 创建一个 vara_sk_ key（建 key 时选权限，要用写功能就选「读写」，即 read_write）。本地版直接调用 /api/v1，账号需要开通 API 访问（试用或订阅）；没开通的话用上面的远程连接，不需要开通。
  2. 注册到 Claude Code / Codex（需 Node 18+；npx 自动从 npm 拉取，无需 clone 仓库）：
claude mcp add vara \
  -e VARA_API_KEY="vara_sk_你的key" \
  -e VARA_BASE_URL="https://varaos.com/api/v1" \
  -- npx -y vara-research-mcp

重启 AI 客户端后 vara_* 工具才会出现。验证：对 AI 说 "列出我的 Vara 实验"。

论文 → 可复现实验（导入）

把论文 Methods / 协议 / 笔记贴给 AI，它先取 schema 再生成结构化 bundle 导入。返回一个 reviewUrl，你在网页确认后才入库：未确认的草稿不进你的实验列表，导错了不用慌。

  • 每个字段标来源：explicit原文逐字 · partial缺值 · inferred推断 · missing没提，都带置信度
  • 缺的不瞎编 → 进 "复现风险"；AI 补的不混入原文 → 进 "AI 推断"，附原文引用 + 核对提示
  • 步骤严格按原文顺序；来源语言不限（中文论文也能导，默认翻译成英文输出）

边界与报错

  • 403：insufficient_scope，key 是只读的，去 /settings/api 新建一把读写（read_write）key；trial_expired：本地版或直接调 REST 时账号没开通 API 访问（远程连接不受影响）；FREE_TIER_EXPERIMENT_LIMIT：免费版实验数已满
  • 404：id 不存在或不属于你（先 search 确认）；429：rate_limited 是请求过快（写入 60 次/分钟、单个连接 300 次/分钟、每个账号 600 次/分钟，按 url 下载文件 20 次/分钟），等一下重试；quota_exhausted 是 AI 额度用完（从 PDF 加文献、要走 AI 解析的导入会用到），额度按时间窗口自动恢复，或升级获得更多额度；经远程连接每小时最多按 DOI 加 200 篇文献
  • 数据隔离：只能看 / 改这个 key 所属账号的数据；单次响应超 25000 字符会截断（换更具体的查询或用 id）

本页更新于 2026-10-27