MCP: Instructions Tools

The OpenTrain MCP server exposes the complete instruction-manual surface as eleven grouped, context-efficient tools plus three versioned resources. Available in the local stdio package @opentrain-ai/mcp 0.3.0 or later, and on the hosted MCP endpoint (https://app.opentrain.ai/mcp) with the same tool names and exact schemas. Nested changeset operations are fully typed and discriminated by kind. Grouped tool schemas expose the shared action envelope; action-specific required IDs and bodies are also validated after dispatch, so clients should use the selected action’s description/examples rather than assuming every invalid action combination is rejected by the top-level schema alone. Scope requirements match the wrapped API endpoints.

Tools

Tool	Actions	What it does
`opentrain_instructions_discover`	—	Read the canonical schema version, node/mark/attribute vocabulary, patch operations, audiences, and asset limits before authoring.
`opentrain_instructions_workspaces`	`list` `get` `create` `update` `archive`	Manage the permission and asset boundary. Creation requires employer organization membership; archive retains rows but removes public-API access.
`opentrain_instructions_permissions`	`list` `grant` `revoke`	Owner-governed per-user workspace access. Creation persists the owner’s `OWNER` record; grant upserts `EDITOR`/`REVIEWER`/`VIEWER`.
`opentrain_instructions_manuals`	`list` `get` `create` `update` `archive`	Manuals, default audiences, and job/folder/work-project bindings.
`opentrain_instructions_read`	`tree` `page`	Bounded manual outlines and single canonical pages (`json`, `html`, or `markdown` with its loss report).
`opentrain_instructions_search`	—	Search accessible working-draft pages with an optional exact-match audience filter; publication snapshots are not searched.
`opentrain_instructions_changeset`	`validate` `diff` `apply` `submit` `list` `get` `approve` `reject`	Page-content and tree mutation lifecycle—see below.
`opentrain_instructions_versions`	`list` `diff` `restore`	Immutable revisions; restore lands as a new audited revision.
`opentrain_instructions_assets`	`prepare` `finalize` `list` `get`	Private image/file/audio/video media. Video reads return an MCP resource link plus derivative placeholders instead of embedded bytes.
`opentrain_instructions_render`	—	HTML/Markdown previews of saved pages or ad-hoc content, with machine-readable loss reports.
`opentrain_instructions_publish`	—	Publish an immutable, audience-filtered snapshot at an exact manual revision (`instructions:publish`).

The changeset tool

opentrain_instructions_changeset carries the full write lifecycle:

validate / diff dry-run a changeset body without writing.
apply with a changeset body writes atomically (all operations or none), guarded by base revisions/checksums and an optional idempotencyKey. A conflicted apply returns its structured conflicts as the tool result — machine-readable, not an opaque error.
submit stores the changeset as a reviewed proposal instead of applying it.
approve / reject (by changesetId, optional decisionNote) are the reviewer decisions.
apply with a changesetId and no body applies a stored APPROVED proposal through the same guarded write path, returning the updated changeset record plus the application result; drift records the proposal as CONFLICTED.

Nested creation works in one call: a CREATE_PAGE operation with clientPageKey: "x" can be referenced by sibling operations as parentPageId: "new:x", in any operation order.

Resources

Resource URI	Contents
`opentrain://instructions/v1/capabilities`	The canonical schema and vocabulary document.
`opentrain://instructions/v1/pages/{pageId}`	One page’s canonical TipTap JSON without loading the whole manual.
`opentrain://instructions/v1/manuals/{manualId}/publications/{publicationNumber}/{audience}`	An immutable, audience-filtered publication manifest.

Setup

See the MCP overview for installation and authentication. The instruction tools respect the same token scopes and workspace roles as the HTTP API: reads need instructions:read; direct writes need instructions:write; proposal validate/diff/submit need instructions:propose plus EDITOR or OWNER; reviewer decisions need instructions:review plus REVIEWER or OWNER; permission management and publishing need instructions:publish plus OWNER (permission listing also needs instructions:read).

Getting started

Connect your agent

Core concepts

Guides

API reference

CLI

MCP server

Annotation platforms

MCP: Instructions Tools

Tools

The changeset tool

Resources

Setup

​Tools

​The changeset tool

​Resources

​Setup

Tools

The changeset tool

Resources

Setup