MCP server

The Divergent MCP server gives an agent the same operations as div, as MCP tools. The sandbox tools are documented in Sandboxes MCP tools.

Setup

The server runs over stdio:

DIVERGENT_API_KEY=dv_live_... node apps/mcp/dist/index.js

For Claude Code, add it to .mcp.json:

{
  "mcpServers": {
    "divergent": {
      "command": "node",
      "args": ["/path/to/divergent-studio/apps/mcp/dist/index.js"],
      "env": { "DIVERGENT_API_KEY": "dv_live_..." }
    }
  }
}

Environment variables

Variable	Description	Default
DIVERGENT_API_KEY	API key. Required: the server exits at startup without it. Create one under Settings in the dashboard, or use the key div login saved.
DIVERGENT_API_URL	API URL.	https://api.divergentlabs.xyz

The server writes nothing to disk.

Tools

Tools that take a run accept its name or ID. Every tool returns JSON.

Account

Tool	Parameters	Returns
whoami	none	The org and the key’s owner.
catalog	none	GPU types, included cores and memory, and hourly prices.
billing_summary	days (default 30)	Plan, credit, and spend over the last days days.

Runs

Tool	Parameters	Returns
create_run	directory, entrypoint (required); project, gpu (default h100), gpu_count, cpu, memory_gib, name, image, max_spend_cents, env, checks, telemetry_file, no_upload, volume	The started run and the upload summary. Returns immediately.
list_runs	project, status, limit	Runs, newest first.
get_run	run	One run, including check verdicts.
get_run_logs	run; after_seq (default 0), limit (default 500)	Log lines with their seq.
get_run_result	run; path	The run’s result, or the value at path. Fails if there is none.
get_run_telemetry	run; keys (up to 32), x	Without keys: each key’s count, last, min and max. With keys: [x, y] pairs, at most 200 per key.
cancel_run	run	The stopped run. A run that has already finished is returned unchanged, without an error.

Parameters match the div run flags, except that max_spend_cents is in cents, memory_gib is a whole number of GiB, and telemetry_file is relative to directory.

status takes the same values as div runs --status, except active.

Evaluations and models

Tool	Parameters	Returns
run_evaluation	evaluation, model, directory, entrypoint (required); metric, direction (higher or lower), checks, again, suite_paths, setup, and every create_run parameter except name	The started run, or already_measured: true with the earlier run and its value.
list_evaluations	project	Evaluations, each with its leading version.
get_evaluation_report	evaluation; project	Versions ranked best first, with earlier suites listed separately.
list_models	project	Every model version with its location and size.
publish_model_version	model (as model:tag), volume, project (required); path, run	The published version and its measured size.

See div eval and div model for the meaning of each parameter.

Storage

Tool	Parameters	Returns
list_volumes	none	Every volume, with size and file count where measured.
list_volume_files	volume; prefix	The entries directly under prefix. Does not recurse.
storage_put	volume, source (required); destination	File count and bytes uploaded. Failed files are listed under failed. Creates the volume if needed.
storage_get	volume, path	{"encoding": "utf8", "text": ...} for UTF-8 content, otherwise {"encoding": "base64", "base64": ...}.

storage_get rejects files over 8 MB. Use div storage get for larger files.

Secrets

Tool	Parameters	Returns
list_secrets	environment	Each secret’s name, environment, products and timestamps, ordered by environment then name. Every environment unless environment is given. Values are never returned.
set_secret	name, value (required); environment, products	Creates or replaces the secret. A new secret has ["runs", "sandboxes"] unless products is given. A replaced one keeps its products.
set_secret_products	name, products (required); environment	Changes which products receive the secret. The value is not changed.
delete_secret	name (required); environment	Deletes the secret from the environment. Runs and sandboxes already started keep the value.
list_environments	none	Each environment’s name, secrets (a count) and inserted_at, default first. inserted_at is null for default.
create_environment	name	Creates an empty environment: lower case letters, digits and dashes, up to 63 characters, starting with a letter or digit.
delete_environment	name	Deletes the environment and every secret in it. Returns {"deleted": name, "secrets": [names]}. Refused with environment_in_use while a sandbox that is not deleted uses it. default cannot be deleted.

environment defaults to default. products is one or both of "runs" and "sandboxes". Runs receive the secrets in default whose products include runs. A sandbox receives only the secrets named at sandbox_create, from its environment, whose products include sandboxes. See div secrets.

The value passed to set_secret is part of the conversation with the agent. Treat it like a credential typed into a chat.

arXiv

Tool	Parameters	Returns
search_papers	query, author, category, sort (relevance, submitted, updated), limit (1 to 100, default 10)	The total match count and each paper with its abstract.
get_papers	ids (1 to 100)	The papers, and any IDs not found under missing.

See div papers.

Following a run

create_run returns as soon as the run has started. To follow it, poll get_run for the status and get_run_logs for output. Pass the highest seq you have received as after_seq to get only new lines:

create_run                  → {"run": {"name": "run-k4t9", "status": "queued", ...}, "uploaded": {...}}
get_run_logs(after_seq: 0)  → [{"seq": 1, ...}, {"seq": 2, ...}]
get_run_logs(after_seq: 2)  → [{"seq": 3, ...}]
get_run                     → {"status": "succeeded", "terminal": true, ...}