MCP: Job Instructions

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. Both 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.

Tools

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.

Resources

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

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.

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

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

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

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.