> ## Documentation Index
> Fetch the complete documentation index at: https://opentrain.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP: Shared Job Context

> MCP tools and automatic initialize guidance for safe live-job management across OpenTrain agents and employer team members.

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 operating-guide 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 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.
</Warning>

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

## 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 operating-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_operating_guide`       | Read the generated structured Job Operating Guide and deterministic Markdown rendering.         |

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](/docs/developers/concepts/shared-job-context), [live-job guide](/docs/developers/guides/manage-live-jobs-with-shared-context), and [HTTP reference](/docs/developers/api-reference/job-operations/overview).