MCP / AI Agents

Connect Vara to Claude Code / Codex and other AI agents — read/write experiments in plain language, or have AI turn a paper into a reproducible draft.

For developers / advanced users. This page covers command-line setup and API keys. Regular users can skip it — the web app and desktop clients are all you need day to day.

What it is

Vara MCP is a local stdio server that wraps Vara's /v1 data API as 25 agent tools. Once set up, no web UI needed — tell your AI agent in plain language and it lists / searches / creates / updates experiments, attaches files / manages references & materials, or imports a paper into a structured experiment. It uses the same vara_sk_ key as the OpenAI gateway, but hits the data API (no LLM provider config needed).

25 tools

Read (any valid key): list experiments · get one experiment in full (sub-experiments / steps / parameters / run logs / reproduction risks / attachments / linked references) · keyword search · get import schema · list daily plan · list references · list materials
Write (needs read_write key): create / update experiment · add / update sub-experiment · log a run · update a run · import · add / update / remove plan items · attach / delete file · references: add / add-from-PDF / delete / link / unlink · create material
Core data (experiments / sub-experiments / runs) still can't be deleted; only attachments · references (soft-archive) · experiment-reference links can.
When the target is unclear, the AI lists candidates and asks first instead of guessing or defaulting to a new experiment ("ask before recording"). Attachments accept png / jpg / gif / webp / pdf / csv / xls / xlsx, ≤50MB per file.

Setup (2 steps)

Create a vara_sk_ key at /settings/api (pick read_write for write tools)
Register it with Claude Code / Codex (needs Node 18+; npx fetches the npm package — no repo clone):

claude mcp add vara \
  -e VARA_API_KEY="vara_sk_yourkey" \
  -e VARA_BASE_URL="https://www.varaapp.site/api/v1" \
  -- npx -y vara-research-mcp

Restart the AI client for the vara_*tools to appear. Verify: tell your AI "list my Vara experiments".

Paper → reproducible experiment (import)

Paste a paper's Methods / a protocol / notes to your AI; it fetches the schema, builds a structured bundle, and imports it. Returns a reviewUrl — it's committed only after you confirm on the web. Unconfirmed drafts never enter your experiment list, so mistakes are harmless.

Every field tagged by provenance: explicit verbatim · partial missing value · inferred · missing, each with confidence
Missing data is never fabricated → logged to "reproduction risks"; AI-inferred data stays separate → "AI inferences" with citation + verify hint
Steps kept in exact source order; any source language (Chinese papers work too, output translated to English by default)

Limits & errors

403 — key lacks write scope; create a read_write key at /settings/api
404 — id unknown or not yours (search first); 429 — over 60 writes/min, wait and retry
Data isolation: you only see / edit data owned by this key's account; responses over 25000 chars are truncated (use a narrower query or an id)