MCP / AI Agents

What it is

Vara MCP wraps Vara's /v1 data API as 27 agent tools, available as a remote connection or a local server. 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. The local server uses the same vara_sk_ key as the OpenAI gateway, but hits the data API (no LLM provider config needed).

Remote connection (recommended)

No Node install and no key to create. Add the URL below in your AI client, sign in to Vara when prompted and click Allow. You get the same tools as the local server. For step-by-step instructions, access levels and where your data goes, see Connect Vara to AI assistants.

https://varaos.com/api/mcp

• Claude (claude.ai / desktop): Settings, Connectors, Add custom connector. Paste the URL, click Connect, then sign in to Vara and click Allow.
• Claude Code: run the command below. The first time you use it, pick vara in /mcp to finish authorization.

claude mcp add --transport http vara https://varaos.com/api/mcp

• Cursor: add this to mcp.json and sign in when prompted.

{
  "mcpServers": {
    "vara": { "url": "https://varaos.com/api/mcp" }
  }
}

• You choose the permission on the consent page: read and write by default, or tick read-only. Connected clients show up under Connected apps at /settings/api, where you can disconnect them at any time. Access stops immediately.
• Attachments: in remote mode the server can't read files on your computer, so the AI uploads them as a file url (up to 25MB) or as base64 content (up to 3MB). Drag larger local files into the web app instead.
• Any signed-in account can connect; API access is not required. Usage counts the same as in the web app: the Free plan allows up to 3 experiments, and creating one past the limit returns FREE_TIER_EXPERIMENT_LIMIT with how to free a slot. Tools that use Vara's own AI (vara_add_reference_from_pdf, and vara_import_experiment when the markdown has no valid vara block and goes through AI parsing) count toward the AI quota and return quota_exhausted with an explanation when it is used up.
• The access token the client receives can also call the /api/v1 REST API directly; direct REST calls require API access (trial or enabled, the same gate as API keys), with the same scope and rate limits as an API key. The LLM gateway (/v1/chat/completions, /v1/models) does not accept it.
• Shortcuts (MCP prompts): the remote server also offers four, save_conversation_as_experiment, plan_my_week, log_todays_run and today_in_vara. Their arguments are optional, and they only produce request text for the AI; they do not read or write data themselves. The local npx server does not have them. For ChatGPT and other clients, and ready-to-copy requests, see Connect Vara to AI assistants.

Clients that only take a URL and request headers (such as WorkBuddy or Doubao)

If a client's custom connector cannot do OAuth browser sign-in but lets you set a custom request header, connect to the remote URL with an API key. The platform names are examples only; follow what your client's settings show.

• Server URL: https://varaos.com/api/mcp
• Transport: Streamable HTTP (some clients call it HTTP)
• Request header: Authorization: Bearer vara_sk_.... Create the key at/settings/api. Choose the key's permission when you create it: read-only (read) or read and write (read_write). Read-only is the default; choose read and write to change data. Each account can keep up to 20 active keys.
• There is no consent page and the connection does not appear under Connected apps. API access is not required; rate limits (300 requests/min per connection, 60 writes/min), the experiment limit and the AI quota are the same as for an OAuth connection. Revoking the key disconnects it immediately.
• Treat the key like a password and do not share it. A wrong, revoked or malformed key always gets 401; a request without Authorization gets 401 with the OAuth discovery URL in WWW-Authenticate.

27 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, plus get the plates of a sub-experiment (vara_get_plates)
• Write (needs read_write key): create / update experiment · add / update sub-experiment · log a run (optionally with per-well results, plateMarks) · update a run · import · add / update / remove plan items · attach / delete file · references: add / add-from-PDF / delete / link / unlink · create material, plus lay out a plate (vara_design_plate)
• Plates: vara_get_plates reads the plates on a sub-experiment (samples, conditions, notes; with includeRuns it also shows wells marked abnormal or discarded in recent runs). vara_design_plate lays out a plate from a short spec, and Vara assigns the wells. vara_log_run accepts plateMarks to record the result of each well (normal / abnormal / discarded) together with the run. Editing an existing plate through a connector always saves a separate new plate and leaves the original plate unchanged. The name of the new plate is the original name plus a suffix: "（AI 改）" when the original name contains Chinese characters, otherwise " (AI edit)". A sub-experiment holds at most 10 plates.
• 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. The local server takes files up to about 3MB (the file travels base64-encoded in the request body, and Vercel caps request bodies at 4.5MB); remote limits are listed below. Drag larger files into the web app instead.

Edits to existing content wait for you

When a connected AI or the API changes an existing experiment, sub-experiment or run (vara_update_experiment, vara_update_step, vara_update_run), the change is not saved straight away by default. It goes to Pending changes. The AI gets a reply saying the change is waiting for you in Vara, with a link. In the web app you see each field before and after, and the change takes effect only when you click Accept; you can also decline it.

• Where to find it: when something is waiting, a notice appears at the top of the home page, and the affected experiment shows a banner. The setting "Let me confirm changes from external AI" also links to it. You can also open /pending-changes directly.
• Vara checks before applying: if you edited the same field yourself in the meantime, Vara does not overwrite it. It tells you the content has changed and shows what is there now next to what the AI wanted.
• Creating experiments, adding sub-experiments, logging runs, imports, references, attachments and plan items are not affected and are saved directly as before.
• To skip the confirmation, turn off "Let me confirm changes from external AI" at /settings/api; edits are then saved directly again.
• For developers calling REST directly: while confirmation is on, these three PATCH endpoints return HTTP 202 with status pending_confirmation and a pendingChange object (id, reviewUrl, changed fields).

Local connection (API key, 2 steps)

1. Create a vara_sk_ key at /settings/api (choose its permission when you create it; pick read and write, i.e. read_write, for write tools). The local server calls /api/v1 directly, so your account needs API access (a trial or a subscription); without it, use the remote connection above, which doesn't.
2. 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://varaos.com/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, and 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: insufficient_scope, the key is read-only, create a read_write key at /settings/api; trial_expired: API access is not enabled for the local server or direct REST calls (the remote connection is not affected); FREE_TIER_EXPERIMENT_LIMIT: the Free plan's experiment limit is reached
• 404: id unknown or not yours (search first); 429: rate_limited means too many requests (60 writes/min, 300 requests/min per connection, 600 requests/min per account, 20 url file downloads/min), wait and retry; quota_exhausted means the AI quota is used up (adding a reference from a PDF and imports that need AI parsing use it), it refills automatically over time or you can upgrade for more; remote connections can add up to 200 references by DOI per hour
• 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)