Skip to content
OpenTrain AIOpenTrain AIOpenTrain AIDocs

Ask OpenTrain

Answers from the documentation, with sources.

What would you like to do with OpenTrain?

AI answers can be mistaken. Check the linked sources. Don’t include private account information.

Open app

DEVELOPER DOCUMENTATION

MCP: Job Instructions

Canonical job Instructions plus hosted, agent-readable visual proof through the real employer and worker renderers.

The OpenTrain MCP server exposes the same job Instructions used by employers and hired AI trainers. The 16 content tools are available in local stdio package @opentrain-ai/mcp 0.5.0 or later. Version 0.23.0 adds 12 hosted visual-proof tools, and 0.36.0 adds their live-propagation probe. All are also available on the hosted endpoint at https://app.opentrain.ai/mcp.

There are no MCP tools for standalone instruction workspaces, manuals, bindings, changesets, revisions, or publications.

ToolWhat it does
opentrain_job_instructions_capabilitiesDiscover supported schemas, rich nodes, limits, allowed image hosts, imports, and mutation guarantees.
opentrain_job_instructions_inspectRead the canonical job tree, folder inheritance, lock state, and employer URL.
opentrain_job_instructions_read_pageRead one TipTap document and its deterministic checksum.
opentrain_job_instructions_previewValidate and render a complete TipTap document without writing.
opentrain_job_instructions_preflightValidate and sign one exact page mutation without writing.
opentrain_job_instructions_verifySemantically validate and checksum every canonical page.
opentrain_job_instructions_visual_reviewReturn the real employer URL and a sidebar, viewport, image, and screenshot checklist.
opentrain_job_instructions_preflight_treeValidate and sign one complete desired page tree without writing.
opentrain_job_instructions_apply_treeAtomically apply the exact preflighted page tree.
opentrain_job_instructions_plan_imageDerive the stable final image URL without uploading bytes.
opentrain_job_instructions_upload_imageUpload one supported image without changing a page.
opentrain_job_instructions_create_pageIdempotently create a root page or one-level subpage.
opentrain_job_instructions_patch_pageApply checksum-guarded node operations.
opentrain_job_instructions_replace_pageReplace a complete document with checksum and explicit replacement guards.
opentrain_job_instructions_update_pageRename, reparent, or reorder a page.
opentrain_job_instructions_archive_pageExplicitly archive a page from the job tab.

Version 0.27.0 adds folder migration and authoring to both stdio and the hosted MCP endpoint. Existing job tools keep their job-scoped inputs.

ToolPurpose
opentrain_inspect_folder_instructionsRead complete child-job/page inventory; content is explicit opt-in.
opentrain_preview_folder_instruction_changePreview activation, append or guarded reversal without writes.
opentrain_confirm_folder_instruction_changeBind the exact reviewed request/digest and start writer drain.
opentrain_get_folder_instruction_changeRead status without advancing or renewing the operation.
opentrain_apply_folder_instruction_changeVerify/stage and atomically apply the same confirmed operation.
opentrain_cancel_folder_instruction_changeCancel an uncommitted operation while retaining originals.
opentrain_resume_folder_instruction_changeExplicitly recover an expired operation; source drift may refuse.
opentrain_export_folder_instruction_recoveryExport retained originals under current employer authorization.

The opentrain_folder_instructions_* authoring tools cover the active tree, page content/metadata, images/video, history/restore, schema, links and verification. Read tools/list for exact input/output schemas and operation names. Results use validated structuredContent; a business failure sets isError: true rather than presenting an unsuccessful write as success.

Follow the shared folder guide before confirmation. Read-only inventory and preview never activate a folder; ordinary page creation cannot replace first activation. Only verified readback completes migration. Keep the same operation ID after an uncertain response.

Authoring tools expose _meta["opentrain.ai/authoring-retry"] with versioned, operation-specific inspection/retry guidance. Unkeyed mutations keep idempotentHint: false. Missing resources do not prove success; schema intents and video cancellation require their own current-state inspection. No release, read-required or acknowledgment features are enabled by folder migration.

These resource URIs retain their existing job scope.

Resource URIContents
opentrain://jobs/{jobId}/instructionsThe canonical job page tree and employer URL.
opentrain://jobs/{jobId}/instructions/pages/{pageId}One canonical page and checksum.

These 12 tools render the real Instructions UI in OpenTrain-hosted Chromium. They do not ask the MCP client to automate a browser:

ToolWhat it does
opentrain_job_instructions_visual_capabilitiesDiscover audiences, viewports, targets, evidence kinds, retention, and worker-coverage rules.
opentrain_job_instructions_visual_session_createPin one canonical job tree and choose the employer or designated test-worker surface.
opentrain_job_instructions_visual_session_getRead the session, current selection, state revision, and source drift.
opentrain_job_instructions_visual_session_selectSelect a page or stable node with an expected-state revision.
opentrain_job_instructions_visual_session_expireEnd a session early.
opentrain_job_instructions_visual_session_mint_linkRefresh the session’s one-time renderer grant.
opentrain_job_instructions_visual_renderCapture desktop/mobile PNG, ARIA, diagnostics, and manifest evidence.
opentrain_job_instructions_visual_artifacts_listList bounded private artifacts for a session.
opentrain_job_instructions_visual_artifact_getReturn one artifact with a fresh signed resource URL.
opentrain_job_instructions_visual_link_createCreate an observe-only human review link.
opentrain_job_instructions_visual_links_listList link metadata and lifecycle states without recovering secrets.
opentrain_job_instructions_visual_link_revokeRevoke one review link.

opentrain_job_instructions_visual_render returns verified PNGs as MCP image content when the client supports them, plus the structured artifact records and short-lived resource links. An agent can reason over the exact screenshots in the same turn. A human observe link uses normal OpenTrain authentication and does not require Vercel access.

Employer sessions use the actual Instructions workspace. Worker sessions require a real designated test-worker contract and report typed workerCoverage; OpenTrain never fabricates worker proof. Every render reports source drift. collaborationSyncVerified remains false because captured visual proof cannot prove that an already-open collaborative client received a live update.

YouTube and Loom player frames load in the proof. Every other third-party embed is blocked by design and renders blank in the PNG while the render still succeeds; the diagnostics artifact lists the blocked address under blockedRequests. When the render measured the count, the result’s manifest.warnings also has a coded THIRD_PARTY_EMBED_BLOCKED string with the number of blocked embeds and no address. YouTube and Loom players are never in the count. On the hosted endpoint, the render result also carries the typed renderWarnings list. An absent list means the count was not measured, and [] means nothing was blocked; see Third-party embeds.

opentrain_job_instructions_visual_render accepts an optional syncProbe argument on the hosted endpoint and in local package 0.36.0 or later. The probe checks whether a view that is already open shows a change that another writer commits while it watches:

{
"sessionId": "<SESSION_ID>",
"expectedStateRevision": 2,
"viewports": ["desktop"],
"syncProbe": {
"timeoutMs": 45000,
"expectedPageChecksum": "<64-hex page checksum>",
"expectedTreeChecksum": "<64-hex tree checksum>"
},
"idempotencyKey": "sync-probe-v1"
}
  • syncProbe.timeoutMs is required: 5000 to 45000 milliseconds. The two checksums are optional, 64-character lowercase hex values from your writer’s receipt. The schema rejects any other field.
  • Use the desktop viewport only, and select the page first, at session creation or with opentrain_job_instructions_visual_session_select. Without a selected page the call fails with status 409 before the probe starts.
  • Commit the page body and page-tree change from a separate process while the call runs. The local server waits up to 130 seconds for the result.
  • A verified probe returns the render with livePropagationVerified: true, propagationSurface: "SCOPED_READ_ONLY_VIEW", and its syncReport. Both servers check the result against the published schema first; if it does not match, they return an error and withhold the values.
  • A probe that is not verified returns a tool error for status 409. On the hosted endpoint, the error’s structuredContent is the API error body, whose details carry reason: "COLLABORATION_SYNC_NOT_VERIFIED", the syncReport, and the artifactIds. The local server reports only the status and message. To read the report there, find the session’s manifest with opentrain_job_instructions_visual_artifacts_list and fetch it through the signed URL from opentrain_job_instructions_visual_artifact_get.
  • Each experiment needs a new session and a new idempotencyKey. Retrying the same key returns the saved result and never starts another observer.

livePropagationVerified: true proves that the change reached the scoped read-only view. collaborationSyncVerified stays false, so the probe proves nothing about live collaborative editors. See Live-propagation probe for every status and failure reason.

Preview and both preflight tools are read-only. Every mutation requires confirmLive: true and the short-lived signed token returned by its exact preflight because the job Instructions editor has no separate publication state and hired AI trainers can see the write immediately.

Creation also requires an idempotencyKey. Patch and replacement require the last-read checksum. Replacement additionally requires confirmReplace: true; archive requires confirmArchive: true.

The server enforces root pages plus one subpage level. A successful mutation returns the exact employer URL and canonical content. Complete-tree apply uses an exact live-tree fence and one atomic visibility boundary, so workers do not see a partially assembled page hierarchy.

opentrain_job_instructions_upload_image accepts a base64-encoded JPEG, PNG, WebP, GIF, or AVIF up to 5 MB and returns a URL for a TipTap image node. The upload alone does not edit a page. Use opentrain_job_instructions_plan_image first when the reviewed document must contain the exact final URL before upload. General file, audio, and video attachments are not supported by this job Instructions surface.

Capability discovery returns image.allowedHostPatterns. When a source image uses another host, upload it first and place the returned canonical URL in the page document.

opentrain_job_instructions_visual_review describes what an authenticated employer browser should show, including sidebar order and page checksums. It is a no-render checklist. Use the hosted visual-proof tools above for actual PNG and semantic evidence from the employer or designated worker surface.

Reads and visual artifact reads require instructions:read. Preview, image upload, content mutations, session control, rendering, and link mutations require instructions:write. The authenticated employer must also have access to the job, and the visual-proof rollout must be enabled for the actor; a token scope never grants access across organizations.

See MCP overview for setup and Manage job Instructions for an end-to-end workflow.