ValcairnRequest access

Use Valcairn from AI assistants

Let Claude, Cursor, VS Code or Codex check your training files, start training runs after you confirm the plan, follow them, compare models and verify signed records.

The valcairn package is not on npm yet, so npx valcairn does not work today. Until it is, run it from a checkout of the Valcairn repository: replace npx -y valcairn with node <checkout>/packages/valcairn/bin/valcairn.js after npm install in packages/valcairn.

1. Create an API key

On your workspace's API keys page (Team, or Compute in a personal workspace), create a key and copy it with the workspace id. A read-only key can check, read and verify; a full key can also start runs. The key acts as you, in that workspace only. Revoke it there at any time.

2. Add the server to your assistant

Claude Code

Run once in a terminal:

claude mcp add valcairn --env VALCAIRN_URL=https://your-valcairn-site --env VALCAIRN_WORKSPACE=<workspace id> --env VALCAIRN_API_KEY=vck_… -- npx -y valcairn mcp

Claude Desktop

Add to claude_desktop_config.json (Settings > Developer > Edit config):

{
  "mcpServers": {
    "valcairn": {
      "command": "npx",
      "args": [
        "-y",
        "valcairn",
        "mcp"
      ],
      "env": {
        "VALCAIRN_URL": "https://your-valcairn-site",
        "VALCAIRN_WORKSPACE": "<workspace id>",
        "VALCAIRN_API_KEY": "vck_…"
      }
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json, or .cursor/mcp.json in a project:

{
  "mcpServers": {
    "valcairn": {
      "command": "npx",
      "args": [
        "-y",
        "valcairn",
        "mcp"
      ],
      "env": {
        "VALCAIRN_URL": "https://your-valcairn-site",
        "VALCAIRN_WORKSPACE": "<workspace id>",
        "VALCAIRN_API_KEY": "vck_…"
      }
    }
  }
}

VS Code

Add to .vscode/mcp.json:

{
  "servers": {
    "valcairn": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "valcairn",
        "mcp"
      ],
      "env": {
        "VALCAIRN_URL": "https://your-valcairn-site",
        "VALCAIRN_WORKSPACE": "<workspace id>",
        "VALCAIRN_API_KEY": "vck_…"
      }
    }
  }
}

Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.valcairn]
command = "npx"
args = ["-y", "valcairn", "mcp"]
env = { VALCAIRN_URL = "https://your-valcairn-site", VALCAIRN_WORKSPACE = "<workspace id>", VALCAIRN_API_KEY = "vck_…" }

Already signed in with valcairn login? Leave out the key: the server reads it from your keychain.

Tools

  • check_training_file: Checks a JSONL file on your computer and lists each problem by line. Local and free.
  • list_projects: Lists the workspace's projects and their ids.
  • get_run_status: State, progress and, on failure, the recorded reason of a training run.
  • verify_record: Checks a signed record offline and says what it proves and what it does not.
  • start_training: Returns the plan and a confirmation code first; starts only when called again with the code after you agree.
  • compare_models: Compares the tuned and original models' answers on the same frozen cases: wins, losses, ties. Saves a comparison record.

Nothing that uses machines or credits starts without a confirmation code the server issued for that exact request. Every call is recorded in the workspace audit trail with the key's name.

Instructions for coding agents

SKILL.md tells a coding agent the order of steps, when to ask you first and how to read each result. Save it as .claude/skills/valcairn/SKILL.md in a project, or point your agent's instructions file at it.

From a terminal

valcairn login --url https://your-valcairn-site --workspace <workspace id>
valcairn check train.jsonl
valcairn start --method lora --model Qwen/Qwen2.5-0.5B-Instruct --dataset <project id>
valcairn status <run id>
valcairn verify export.json --key <public key from /api/release-key>

Add --json to any command for output a program can read.

API reference · Contact