MCP: Project To-dos and Quizzes

The OpenTrain MCP server manages the same Project To-dos list employers and AI trainers see in the product. The complete selective-coaching surface is available in local stdio package @opentrain-ai/mcp 0.14.0 or later. Version 0.23.0 adds 12 Native Forms visual-proof tools. Both are also available on the hosted endpoint at https://app.opentrain.ai/mcp.

All tools follow the Project To-dos safety contract: explicit audiences, strict SELECTED validation, signed preflight receipts for broad assignments, and request-bound idempotency.

The configured account must have the default-off Project To-dos agent surface enabled. A full-access employer key supplies the read/write scopes below but does not bypass that account gate; AGENT_SURFACE_DISABLED is an enablement error, not a reason to rotate the key. The static coaching-capabilities tool is the deliberate exception: it is available before enablement so an agent can discover the contract without tenant data.

Tools

Tool	What it does
opentrain_list_project_todos	Read the catalog, roster, assignments, and summary for a job or contract.
opentrain_export_project_todos_csv	Download per-person statuses as CSV (emails redacted).
opentrain_preflight_project_todo	NO-WRITE preview of a create, update+reissue, assign, or archive: masked recipients, exact counts, due/blocking behavior, duplicate warnings, archive effects, and the signed receipt broad audiences require.
opentrain_create_project_todo	Create one item and its assignments atomically. audience is mandatory; broad audiences require the matching receipt.
opentrain_assign_project_todo	Assign an existing item to a stated audience.
opentrain_archive_project_todo	Archive with a mandatory audited reason after previewing the exact open assignments that will close.
opentrain_set_project_todo_future_assignment	Confirm an exact future-hire auto-assignment policy change using the request-bound receipt from a matching set_future_assignment preflight; it creates no assignments immediately.
opentrain_manage_project_todo	Advanced action union for the remaining actions (enable/disable, categories, transitions, review).
opentrain_read_project_todo_quizzes	Quiz reads: forms, one form, results, one attempt, roster, CSV.
opentrain_preflight_project_todo_quiz_assignment	NO-WRITE preview of one quiz assignment, mirroring every live gate, with the receipt for broad audiences.
opentrain_assign_project_todo_quiz	Create and assign a quiz to-do pinned to one immutable published version.
opentrain_manage_project_todo_quiz	Advanced quiz union: authoring, publishing, grading, release, and retakes.

Safety behavior

• create_item and assign refuse to run without an explicit audience — in the focused tools and in both generic unions — before any request is sent. OpenTrain never defaults to all active workers.
• The generic unions cannot bypass recipient preview: fan-out and quiz-assignment bodies are redirected to the focused preflight-then-mutate tools.
• Receipts are minted by the preflight tools, live about 15 minutes, and die early if the roster or the exact payload changes.
• Retries with the same idempotencyKey converge; a replay reports itself and never widens the original fan-out. update_item is the exception — it publishes a new immutable version per call and must not be blind-retried.

Selective coaching tools

Version 0.14.0 adds 29 action-specific tools with identical hosted and stdio semantics, plus one stdio-only local-file upload convenience:

Tool group	Tools	Scope and behavior
Employer reads	opentrain_quiz_coaching_queue, _state, _cycles, _threads, _comments	Keyless, bounded reads with masked worker identity; project_todos:read.
Employer feedback	opentrain_quiz_coaching_comment, _redo_selection, _cancel_draft, _resolve_thread, _reopen_thread, _accept	Stable idempotencyKey; project_todos:write.
Selective return	opentrain_quiz_coaching_send_back_plan, _send_back_confirm	The plan is keyless and writes nothing. Confirm applies only the signed selection and fails 409 PLAN_STALE on drift.
Worker reads	opentrain_quiz_respond_context, _threads, _comments, _history	The token owner’s assignment only; project_todos:respond.
Worker actions	opentrain_quiz_respond_start, _autosave, _resubmit, _reply	Stable idempotencyKey; requested questions only.
Full retakes	opentrain_quiz_retake_plan, _apply	Separate from selective coaching; apply is bound to the plan checksum.
Discovery and export	opentrain_quiz_coaching_capabilities, _export	Static contract discovery and bounded masked JSON, JSONL, or formula-neutral CSV.
Feedback images	opentrain_quiz_coaching_image_prepare, _finalize, _status, _delivery	Private direct-upload lifecycle; delivery returns a short-lived MCP resource link.
Stdio convenience	opentrain_quiz_coaching_image_upload	Local-file one-shot available only in stdio MCP; hosted agents use prepare/upload/finalize.

Signed storage grants never enter structured tool output. Image bytes travel directly through the short-lived single-PUT grant, not as base64 tool arguments.

Hosted Native Forms visual proof

The opentrain_quiz_preview_* family renders one exact draft revision or published form version through the real worker form runner:

Tool suffix	Purpose
capabilities	Discover pins, targets, viewports, artifact kinds, retention, and zero-write guarantees.
session_create, session_get, session_select, session_expire, session_mint_link	Create and control a revision-fenced preview session.
render	Capture desktop/mobile PNG, ARIA, diagnostics, and provenance manifest evidence.
artifacts_list, artifact_get	Read bounded private evidence and fresh signed resource links.
link_create, links_list, link_revoke	Manage short-lived, observe-only human review links.

The render tool returns verified PNGs as MCP image content when supported, as well as the structured records and resource links. Agents can therefore inspect the exact worker-shaped visual without browser automation. Human links require normal OpenTrain sign-in, never Vercel authentication.

This is SIMULATED_WORKER_PREVIEW evidence, not delivery proof. It is pinned to one draft revision plus content hash or one immutable version, exposes no answer keys, and writes no learner attempts, answers, grades, result releases, To-do transitions, notifications, or completion rows. See Hosted quiz visual proof.

Permissions

Employer reads require project_todos:read; employer mutations require project_todos:write and a claimed account. Worker coaching uses a worker-minted project_todos:respond key, which is intentionally excluded from employer Full access. See Scopes and capabilities, the API reference, and the selective-coaching API.