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.

​

Context and reconciliation tools

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.

​

Attention-signal tools

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

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

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

​

Typed-policy and operating-guide tools

The same guide is also exposed as the read-only MCP resource template opentrain://jobs/{jobId}/operations/guide with MIME type text/markdown. Use the tool when you need structured JSON and exact revision/checksum fields; use the resource when an MCP host wants the shared operating guide as a durable instruction document. Resource discovery is optional—the initial context call already carries the guide digest and remains the required bootstrap. 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 generated guide is the shared AGENTS.md-equivalent for the job. It is a read-only projection; canonical records and effective typed policies remain authoritative. 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.