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.
| Tool | What it does |
|---|---|
opentrain_job_instructions_capabilities | Discover supported schemas, rich nodes, limits, allowed image hosts, imports, and mutation guarantees. |
opentrain_job_instructions_inspect | Read the canonical job tree, folder inheritance, lock state, and employer URL. |
opentrain_job_instructions_read_page | Read one TipTap document and its deterministic checksum. |
opentrain_job_instructions_preview | Validate and render a complete TipTap document without writing. |
opentrain_job_instructions_preflight | Validate and sign one exact page mutation without writing. |
opentrain_job_instructions_verify | Semantically validate and checksum every canonical page. |
opentrain_job_instructions_visual_review | Return the real employer URL and a sidebar, viewport, image, and screenshot checklist. |
opentrain_job_instructions_preflight_tree | Validate and sign one complete desired page tree without writing. |
opentrain_job_instructions_apply_tree | Atomically apply the exact preflighted page tree. |
opentrain_job_instructions_plan_image | Derive the stable final image URL without uploading bytes. |
opentrain_job_instructions_upload_image | Upload one supported image without changing a page. |
opentrain_job_instructions_create_page | Idempotently create a root page or one-level subpage. |
opentrain_job_instructions_patch_page | Apply checksum-guarded node operations. |
opentrain_job_instructions_replace_page | Replace a complete document with checksum and explicit replacement guards. |
opentrain_job_instructions_update_page | Rename, reparent, or reorder a page. |
opentrain_job_instructions_archive_page | Explicitly archive a page from the job tab. |
Shared folder tools
Section titled “Shared folder tools”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.
| Tool | Purpose |
|---|---|
opentrain_inspect_folder_instructions | Read complete child-job/page inventory; content is explicit opt-in. |
opentrain_preview_folder_instruction_change | Preview activation, append or guarded reversal without writes. |
opentrain_confirm_folder_instruction_change | Bind the exact reviewed request/digest and start writer drain. |
opentrain_get_folder_instruction_change | Read status without advancing or renewing the operation. |
opentrain_apply_folder_instruction_change | Verify/stage and atomically apply the same confirmed operation. |
opentrain_cancel_folder_instruction_change | Cancel an uncommitted operation while retaining originals. |
opentrain_resume_folder_instruction_change | Explicitly recover an expired operation; source drift may refuse. |
opentrain_export_folder_instruction_recovery | Export 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.
Resources
Section titled “Resources”These resource URIs retain their existing job scope.
| Resource URI | Contents |
|---|---|
opentrain://jobs/{jobId}/instructions | The canonical job page tree and employer URL. |
opentrain://jobs/{jobId}/instructions/pages/{pageId} | One canonical page and checksum. |
Hosted visual-proof tools
Section titled “Hosted visual-proof tools”These 12 tools render the real Instructions UI in OpenTrain-hosted Chromium. They do not ask the MCP client to automate a browser:
| Tool | What it does |
|---|---|
opentrain_job_instructions_visual_capabilities | Discover audiences, viewports, targets, evidence kinds, retention, and worker-coverage rules. |
opentrain_job_instructions_visual_session_create | Pin one canonical job tree and choose the employer or designated test-worker surface. |
opentrain_job_instructions_visual_session_get | Read the session, current selection, state revision, and source drift. |
opentrain_job_instructions_visual_session_select | Select a page or stable node with an expected-state revision. |
opentrain_job_instructions_visual_session_expire | End a session early. |
opentrain_job_instructions_visual_session_mint_link | Refresh the session’s one-time renderer grant. |
opentrain_job_instructions_visual_render | Capture desktop/mobile PNG, ARIA, diagnostics, and manifest evidence. |
opentrain_job_instructions_visual_artifacts_list | List bounded private artifacts for a session. |
opentrain_job_instructions_visual_artifact_get | Return one artifact with a fresh signed resource URL. |
opentrain_job_instructions_visual_link_create | Create an observe-only human review link. |
opentrain_job_instructions_visual_links_list | List link metadata and lifecycle states without recovering secrets. |
opentrain_job_instructions_visual_link_revoke | Revoke 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.
Live-propagation probe
Section titled “Live-propagation probe”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.timeoutMsis 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 status409before 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 itssyncReport. 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’sstructuredContentis the API error body, whosedetailscarryreason: "COLLABORATION_SYNC_NOT_VERIFIED", thesyncReport, and theartifactIds. The local server reports only the status and message. To read the report there, find the session’s manifest withopentrain_job_instructions_visual_artifacts_listand fetch it through the signed URL fromopentrain_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.
Immediate-live confirmation
Section titled “Immediate-live confirmation”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.
Images
Section titled “Images”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.
Checklist versus rendered proof
Section titled “Checklist versus rendered proof”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.
Authentication
Section titled “Authentication”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.