MCP Server Overview

The OpenTrain MCP server (@opentrain-ai/mcp) exposes the Public API and the agent auth endpoints as Model Context Protocol tools, so agent frameworks like Claude Code can hire AI trainers, maintain canonical job Instructions, safely assign and review Project To-dos and native quizzes, render the real LMS worker player for visual inspection, author adaptive Task Checklists, and review employer-private feedback without writing HTTP code. It runs locally over stdio and registers as the server name opentrain.

The tool reference documents the hiring and operations tools; Shared Job Context documents automatic live-job synchronization and coordination; the Instructions reference documents rich job pages; the Project To-dos reference documents assignment, quizzes, grading, release, and retakes; and the job quality reference covers Reviewer Feedback and Task Checklists. For a guided first run, start with the MCP quickstart.

Install

For Claude Code:

claude mcp add opentrain -- npx -y @opentrain-ai/mcp

For any other MCP client, add the server to your client’s MCP configuration:

{
  "mcpServers": {
    "opentrain": {
      "command": "npx",
      "args": ["-y", "@opentrain-ai/mcp"]
    }
  }
}

Node.js 18+ is required. The server communicates over stdio — no ports, no daemon.

Tokenless Onboarding

The MCP server is designed so an agent can start from absolutely nothing:

Register

Call opentrain_register_agent (no credentials needed). It creates an anonymous agent account via POST /api/agent/identity and saves the new ot_pat_ token to the shared config file, so every other tool works immediately. If saved credentials already exist, the tool refuses unless you pass force: true.

Work

Draft and publish jobs, review candidates, and read messages right away — these work pre-claim. See the scopes and capabilities page for what is gated.

Claim

Ask the human for their email and call opentrain_claim_account, then poll opentrain_claim_status — the claim ceremony. Once claimed, the stored token is upgraded automatically and money-adjacent tools (hiring, milestones, top-ups) unlock.

Credentials and Environment Variables

The server reads credentials in this order:

1. OPENTRAIN_PERSONAL_API_TOKEN — if set, it wins outright; the saved credentials file is not read at all.
2. The shared credentials file at ${XDG_CONFIG_HOME:-~/.config}/opentrain/cli.json — the same file the CLI uses. Registering or logging in through either surface makes the credentials available to both.

The base URL comes from OPENTRAIN_API_BASE_URL, then the saved file, then the default https://app.opentrain.ai.

To run the server against an existing account instead of registering a new one, set the token in your MCP client config:

{
  "mcpServers": {
    "opentrain": {
      "command": "npx",
      "args": ["-y", "@opentrain-ai/mcp"],
      "env": {
        "OPENTRAIN_PERSONAL_API_TOKEN": "ot_pat_..."
      }
    }
  }
}

Note

When OPENTRAIN_PERSONAL_API_TOKEN is set, opentrain_register_agent and the claim tools still write to the shared config file, but every API call keeps using the env token. Unset it if you want the freshly registered account to take effect.

Tool Output Model

Every tool returns two parallel representations:

• Text content — a human-readable summary (status, key fields, suggested next step), useful for models reasoning over results.
• structuredContent — the exact API response object, for programmatic consumption.

Failures return isError: true with the HTTP status, the error envelope’s code and message, and the details object when present (e.g. a claimUrl on 403 account_claim_required, or a billingUrl on 409 payment_method_required).

For covered live-job tools, MCP 0.11.0+ also returns a redacted sync envelope and exhaustive syncCoverage. The server keeps its session credential and signed per-job delivery tokens private, so they never enter model-visible text or structuredContent. Agents should inspect conflicts, recommendations, and exact next operations before the next write. See MCP: Shared Job Context.

MCP vs CLI vs Raw HTTP

Surface	Best for	Credentials
MCP server	Agents inside MCP-capable frameworks (Claude Code, etc.) — no HTTP code needed	Shared cli.json or OPENTRAIN_PERSONAL_API_TOKEN
CLI	Shell-based agents and humans; scripting with --json	Shared cli.json or OT_API_TOKEN
Raw HTTP	Any language or runtime; surfaces not wrapped by MCP/CLI (e.g. POST /tokens)	Authorization: Bearer header

All three hit the same API with the same scopes, workspace permissions, feature flags, and human co-sign rules — pick whichever fits your runtime. Each MCP tool’s requirements mirror the endpoint it wraps; the tool reference links every tool to its endpoint page.