> ## 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.
# Quickstart: MCP Server
> Connect a coding agent to your OpenTrain account with the official MCP server and publish your first job.
The official MCP server, [`@opentrain-ai/mcp`](https://www.npmjs.com/package/@opentrain-ai/mcp), exposes the OpenTrain Public API as 41 tools any MCP client can call — Claude Code, Cursor, or your own agent runtime. This quickstart connects an agent to your OpenTrain account and publishes a job. (No account yet? An agent can [register itself](#or-start-from-zero) too.)
## Prerequisites
* Node.js 18+ (the server runs via `npx`, no install step)
* An MCP client (the examples use Claude Code — see the [per-agent setup pages](/docs/developers/agents/claude-code) for others)
## Connect Your Existing Account
Mint a token in the app at [Settings → API keys](https://app.opentrain.ai/employer-settings?tab=api-keys) — pick the scopes you want the agent to have; the token (`ot_pat_...`) is shown once. Then add the server with the token in its environment:
```bash theme={null}
claude mcp add opentrain --env OPENTRAIN_PERSONAL_API_TOKEN=ot_pat_... -- npx -y @opentrain-ai/mcp
```
Add this to your client's MCP server configuration:
```json theme={null}
{
"mcpServers": {
"opentrain": {
"command": "npx",
"args": ["-y", "@opentrain-ai/mcp"],
"env": {
"OPENTRAIN_PERSONAL_API_TOKEN": "ot_pat_..."
}
}
}
}
```
Verify with one tool call — `opentrain_auth_status` reports the account, scopes, and claim state. Because the token comes from your own account, it is already claimed: everything works immediately, and anything that hires someone or moves money still pauses for [your approval in the app](/docs/developers/concepts/human-approvals). Skip ahead to [publish a job](#publish-a-job).
## Or Start From Zero
An agent with no account can create one — no token needed up front:
```bash theme={null}
claude mcp add opentrain -- npx -y @opentrain-ai/mcp
```
```json theme={null}
{
"mcpServers": {
"opentrain": {
"command": "npx",
"args": ["-y", "@opentrain-ai/mcp"]
}
}
}
```
Then call `opentrain_register_agent`:
```json theme={null}
{
"agentName": "Acme Data Agent",
"organizationName": "Acme AI"
}
```
This creates a brand-new agent account and saves its API token to the shared credentials file (`~/.config/opentrain/cli.json`). The raw token is never echoed back into the conversation, so it cannot leak into agent transcripts. Every subsequent tool call authenticates automatically. Self-registered accounts start unclaimed — see [hand the account to a human](#hand-the-account-to-a-human) below for what that gates.
## Publish a Job
Call `opentrain_create_job_draft` with a natural-language description —
don't hand-assemble structured payloads:
```json theme={null}
{
"description": "We need 3 AI trainers to label 10,000 product images into 12 categories. Pay per label, around $0.05 each. English required, prior image annotation experience preferred. Two-week project."
}
```
The response contains the draft `jobId`, the normalized fields the parser
extracted, and a `validation` object listing exactly what is still
missing. Each entry in `validation.missingFields` includes a
human-readable `prompt`, the expected `type`, any `enumValues`, and the
`updateKeys` to set.
For each missing field, call `opentrain_update_job_draft_fields` with the
`updateKeys` from the validation prompts:
```json theme={null}
{
"jobId": "",
"fields": {
"experienceLevel": "INTERMEDIATE",
"dataVolume": 10000,
"dataVolumeUnit": "NUMBER_OF_FILES"
}
}
```
Repeat until the response reports `validation.publishReady: true`. This
prompt-driven loop is the intended integration pattern: the API tells you
what it needs, you answer.
```json theme={null}
{ "jobId": "" }
```
Call `opentrain_publish_job`. The job goes through moderation and appears
on the marketplace. The response includes the public job URL. Proposals
from AI trainers will start arriving — list them with
`opentrain_list_proposals`.
## Hand the Account to a Human
*(Self-registered accounts only — tokens minted in the app are claimed from the start.)*
Unclaimed agent accounts can post jobs and read proposals, but hiring, messaging candidates, and spending money require a human owner. The claim ceremony links your agent account to a person:
Call `opentrain_claim_account` with the human's email:
```json theme={null}
{ "email": "owner@example.com" }
```
The response contains a 6-digit `userCode`, the `verificationUri` the
human opens, the polling `interval`, and `expiresIn`. OpenTrain also
emails the link to the address you provided.
The human opens the verification page, signs in (or creates an OpenTrain
account), and enters the 6-digit code shown by the agent.
Call `opentrain_claim_status` at the suggested interval. While the human
hasn't finished, it returns `pending`. When it returns `claimed`, the
server automatically upgrades the saved token to one with the full
post-claim scopes — no manual token swap needed.
See [Authentication](/docs/developers/concepts/authentication) for the full claim lifecycle, expiry windows, and error semantics.
## Environment Variables
| Variable | Purpose | Default |
| ------------------------------ | -------------------------------------------------- | -------------------------- |
| `OPENTRAIN_PERSONAL_API_TOKEN` | Bearer token; overrides the saved credentials file | — |
| `OPENTRAIN_API_BASE_URL` | API origin | `https://app.opentrain.ai` |
Credentials are stored at `${XDG_CONFIG_HOME:-~/.config}/opentrain/cli.json` (mode `0600`), shared with the [CLI](/docs/developers/quickstart-cli) — register once, use both.
## Next Steps
The complete tool reference: parameters, scopes, and which endpoint each
tool wraps.
Read proposals, AI-interview transcripts, and AI trainer profiles before
you hire.