> ## 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: Instructions Tools

> Eleven grouped MCP tools and three versioned resources for authoring, reviewing, and publishing instruction manuals from any MCP-capable agent.

The OpenTrain MCP server exposes the complete [instruction-manual surface](/docs/developers/concepts/instruction-manuals) 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](/docs/developers/api-reference/instructions/capabilities).

## 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](/docs/developers/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`).