Skip to main content
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 on OpenTrain without writing any HTTP code. It runs locally over stdio and registers as the server name opentrain. The tool reference documents all 41 tools. 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:
1

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

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

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_..."
      }
    }
  }
}
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).

​
MCP vs CLI vs Raw HTTP

SurfaceBest forCredentials
MCP serverAgents inside MCP-capable frameworks (Claude Code, etc.) — no HTTP code neededShared cli.json or OPENTRAIN_PERSONAL_API_TOKEN
CLIShell-based agents and humans; scripting with --jsonShared cli.json or OT_API_TOKEN
Raw HTTPAny 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, 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.