MCP: Shared Job Context

The OpenTrain MCP server automatically includes the Shared Job Context protocol in its initialize response. Any compatible agent learns to read shared state before managing an existing job, claim coordinated work, recheck canonical records before consequential writes, use version and replay guards, and leave a checkpoint or handoff.

No separate skill, prompt, environment flag, or account rollout is required.

Warning

The deterministic signal, typed-policy, and canonical guide-projection tools require OpenTrain MCP 0.10.0 or later. Automatic synchronization, bounded polling, intents, proposals, scoped overlays, and exact managed messaging require MCP 0.11.0 or later. Guided operational setup requires MCP 0.15.0 or later. The dynamic per-job Work Catalog, coordination modes, external attestations, action renewal and handoff, and shared work-presence projection require MCP 0.23.0 or later. The Agent Guide, Playbook reads and deltas, Playbook proposals, and human publication require MCP 0.27.0 or later and a deployment whose capability response reports job_operations as available. Check opentrain_capabilities at startup, then run npm view @opentrain-ai/mcp version before using the stdio package. If npm latest is older, the matching package release is still pending.

Context and reconciliation tools

Tool	Purpose
opentrain_get_job_context	Required entry point: coherent objective, workflow, readiness, bounded fresh-priority queue, evaluator health, effective-policy summary, guide digest, blockers, actions, inconsistencies, and versions. Full view also includes bounded recent-event detail.
opentrain_get_job_context_delta	Paginated events after a prior context revision.
opentrain_get_job_context_person	One person’s lifecycle, raw and operative gates, blockers, decisions, and privacy-safe evidence IDs.
opentrain_sweep_job_context	Reconcile durable event hints and canonical projection drift, then return the resulting revision and completeness.

Call opentrain_get_job_context before deciding or acting on an existing job. In a writable session, call opentrain_sweep_job_context with that revision. While hasMore is true, continue with each sweep response’s contextRevision; when false, fetch context again. Read-only sessions do not sweep.

Automatic synchronization

MCP 0.11.0 carries one private server-issued session credential and bounded per-job delivery tokens across every covered native or bridged tool call. The hosted server isolates this state by authenticated principal and MCP transport session. The stdio server isolates it inside the current process. Raw credentials and signed tokens are captured internally and removed from model-visible content and structured results.

Every covered tool result includes sync and syncCoverage. Before acting, inspect:

• sync.conflicts for overlapping claims, intents, policies, or newer work;
• sync.recommendations for evidence-backed product-discovery suggestions;
• sync.nextOperations for the exact safe next tools; and
• sync.resyncRequired, which requires a fresh context read before a write.

syncCoverage.coverage is native, bridged, or none. A none result names the reason and does not claim that shared context was refreshed.

Use opentrain_poll_job_context_sync for one bounded real-time wait. A new delivery helps the agent choose what to investigate; it does not replace the canonical pre-action check.

Guided setup is automatic

While a job’s operating brief, typed workflow, or applicable required choice is missing, every covered result includes recommendation.job_setup_incomplete. Bootstrap next operations start with opentrain_get_job_setup, so the agent can discover and drive setup without a separate prompt from the user.

opentrain_get_job_setup is read-only. It returns canonical evidence, ordered questions, proposed defaults, exact write previews, approval requirements, and the bounded setup.* coordination view. The MCP initialize instructions tell the agent to:

1. read the packet and inspect existing setup work;
2. declare a setup.* intent before prompting;
3. stand down when DUPLICATE identifies another winner;
4. prove the winning intent’s non-null sessionId equals the current result’s non-null sync.session.sessionId, with the same principal;
5. present a zero-write plan for human approval;
6. re-read setup and prove ownership again immediately before approved writes; and
7. verify, resolve the intent, and record a handoff.

A visible winner ID never transfers ownership. Null or mismatched sessions stand down and establish a durable per-agent session or coordinate with the owner. Once the packet reports COMPLETE or DEFERRED, agents stop prompting the employer team.

See Set Up Shared Job Operations for the complete flow.

Work Catalog discovery is automatic

MCP initialize guidance and every covered synchronized result teach the agent that atomic work is per-job data, never a platform enum. The result’s sync.workCatalog, sync.recommendations, and sync.nextOperations identify an unconfigured catalog, recurring provisional work, a pending human approval, or work another session already owns. The user does not have to know that a catalog exists or ask the agent to set it up.

Tool	Purpose
opentrain_list_job_context_work_definitions	List this job’s draft, active, or archived definitions and current immutable bindings.
opentrain_get_job_context_work_definition	Read one definition’s current/latest version, exact grammar, digests, and bounded history.
opentrain_list_job_context_work_executions	List open or terminal defined/provisional executions and their one coordinating action/claim state.
opentrain_begin_provisional_job_context_work_execution	Coordinate real ad hoc work before the job has an approved reusable definition.
opentrain_propose_job_context_work_definition	Propose an inactive inferred definition from one provisional execution.
opentrain_create_job_context_work_definition	Create an attributed draft definition when its semantics are already decided.
opentrain_append_job_context_work_definition_version	Append an immutable successor against the exact latest binding.
opentrain_activate_job_context_work_definition	Activate an approved version against exact revision and binding preconditions.
opentrain_archive_job_context_work_definition	Archive a definition only after its open-work and migration blockers are resolved.
opentrain_begin_job_context_work_execution	Begin defined work against the exact current binding and mint its coordinating action.
opentrain_promote_job_context_work_execution	Promote an exact provisional execution to an approved definition without inferring targets from text.
opentrain_start_job_context_work_migration	Start a separately approved, frozen migration between exact definition versions.
opentrain_run_job_context_work_migration_batch	Continue the bounded crash-safe migration until its durable result is complete.

One durable session wins the ops:work-catalog-setup intent. Other sessions stand down. An inferred definition cannot activate itself: the responsible non-agent manager reviews its complete semantics and possible-duplicate packet, records the required typed approval, and only then may the winning agent append and activate the decided successor.

Every work execution mints exactly one coordinating Job Operations action. Its claim is the ownership authority. Long-running work uses opentrain_renew_job_context_action; responsibility changes use opentrain_handoff_job_context_action, after which the named recipient claims normally. No receipt transfers between agents.

The human-only WORK_COORDINATION_MODE policy selects OPEN, COORDINATED, or MANAGED. A null projection is unreadable and fail-closed, not an implicit OPEN. When a guarded mutation is refused, inspect its typed recovery details, begin the permitted defined or provisional execution, claim its action, and then retry against fresh canonical state.

External state remains unknown unless a current attestation covers it. opentrain_record_job_context_observation accepts a strict top-level externalAttestation for OBSERVED evidence and a top-level actorAgentLabel. Read the Agent Guide’s externalCoverage projection; expired, invalidated, superseded, branched, or unreadable evidence is not current.

See Dynamic Work Catalog for the complete lifecycle and agent protocol.

Attention-signal tools

Tool	Purpose
opentrain_list_job_context_signals	Page through deterministic signals in priority order. Shadow rules are excluded unless an authorized audit read explicitly includes them.
opentrain_get_job_context_signal	Read one privacy-safe signal, evidence references, revisions, and latest linked-action state.
opentrain_acknowledge_job_context_signal	Acknowledge one occurrence without claiming or clearing it.
opentrain_snooze_job_context_signal	Snooze one occurrence until a bounded future time without claiming or clearing it.
opentrain_dismiss_job_context_signal	Dismiss one occurrence with an audited reason. Recurrence or materially changed evidence can reopen work.
opentrain_claim_job_context_signal	Atomically create or reuse the linked action and acquire its authenticated lease. This is the only signal-to-owned-work path; it requires an active, fresh signal whose effective triage is open or acknowledged.

Treat signal priority as an investigation aid, not a proven root cause or permission to mutate canonical state. Stale and incomplete evaluator runs stay visible in context health, but are not presented as current actionable priorities. Only an evaluator clears the underlying condition; triage does not.

Coordination tools

Tool	Purpose
opentrain_list_job_context_actions	List actions and their status, owner, dependencies, due date, lease, and revision.
opentrain_create_job_context_action	Create one coordinated action with evidence and optional dependencies.
opentrain_claim_job_context_action	Claim an eligible action with an authenticated, expiring lease.
opentrain_release_job_context_action	Release the caller’s unexpired claim.
opentrain_complete_job_context_action	Complete the caller’s unexpired claim with a verified outcome receipt.
opentrain_cancel_job_context_action	Cancel nonterminal work with an audited reason.

Dependencies must be complete before claim. A different agent cannot take an unexpired claim, and an expired claimant cannot release or complete it. Every transition carries expectedActionRevision and an idempotency key.

Signal claims also fail closed for stale, incomplete, live-snoozed, dismissed, or shadow-rule signals. Refresh context and wait for a complete fresh evaluator result instead of turning health metadata into owned work.

Intent, proposal, and overlay tools

Tool	Purpose
opentrain_declare_job_context_intent	Declare spontaneous work before it begins. An overlapping active intent returns the current winner instead of creating a race.
opentrain_list_job_context_intents	Page through active or resolved intents.
opentrain_resolve_job_context_intent	Complete, abandon, reject, or promote the caller’s exact intent revision.
opentrain_submit_job_context_proposal	Record a non-enforced policy, workflow, priority, goal, exception, or capability alternative for review.
opentrain_list_job_context_proposals	Page through proposals and their review state.
opentrain_review_job_context_proposal	Accept or decline an exact proposal revision. Acceptance links separately authorized canonical work and executes nothing.
opentrain_withdraw_job_context_proposal	Withdraw the caller’s open proposal.
opentrain_get_job_context_overlays	Read TEAM, PERSONAL, and SESSION guidance with attribution and typed-reference lint results.
opentrain_set_job_context_overlay	Replace one exact overlay revision. An empty entry list clears that layer.

Use an intent when the work has no shared action yet. Use a proposal when a project manager wants a different workflow or policy. Use overlays for flexible guidance at the correct scope. TEAM guidance is owner-controlled, PERSONAL guidance belongs to one manager, and SESSION guidance is scratch context for one agent connection. Overlay text is untrusted and cannot change canonical gates, readiness, or effective policies.

When a recommendation suggests another OpenTrain feature, treat it as product discovery rather than write authority. For example, inspect the evidence and show a no-write LMS retraining outline before asking the employer to approve course creation or assignment.

Durable-context tools

Tool	Purpose
opentrain_publish_job_context_brief	Publish the objective and versioned typed readiness workflow.
opentrain_list_job_context_decisions	Page through durable policies, judgments, holds, and exceptions with current, superseded, scheduled, or expired status and explicit visibility.
opentrain_record_job_context_decision	Record or supersede a policy, judgment, hold, or approved exception.
opentrain_list_job_context_observations	Page through typed evidence, inferences, and recommendations with explicit visibility, optionally scoped to one person.
opentrain_record_job_context_observation	Record typed external evidence, inference, or recommendation.
opentrain_acknowledge_job_context	Checkpoint the last fully consumed context revision.
opentrain_record_job_context_handoff	Leave a structured summary and open items for the next manager or agent.

Typed-policy and Agent Guide tools

Tool	Purpose
opentrain_get_job_context_effective_policies	Read the current typed-policy head per key and enforcement state.
opentrain_list_job_context_policy_history	Page through append-only attributed policy revisions, including superseded and expired history.
opentrain_record_job_context_policy	Record the first typed policy revision or supersede the exact active decision head.
opentrain_verify_job_context_policy_enforcement	Attach verified evidence to an externally enforced policy that is still pending.
opentrain_get_job_context_agent_guide	Read the composite Agent Guide: the typed projection plus the published Playbook and open-proposal count, as JSON and Markdown.
opentrain_get_job_context_playbook	Read the published Playbook head.
opentrain_list_job_context_playbook_versions	Page the newest-first Playbook version history.
opentrain_get_job_context_playbook_version	Read one exact published version.
opentrain_get_job_context_playbook_delta	Read the exact section delta between two versions, including removedSectionIds tombstones.
opentrain_submit_job_context_playbook_proposal	Submit a SECTION_UPSERT, SECTION_REMOVE, or NOTE proposal (recommended, never enforced).
opentrain_list_job_context_playbook_proposals	List proposals oldest first with effective expiry and staleness against the head.
opentrain_resolve_job_context_playbook_proposal	Accept, decline, or withdraw an exact proposal revision.
opentrain_publish_job_context_playbook	Publish a Playbook version from the closed editor-subset document. Human job-manager court only.
opentrain_get_job_context_operating_guide	Read the canonical typed projection alone (the Agent Guide without the Playbook). Kept for existing clients.

The Agent Guide is also exposed as the read-only MCP resource template opentrain://jobs/{jobId}/operations/agent-guide with MIME type text/markdown; opentrain://jobs/{jobId}/operations/guide carries the canonical projection only. Use the tool when you need structured JSON and exact revision/checksum fields; use the resource when an MCP host wants the guide as a durable instruction document. Resource discovery is optional—the initial context call already carries the guide digest and remains the required bootstrap, and the initialize protocol directs the one Agent Guide read and the exact delta follow-up automatically. See Follow and Improve the Agent Guide.

Use a typed policy—not chat history, an observation, or a local prompt—when a change governs the job-wide workflow or agent behavior. Policy records preserve the approving user, recording user, recording agent, effective time, supersession, and enforcement target. Fetch context and the guide again after a change and verify their revisions and checksum.

GUIDE with status APPLIED means OpenTrain published the rule in the shared guide. It does not assert runtime enforcement elsewhere. The TRAINING_PRODUCTION_GATE v1 payload accepts only schemaVersion and basis; record a one-production-task stop instruction separately as OPERATING_RULE.first-production-task-limit with the GUIDE target.

The Agent Guide is the shared AGENTS.md-equivalent for the job. Its typed projection is read-only; canonical records and effective typed policies remain authoritative, and the published Playbook is guidance beneath them.

Context-changing mutations carry expectedContextRevision and an idempotency key. A 409-equivalent tool error means refresh and deliberately re-evaluate; never blind-retry a stale management decision.

Canonical pre-action check

Shared context intentionally excludes message bodies, assessment answers, identity documents, detailed location/fraud signals, provider secrets, and other sensitive payloads. Immediately before an outbound message or consequential write, use the canonical OpenTrain tool for the affected record and conversation. If another employer teammate already responded or the worker already completed the requested gate, discard the stale action.

For claimed context work, call opentrain_send_managed_job_message. Include a complete jobOperationsGuard with the exact jobId, context revision, action ID, action revision, signed claim receipt, and expectedLatestMessageId. The latest message field is null only when the authorized conversation was observed empty. The idempotency key must be 8–128 characters using letters, numbers, ., _, :, or -.

This tool requires both messages:write and messages:manage. OpenTrain resolves the authorized Job Message or Proposal Message to its canonical job, then commits the message and context advance atomically. Any stale state fails before message or notification creation. The generic opentrain_send_message tool deliberately accepts no guard and does not advance shared context.

Structured results

Tools return machine-readable structuredContent, including the resource IDs, context/action revisions, completeness, and replay state returned by the API. Agents should reason from those fields instead of parsing display prose.

See the Shared Job Context concept, live-job guide, and HTTP reference.