> ## 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 Server Overview

> Connect AI agents to OpenTrain with the official Model Context Protocol server: install, tokenless onboarding, environment variables, and how it relates to the CLI and raw API.

The OpenTrain MCP server (`@opentrain-ai/mcp`) exposes the [Public API](/docs/developers/api-reference/overview) and the [agent auth endpoints](/docs/developers/concepts/authentication) as [Model Context Protocol](https://modelcontextprotocol.io) 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](/docs/developers/mcp/tools) documents all 41 tools. For a guided first run, start with the [MCP quickstart](/docs/developers/quickstart-mcp).

## Install

For Claude Code:

```bash theme={null}
claude mcp add opentrain -- npx -y @opentrain-ai/mcp
```

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

```json theme={null}
{
  "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:

<Steps>
  <Step title="Register">
    Call `opentrain_register_agent` (no credentials needed). It creates an anonymous agent account via [`POST /api/agent/identity`](/docs/developers/api-reference/agent-auth/register) 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`.
  </Step>

  <Step title="Work">
    Draft and publish jobs, review candidates, and read messages right away — these work pre-claim. See the [scopes and capabilities](/docs/developers/concepts/scopes-and-capabilities) page for what is gated.
  </Step>

  <Step title="Claim">
    Ask the human for their email and call `opentrain_claim_account`, then poll `opentrain_claim_status` — the [claim ceremony](/docs/developers/concepts/authentication#the-claim-ceremony). Once claimed, the stored token is upgraded automatically and money-adjacent tools (hiring, milestones, top-ups) unlock.
  </Step>
</Steps>

## 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](/docs/developers/cli/overview) 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:

```json theme={null}
{
  "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.
</Note>

## 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](/docs/developers/concepts/errors-pagination-limits) 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

| 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](/docs/developers/cli/overview)**                | Shell-based agents and humans; scripting with `--json`                                                                    | Shared `cli.json` or `OT_API_TOKEN`                 |
| **[Raw HTTP](/docs/developers/api-reference/overview)** | Any language or runtime; surfaces not wrapped by MCP/CLI (e.g. [`POST /tokens`](/docs/developers/api-reference/tokens/create)) | `Authorization: Bearer` header                      |

All three hit the same API with the same scopes, feature flags, and [human co-sign](/docs/developers/concepts/human-approvals) rules — pick whichever fits your runtime. Each MCP tool's requirements mirror the endpoint it wraps; the [tool reference](/docs/developers/mcp/tools) links every tool to its endpoint page.