MCP: Individualized LMS retraining

The local stdio and hosted OpenTrain MCP servers expose the same individualized-retraining operations as REST and the CLI. They are thin tools over the canonical LMS and Project To-do engines.

Hosted visual proof requires @opentrain-ai/mcp 0.17.0 or later. Canonical authoring intent and the retraining scaffold require MCP 0.21.0 or later. The hosted MCP endpoint exposes the same operations after the matching platform release.

Discover capabilities first

Call opentrain_capabilities first. Inspect the LMS retraining family under agentSurfaces, including the family status and each operation’s authorized value. Then call opentrain_lms_capabilities and inspect its retraining, assessments, course, lessonContent, assets, preview, and mastery sections instead of relying on remembered enums or limits.

Treat disabled, rollout_gated, or unauthorized as fail-closed results. The retraining capability block also identifies the two human checkpoints: worker-equivalent Preview and the no-write assignment plan. An agent must not assign directly around either checkpoint.

Tools

Tool	Purpose
opentrain_lms_retraining_create_case	Create one employer-only DRAFT case for exactly one active contract.
opentrain_lms_retraining_list_cases	List cases with job, contract, status, cursor, and limit filters.
opentrain_lms_retraining_get_case	Read a case with live assignment, employer-review, and bounded run projections.
opentrain_lms_retraining_update_case	Patch a draft under its expected state revision.
opentrain_lms_retraining_scaffold_case	Return deterministic, strictly no-write grounding, intent, constraints, and ordered canonical build operations.
opentrain_lms_retraining_plan_case	Generate the signed, strictly no-write assignment plan.
opentrain_lms_retraining_assign_case	Consume the reviewed plan and create one canonical Project To-do assignment.
opentrain_lms_retraining_close_case	Close an occurrence with an outcome proven by canonical assignment state.
opentrain_lms_retraining_list_modules	List reusable published skill-gap modules with bounded pagination.
opentrain_lms_retraining_register_module	Register or relabel one published course module.

Hosted visual-proof tools

These tools operate on the existing isolated LMS Preview session:

Tool	Purpose
opentrain_lms_render_preview	Render the real worker player into desktop/mobile PNG, ARIA, diagnostics, and manifest evidence.
opentrain_lms_step_preview	Execute one closed typed DOM action and return before/after evidence plus a canonical receipt.
opentrain_lms_share_preview_link	Mint a short-lived observe-only link for a signed-in employer organization member.
opentrain_lms_get_preview_link	Inspect one link record without recovering its secret URL.
opentrain_lms_list_preview_links	List bounded link records for a session.
opentrain_lms_revoke_preview_link	Revoke one review link.

Render and step responses include structured artifact metadata. When a PNG is within transport limits and passes signature, checksum, and byte-size verification, MCP also returns it as an inline image content block. Otherwise, it returns short-lived resource links and states that inline visual evidence is unavailable. Agents must never infer a successful visual check from metadata alone.

The render tool captures the session’s current focus. Target fields are assertions, not navigation. Use the existing Preview selection tool first. The step tool accepts only open_lesson or complete_content; it cannot run arbitrary browser commands.

Recommended sequence

1. Create a case for one contract ID.
2. Call opentrain_lms_retraining_scaffold_case; it is strictly no-write and returns the canonical authoringIntent, approved grounding, constraints, and ordered registered operations.
3. Use those existing LMS course and Native Forms tools to create or update the module. Preserve the returned intent in the canonical draft.
4. Use the hosted LMS Preview render and step tools to inspect the real learner renderer without writing worker state. When human review is needed, mint a short-lived observe-only link to the same session.
5. Register the published module if it is not already in the skill-gap registry.
6. If needed, patch the DRAFT case with opentrain_lms_retraining_update_case and its exact expected revision.
7. Call opentrain_lms_retraining_plan_case and ask an authorized employer to review and explicitly approve the exact masked recipient, version and content hash, frozen due instant, effects, request hash, and receipt.
8. Only after that approval, call opentrain_lms_retraining_assign_case with the exact receipt, expected revision, confirmAssign: true, and a stable idempotency key.
9. Read the case and use existing LMS review tools to monitor or grade it.
10. Use the canonical Project To-do RETURN operation to grant one more run when allowed.
11. Close the case only after its outcome agrees with canonical assignment state.

Update a published module that is already assigned

opentrain_lms_publish_course creates a new immutable version. It does not update existing learner assignments. After publish:

1. Call opentrain_lms_rollout_preview with the course ID, new version ID, exact content hash, and explicit job or assignment audience.
2. Ask the authorized employer to review the live informational impact.
3. Call opentrain_lms_rollout_course_version with the same target, confirmApply: true, and a stable idempotency key.
4. Read opentrain_lms_rollout_status or opentrain_lms_rollout_receipt until the queued count reaches zero or a typed blocker requires attention.

Apply reclassifies live assignment state, so ordinary learner progress after Preview does not stale the whole operation. Safe assignments update now; protected in-progress assessments defer to a safe boundary. Compatible progress and submitted-attempt rules remain intact, terminal assignments are skipped, and no duplicate Project To-do is created.

See Update an assigned LMS course and the course rollout API.

Safety contract

• Recipient resolution is exact-one and fail-closed.
• The assignment audience is always one selected contract. Future hires are never included.
• Planning writes nothing and consumes no attempts.
• The plan freezes the course version, content hash, case revision, capture hash, and due instant.
• Assignment requires an authorized employer’s explicit approval, the reviewed short-lived receipt, explicit confirmation, and a stable idempotency key. confirmAssign: true records that approved mutation; it does not let an agent self-approve.
• Worker names are masked. Employer-only evidence does not enter the worker payload.
• Learner and summary results never expose answer keys, correct values, prior wrong values, or per-question scores.
• List tools are cursor-paged. Follow nextCursor until hasMore is false before claiming a complete audit.
• Tool failures set isError: true and preserve the API status, stable error code, structured details, and request ID. Branch on those fields rather than human-readable text.
• Preview images prove the simulated worker renderer at an exact revision. They do not prove delivery to a particular worker or mutate learner state.

Permissions

Reads require lms:read. Mutations and the protected no-write plan require lms:write. Both the local and hosted MCP servers enforce the same organization and job authorization as REST.

See the workflow guide, Retraining API, and Hosted LMS visual preview for the full lifecycle.