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