Start sample or full Runs, wait with a bounded cap, then resume, retry, or cancel.

The public production MCP endpoint is live at https://mcp.everyn.ai/mcp. Configure a host with that Streamable HTTP URL and complete WorkOS OAuth.

A Run is the durable execution record for a pinned Job version against a Dataset scope. Public states are draft, queued, running, paused, succeeded, completed_with_flags, failed, and canceled. Unknown future states fail closed.

start_run accepts exactly one form: new sample, new full, resume, or retry. Do not combine them.

Sample versus full

Form	Required input	Meaning
New sample	`dataset_id`, `job_version_id`, `mode: "sample"`, `sample`, idempotency key	Limited scope. `sample.limit` or `sample.dataset_row_ids`.
New full	`dataset_id`, `job_version_id`, `mode: "full"`, idempotency key	Entire Dataset. Never inferred from a sample.

Never silently widen a sample into a full Run. A direct user request for that exact sample or full Run is sufficient intent. If you propose the action, show the receipt and ask first.

Optional reference_dataset_ids may accompany a new sample or full Run.

Admission

start_run reuses Everyn's shared billing admission and fails closed without provider dispatch. MCP cannot create a billing account, take payment, add funds, or change a plan.

Error	Retryable	Next step
`admission.missing_plan_authority`	No	Open Usage and Billing at `https://app.everyn.ai/settings`.
`admission.billing_hold`	No	Open Usage and Billing. MCP cannot release a hold.
`admission.insufficient_managed_ai`	Yes	Open Usage and Billing, then retry after spendable value exists.
`admission.row_budget_or_exposure_exhausted`	Yes	Open Usage and Billing, then retry after budget headroom exists.
`admission.unknown_billing_state`	No	Open Usage and Billing. Do not assume the Run started.

Mid-run wallet exhaustion pauses the Run and preserves completed work. It is not a start_run admission denial. Resume after Usage and Billing shows spendable value.

Wait

get_run returns immediate status or performs one bounded wait.

`wait.for`	Meaning
`change`	Any status or progress change.
`attention`	The Run needs a decision.
`terminal`	The Run reached a terminal state.

timeout_seconds is optional and capped at 25 seconds, below the 30-second CloudFront origin-read default. One wait never covers a Run lifetime.

Disconnect ends only the waiter. The Run keeps going. After the user asked you to wait, keep calling bounded get_run waits without asking them to prompt again.

search_runs filters by state, Dataset, Job, and time. It does not invent free-text Run search.

Resume and retry

Form	Use when
Resume	One eligible paused Run via `resume_run_id`.
Retry	Create and start one immutable retry over Everyn-derived eligible unresolved scope via `retry_run_id`.

Callers do not select an arbitrary retry subset. Do not blindly retry quality or spec failures.

Cancel

cancel_run cancels one Run with harvest-aware semantics. Harvest failure never blocks cancellation.

`mode`	Meaning
`normal` (default)	Cancel and harvest committed output when possible.
`urgent_stop`	Cancel first.

Canceled Runs cannot resume. Repeated cancel is safe. already_terminal reports a Run that was already finished.

Preview while waiting

get_run_results returns a small committed preview with explicit incompleteness. Default 20 rows, hard maximum 50. It never paginates exhaustively or creates a CSV. Active Runs always report incomplete.

When next_action is export_and_analyze, the completion set is terminal and version-compatible. Continue with Export.