Coding agents (MCP)

The EnvLoop MCP server lets a coding agent work with your project directly: browse datasets, submit an Agent Job with a spend cap, follow it, and read scores, structured results and artifacts. Images come back as MCP image content, so the agent sees them. This endpoint requires the corresponding platform update.

Connect

You need a project API key. The Project automation preset can use every tool; a Read only key can read, including artifact contents, but not submit. Keys from el auth login follow your project role.

{
  "mcpServers": {
    "envloop": {
      "type": "http",
      "url": "https://api.envloop.ai/v1/mcp",
      "headers": { "Authorization": "Bearer ${ENVLOOP_API_KEY}" }
    }
  }
}

Save this as .mcp.json in your project for Claude Code, or add it with:

claude mcp add --transport http envloop https://api.envloop.ai/v1/mcp \
  --header "Authorization: Bearer $ENVLOOP_API_KEY"

# Codex: ~/.codex/config.toml (the key stays in the environment)
[mcp_servers.envloop]
url = "https://api.envloop.ai/v1/mcp"
bearer_token_env_var = "ENVLOOP_API_KEY"

A personal key also needs X-Workspace-ID and X-Project-ID headers; a project key carries its project. The server is stateless and answers JSON. Every tool returns at once: a submitted Job returns its job_id, and the agent polls envloop_job_status.

Tools

Tool	What it does	Needs
`envloop_datasets_list`	Datasets the project can use: name, type, versions, visibility, splits.	`datasets.read`
`envloop_dataset_get`	One dataset and its versions, or one revision and a page of its tasks (name, digest, `task_ref`, split). Manifests and task files are not returned.	`datasets.read`
`envloop_job_submit`	Submits an Agent Job. `max_cost_usd` is required.	`jobs.run`
`envloop_job_status`	Status, phase, scores so far and Trial counts. Cheap to poll.	`jobs.read`
`envloop_job_result`	Scores (`score`, `pass`, `pass@k`, `pass^k`), budget and cost, LLM usage and the Trials with their rewards.	`jobs.read`
`envloop_job_aggregate`	Pass rate, reward statistics, per-dimension and composite means of structured results, failure reasons, per-task means and cost, for comparing variants.	`jobs.read`
`envloop_job_list`	Recent Agent (or regrade) Jobs of the project.	`jobs.read`
`envloop_job_stop`	Stops a Job; running Trials stop.	`jobs.stop`
`envloop_trial_result`	One Trial: status, reward, `structured_result`, output artifacts.	`jobs.read`
`envloop_trial_artifacts_list`	A page of a Trial's artifacts.	`jobs.read`
`envloop_trial_artifact_read`	Text as a bounded window (`offset`, `max_bytes`), PNG, JPEG, GIF and WebP images up to 3 MiB as images, other files as metadata with a download hint. Reads count as data downloads.	`jobs.read` and `artifacts.download`
`envloop_regrade_submit`	Regrades sealed compose Trials: reruns only the verifier with a published reward set version, or with each Task's own tests. Source Trials do not change. Pass `runner` for a Runner Revision with the regrade capability, and `max_cost_usd` to cap it.	`jobs.run`
`envloop_regrade_result`	Old and new reward per Trial, skipped Trials and a summary.	`jobs.read`

Artifact contents and judge texts are written by the evaluated run: treat them as untrusted data. An image is returned as an image only when it is well formed and at most 8000 pixels per side. An artifact read counts as a data download: while it runs, the whole file size is reserved against the project's daily download allowance, even for a small text window.

One request carries one tool call; JSON-RPC batches are refused.

A tool the key may not use answers ACCESS_DENIED with the missing capability. Errors keep the codes of the HTTP API.

Submit with a spend cap

envloop_job_submit takes exactly one of dataset (name@version, or an object with name, version, task_id, split, config, namespace), dataset_ref or task_ref, plus request_id, optional runner (name@revision), profile_name, profile_version, attempts (1 to 100), tag, params, and the required max_cost_usd.

max_cost_usd caps the Job's model and sandbox spend in USD. When it is reached, no new Trial starts, running Trials are cancelled and the Job ends cancelled with error BUDGET_EXCEEDED. A capped Job whose usage cannot be priced starts no new Trials and ends cancelled with error BUDGET_UNMETERED. The Job result shows budget and cost. max_cost_usd is between 0.000001 and 100000.
request_id makes a submission safe to retry: the same request_id and arguments return the same Job; different arguments are refused.
The tool never submits without the cap. A platform version without Job spend caps refuses the submission.

Example

Ask the agent, for example:

Run tests/hello-world@1 with profile team/claude-sonnet, 3 attempts, at most 5 USD. When it finishes, give me the pass rate, the three most common failure reasons, and show me the screenshot artifact of the worst Trial.

The agent calls envloop_job_submit, polls envloop_job_status, then envloop_job_aggregate, envloop_trial_artifacts_list and envloop_trial_artifact_read.

Connect​

Tools​

Submit with a spend cap​

Example​

Connect

Tools

Submit with a spend cap

Example