MCP server¶
New in 0.2 (pre-release)
astro-weights mcp RUN_DIR is a stdio MCP server for one run directory. It serves seven tools. Any MCP client can drive it: the built-in editors of astro-weights run, Claude Code, Codex or your own.
Related pages: Tutorial: first agent run for a first run, Explanation: agent budgets and sandbox for why the budget and sandbox work as they do.
Start¶
Both start the same server. Install the mcp extra; forward_pass also needs hf:
- The server reads
RUN_DIR/run.jsononce, at start. Write it before you start the server. - One server process per run directory. The ledger and the record have no cross-process lock.
- Exit code 2, with
error: ...on stderr, whenrun.jsonis missing or bad, or when it differs from an existing run record onseed,editor,modelorlimits.astro-weights mcpalso exits 2, with the install hint, when themcpextra is missing. --unsafe-kernelruns agent code without an OS sandbox when none works. It changes nothing where a sandbox works. See Explanation: agent budgets and sandbox.
Client config¶
Most clients take a command and its arguments. Use an absolute RUN_DIR; a client may start the server from another directory.
{
"mcpServers": {
"astro-weights": {
"command": "astro-weights",
"args": ["mcp", "/path/to/run"]
}
}
}
Per client: Claude Code, Codex, Claude Agent SDK.
Run directory¶
| Path | Written by | Holds |
|---|---|---|
run.json |
you, or astro-weights run |
seed, labels, limits, model and settings; see run.json |
record.jsonl |
server | run history, one JSON event per line; see Run record |
ledger.jsonl |
server | budget: one charge, refuse, fail or reset per line. The only source of truth for spend |
jobs/<handle>.json |
server | one file per job: request, state, result |
edits/ |
server | manifest.json plus one <sha256>.safetensors per stored edit |
forward/<id>/ |
server | results of one forward_pass job: <key>.npy arrays, texts*.json |
kernel/ |
agent code | the only directory exec_python code can write |
kernel.log, kernel.started |
server | the kernel process's log, and a marker that a kernel has run here |
export/ |
server, on finish |
adapter/ and, with export.base_gguf, model.gguf |
astro-weights run also writes config.toml here; see Reference: CLI.
run.json¶
| Key | Type | Default |
|---|---|---|
seed |
int | required |
editor |
non-empty string, a label for the record | required |
model |
string or null, a label for the record |
required |
limits |
object with exactly the four keys below | required |
model_dir |
path to the model, relative to RUN_DIR or absolute |
absent: exec_python and forward_pass return ... is not available yet |
kernel |
object: timeout_s (number > 0), mem_gib (int >= 1, Linux only), allow_nested_userns (bool: sandbox with bwrap older than 0.8) |
600.0, 16, false |
forward |
object: device (auto, cpu, cuda), dtype (auto, float32, bfloat16, float16), max_new_tokens (int from 1 to 32768) |
auto, auto, 4096 |
export |
object: rank (int >= 1), max_rel_residual (finite number >= 0), base_gguf (path, relative to RUN_DIR or absolute), gguf_out_type (q8_0, f16, bf16) |
8, 0.05, absent, q8_0 |
An unknown key inside kernel, forward or export is an error.
Limits¶
All four keys are required. 0 allows none.
| Key | Type | Counts | Past the limit |
|---|---|---|---|
forward_passes |
int >= 0 | finished forward_pass jobs |
refused before the job starts |
code_runs |
int >= 0 | finished exec_python jobs |
refused before the job starts |
tokens |
int >= 0 | tokens sent with report_usage |
still recorded; listed in over |
dollars |
finite number >= 0 | dollars sent with report_usage |
still recorded; listed in over |
limits cannot change once the run has a record: a restart with other limits exits 2.
Tools¶
| Tool | Arguments | Returns | Charges | Mode |
|---|---|---|---|---|
exec_python |
code: string |
{"handle", "state": "queued"} |
1 code_runs when the job finishes |
submit, then poll |
forward_pass |
request: object |
{"handle", "state": "queued"} |
1 forward_passes when the job finishes |
submit, then poll |
status |
handle: string |
the job plus budget |
nothing | sync |
finish |
summary: string |
{"state": "finished", "budget", "export"} |
nothing | sync, works once |
report_usage |
tokens, dollars, turn, model |
{"budget", "over"} |
tokens and dollars |
sync, editor-only |
check_spend |
estimate |
{"ok", "budget"} |
nothing | sync, editor-only |
report_refusal |
category, model, detail (optional) |
{"recorded": true} |
nothing | sync, editor-only |
A refusal is an ordinary tool result with an error key, not an MCP protocol error. Check every result for error.
Jobs and status¶
exec_python and forward_pass return at once. The work runs in a background thread. Poll status(handle) until state is done or failed.
status returns:
| Key | Value |
|---|---|
handle |
exec-<16 hex digits> or forward-<16 hex digits> |
kind |
exec or forward |
state |
queued, running, done or failed |
params |
the request as stored; a forward_pass request has its defaults filled in |
result |
object when done, else null |
error |
string when failed, else null; at most 2000 characters |
created, updated |
Unix times, seconds |
budget |
the budget object |
- A
donejob was charged. Afailedjob is free. A job that failed because its work raised adds 1 to that kind's failure streak. - A restarted server marks every
queuedorrunningjobfailedwith errorserver restarted.
exec_python¶
Runs one cell in a sandboxed kernel that has numpy (np) and the standard library only. Variables stay between cells. The kernel's helpers (NAMES, names(), load, load_original, save_edit, drop_edit, edited(), forward_result) are described in Explanation: agent budgets and sandbox.
Job result:
| Key | Value |
|---|---|
ok |
false when the cell raised, was killed or the kernel died |
output |
what the cell printed, plus the traceback when it raised; cut at 10000 characters |
restarted |
true when this cell started a fresh kernel after an earlier one was lost; earlier variables are gone |
A cell that raises still ends done, with ok: false, and costs 1 code_runs. A cell that runs longer than kernel.timeout_s is killed and its variables are lost.
forward_pass¶
Runs the model in the server process, on the base or the edited weights. The request is checked in the tool call; a bad one is refused for free and leaves no job. An unknown key is refused.
"kind": "teacher_forced":
| Key | Type | Default |
|---|---|---|
texts |
non-empty list of non-blank strings, at most 1024 | required |
return |
non-empty list drawn from hidden, mlp, attn, logprobs |
required |
layers |
list of layer indices, no repeats | []; required for hidden, mlp and attn |
last_tokens |
int from 1 to 32768 | 36 |
arm |
base or edited |
required |
"kind": "generate":
| Key | Type | Default |
|---|---|---|
prompts |
non-empty list of non-blank strings, at most 512 | required |
max_new_tokens |
int from 1 to forward.max_new_tokens of run.json |
required |
arm |
base, edited or both |
required |
seed |
int from 0 to 2**63 - 1 | 0 |
temperature |
finite number >= 0; 0 is greedy | 0.0 |
Limits on a request:
- Each text or prompt: at least 1 token, at most 32768. All together: at most 524288. A prompt is counted after the model's chat template is applied, when the tokenizer has one.
teacher_forced:len(texts) * last_tokensat most 4000000.attn: at most 2 texts of at most 2048 tokens each, full attention layers only, andtexts * layers * heads * max_tokens**2at most 268435456 (2**28).armeditedorbothneeds at least one stored edit.
Job result for teacher_forced: kind, arm, n, total_tokens, last_tokens, edits (weight name to sha256 of the edit applied), arrays (key to shape) and keys. Array keys: hidden_l<layer>, mlp_l<layer>, attn_l<layer>_t<text>, logprobs_top_ids, logprobs_top, logprobs_target.
Job result for generate: kind, arm, n, total_tokens, max_new_tokens, seed, temperature, arms and keys. arms has one entry per arm run, each with edits, texts, truncated, n_tokens and hit_cap. texts there is a preview: at most 4096 characters per text and 32768 over the whole result. keys is ["texts"], or ["texts_base", "texts_edited"] for "arm": "both".
The result holds shapes and previews only. Read an array or the full texts in exec_python with forward_result(handle, key), using a key from keys.
finish¶
Ends the run. Works once; summary is stored in the record, cut at 2000 characters.
When run.json names a model_dir and there are stored edits, the server exports them to RUN_DIR/export/: a PEFT LoRA adapter in export/adapter and, with export.base_gguf, a merged GGUF at export/model.gguf. Each edit is cut to export.rank by truncated SVD and must keep its relative residual within export.max_rel_residual.
The result is {"state": "finished", "budget": {...}} plus one of:
| Case | Keys added |
|---|---|
| exported | "export": {"adapter", "gguf", "residuals", "rank"}; gguf is null without export.base_gguf |
| no stored edits | "export": null, "note": "no edits: nothing to export" |
no model_dir |
"export": null, "note": "no model_dir: nothing to export" |
| export failed | "export": null, "export_error": "<ExceptionType>: <message>" |
A failed export does not stop the run from finishing. Inspect the adapter with astro-weights inspect.
Editor-only tools¶
report_usage, check_spend and report_refusal are for the client program, not for the model. A client that shows tools to a model should hide these three; the built-in editors do. Claude Code and Codex show all seven.
| Tool | Arguments | Result |
|---|---|---|
report_usage |
tokens and turn: ints >= 0. dollars: finite number >= 0. model: non-empty string, at most 200 characters |
{"budget", "over"}; over lists the kinds now past their limit. Bad arguments: {"error": "bad usage report"} |
check_spend |
estimate: finite number >= 0, in dollars |
{"ok": true, "budget"} or {"ok": false, "error", "budget"}. Writes nothing. Bad argument: {"error": "estimate must be a finite number >= 0"} |
report_refusal |
category: non-empty string, cut at 200 characters. model: as above. detail: string, default "", cut at 2000 |
{"recorded": true}. Bad arguments: {"error": "bad refusal report"} |
report_usageis always recorded, even past a limit and afterfinish. Usage recorded afterfinishis not in thefinishresult'sbudget; read spend fromledger.jsonl.check_spendwith estimate 0 is ok even whendollarsis already past its limit, but not while thedollarsfailure streak blocks work.
Budget object¶
status, finish, report_usage, check_spend and most refusals return budget:
| Key | Value |
|---|---|
limits |
the four limits of run.json |
used |
charged so far, per kind |
remaining |
limit minus used, per kind, never below 0 |
streaks |
failures in a row, per kind |
max_failures |
3 |
Errors and refusals¶
Every refusal is free.
| When | Result | Also written |
|---|---|---|
| limit reached, at submit | {"error": "code_runs budget exhausted: used 2 of 2, requested 1", "budget"} (or forward_passes) |
ledger refuse; record refusal, category budget |
| job ends past the limit | job failed, error budget exhausted, result withheld |
nothing |
| 3 failed jobs of one kind in a row | {"error": "code_runs failed 3 times in a row; an operator must fix this and reset it", "budget"} |
ledger refuse; record refusal, category failure_streak |
bad forward_pass request |
{"error": "bad request: ...", "budget"} |
record refusal, category bad_request |
| the request check itself fails | {"error": "<ExceptionType>: ...", "budget"} |
record refusal, category forward_check |
| no working OS sandbox | exec_python: {"error": "no OS sandbox: <why>; pass allow_unsafe=True (CLI: --unsafe-kernel) to run agent code without a sandbox"} |
record sandbox_unavailable |
no model_dir |
{"error": "exec_python is not available yet"} (or forward_pass) |
record tool_unavailable |
hf extra missing |
forward_pass: {"error": "forward_pass is not available yet: it needs torch and transformers: pip install 'astro-weights[hf]'"} |
record tool_unavailable |
after finish |
{"error": "run already finished"} from every tool but status and report_usage |
nothing |
status on a bad handle |
{"error": "unknown handle"} |
nothing |
- The sandbox error names the Python argument
allow_unsafe. From the command line the switch is--unsafe-kernel. - A failure streak is reset by the next charge of that kind. Once it reaches 3, no tool and no CLI command resets it;
astro_weights.mcp.budget.Ledger.reset_failuresdoes, from Python, with the server stopped.
Run record¶
record.jsonl starts with a start line: seed, config (the limits), editor, model, library_version, library_commit, python, platform. Every line has event and time. Events the server writes:
| Event | Fields | When |
|---|---|---|
edit_saved |
tensor, rel_frobenius |
save_edit stored an edit |
edit_rejected |
tensor, error |
save_edit refused one |
edit_dropped |
tensor |
drop_edit removed one |
kernel_restarted |
none | a cell started a fresh kernel after one was lost |
refusal |
category, editor, model, detail |
a refusal from the table above, or report_refusal |
usage |
turn, model, tokens, dollars |
report_usage |
tool_unavailable |
tool, sometimes error |
a work tool that cannot run was called |
sandbox_unavailable |
tool, error |
exec_python was called with no sandbox |
unsafe_kernel |
none | the server started with --unsafe-kernel |
sandbox_compat |
lost |
the kernel runs under bwrap without --disable-userns (kernel.allow_nested_userns on bwrap older than 0.8) |
summary |
text |
finish |
export |
adapter, gguf, residuals, rank |
finish exported the edits |
export_skipped |
reason |
finish found no edits |
export_failed |
error |
the export raised |
finish |
budget, outcome (finished) |
last step of finish |
Python API of the server modules: Reference.