Neurarch MCP Server

neurarch-mcp

Know what a GPU job needs before it takes a reservation, from inside your agent. An MCP server for Claude Code, Cursor, Claude Desktop, VS Code, Windsurf and Codex.

• Small jobs: pack them or move them to a smaller card.
• Large jobs: the right card count and sharding the first time.
• Agent-launched jobs: a gate before the GPU, because an agent cannot size its own job.

Call size_training_job before a job launches and the agent learns, for the model, batch and card in front of it: the peak memory (weights and optimizer state, activations, stored attention scores, each shown), the smallest card that holds it, the largest batch each card holds, a two-card split when one card does not, what one run costs, and a one-line verdict such as will not fit a T4: needs ~30 GB with headroom (peak 26 GB) at batch 32, seq 2048, use L40S or batch <= 12. history adds what that structure measured the last time it ran in your organisation. After a CUDA out-of-memory error, diagnose_oom reads the message against the same estimate and names the cause (too big for the card, fragmentation, another process, logits over a large vocabulary, growth during the run) with the least invasive fix first. Then whether it forward-passes: the structural checks the CI bot runs (lint_model, check_design), offline too. It answers the same whether a person or an agent wrote the job, which is the question the person who owns the GPU bill is asking.

See it

Before launch. The job does not fit the card it was about to take, so the agent sizes it again at the batch the tool named:

A model straight from Hugging Face. Qwen3-8B fits no single card at batch 8, and on eight A100-40s only sharded:

After a CUDA out-of-memory error. The message is read against the same estimate, and the cause comes back with the fix that leaves training unchanged listed first:

Not every OOM means a smaller batch. When the job fits and the allocator does not, the fix leaves training as it is:

Whether it forward-passes. The shipped examples/tiny-vit.py builds an attention layer its head count does not divide:

Without the agent asking. neurarch-mcp hook sizes a python train.py launch before the Bash call runs and blocks the one that will not fit:

Every number in these recordings is copied from the tools' real output (0.17.1 and 0.17.2) on phi3-mini, tiny-vit.py and hf:Qwen/Qwen3-8B; the error texts are examples and the model's closing sentences are scripted. scripts/demo-anim/ has the calls.

The memory number is a calibrated estimate of the training peak under AdamW with bf16 autocast, not a measurement: 1.2 x 16 bytes per parameter, plus, per sample in bf16, 0.88 x every layer output, 3.64 x stored attention scores (eager attention only; SDPA and flash keep none), 1.34 x each layer's weight-matrix intermediates, 5.2 x recurrent gate states and 2.02 x the largest single tensor. Fitted on 178 measured runs across 41 architectures, out-of-memory runs included. Held out one architecture at a time, the median error is 7% above 1 GB and it flagged 113 of the 131 times a run did not fit a 16, 24, 40 or 80 GB card, where accelerate estimate-memory flagged at most 8. On 25 runs measured after the fit, at the edge of a 24 GB card, the median miss is 14%, so read it as a fit check before a precise number. Every run is public: neurarch.com/memory-calibration.

Get the graph by tracing the model for real shapes, or point the server at a saved graph, a PyTorch .py, or a Hugging Face repo. Every tool but three runs on your machine, offline, with no API key and no account. Two of the three, plan and history, read what a frontier model structurally cannot know: what happened the last time this exact structure trained here. That is not in the weights and not in the repository. The third, model_changes, reads the public record of what changed in a Hugging Face model between revisions. They are the only tools in this package that open a socket.

Install

claude mcp add neurarch -- npx -y neurarch-mcp /abs/path/to/model.py        # Claude Code

Or, in Claude Code, the server, the launch hook and the skill in one plugin: /plugin marketplace add neurarch-ai/neurarch-mcp, then /plugin install neurarch@neurarch-ai.

Per-client config for Claude Desktop, Cursor, VS Code, Windsurf and Codex is below. Node 20+ is the only requirement; there is no install step beyond npx.

What it looks like

An agent about to launch a fine-tune on a T4, against src/test/templates/phi3-mini.neurarch.json (a 310M-parameter Phi-3 block, one of the Neurarch app's templates). The output is the tool's, trimmed:

Agent ▸ (calls size_training_job { batch_size: 32, gpu: "T4" })
  verdict        will not fit a T4: needs ~30 GB with headroom (peak 26 GB) at batch 32,
                 seq 2048, use L40S or batch <= 12
  memory         peak 26.38 GB = 5.96 weights + optimizer state, 20.42 activations
                 (SDPA: the 40.13 GB of attention scores eager would keep are not counted)
  maxBatch       T4 12, L4 23, A10G 23, A100-40 45, L40S 56, A100-80 99, H100-80 99
  cost           $9.68 on a T4, 10 epochs over 50,000 samples (assumed; pass samples)
  forwardPasses  legal, no blockers
  lastRun        fingerprint 4e0b97b4: call history for what it measured last time

  (same job, attention: "eager", gpu: "A100-40")
  verdict        will not fit an A100-40: needs ~76 GB with headroom (peak 67 GB) at batch 32,
                 seq 2048, use A100-80 or batch <= 15
  memory         peak 66.51 GB = 5.96 weights + optimizer state, 60.55 activations
                 (40.13 GB of them the attention scores eager keeps)

A real exchange against examples/tiny-gpt.neurarch.json, about where the budget lives:

You ▸ Where does the parameter budget live, and is it safe to drop block_1?

Claude ▸ (calls describe_architecture)
  tiny-gpt: 8 layers, depth 7, 57.8M params, 8.27 GMACs.
  Heaviest by params: token_embedding (25.7M, 44%), lm_head (25.7M), block_0/1 (3.1M each).
  Heaviest by compute: lm_head, then the two decoder blocks. Validation: clean.

  (calls layer_impact { names: ["block_1"] })
  Downstream of block_1: final_norm and lm_head (shape-sensitive, weight-carrying), then output.

  The budget is dominated by the embedding + LM head (~89%), not the decoder blocks,
  so dropping block_1 frees only ~3.1M params (~5%) while removing one of just two
  decoder layers. It is structurally safe (final_norm just re-reads block_0's output),
  but it is the wrong lever if your goal is shrinking the model. Quantizing the
  embedding/head would do far more.

And whether it forward-passes, shown on examples/tiny-vit.py in the recording above. That is a runtime crash sitting in source that reads fine, found offline in milliseconds, with no key and no account. The same rule set the Neurarch CI action reports, so a clean result here is a clean CI run. The rules are measured (the crash rules: 96 of 96 blocked graphs crashed PyTorch forward, 80 of 80 passes ran); the static parser in front of them is the weaker half, and we measured that too.

Three ways in, in order of how well they work

A .neurarch.json saved from the Neurarch app (File → Save) is the fourth, and carries shapes, groups and design notes. Add --watch so the agent sees app-side saves without a restart.

The flow this server is built around, in one line each: size_training_job before any job launches, history for what that structure measured last time, trace_model for a graph with real shapes, plan for the card the CI bot posts, lint_model / check_design for whether it forward-passes, suggest_fix for the edit. Everything else answers a question one of those raised.

What the static parser can read

We measured it rather than describe it: docs/REAL_REPOS_STUDY.md runs the parser and linter over 116 model files from 59 popular repositories (nanoGPT, HF modeling_*.py, timm, torchvision, DiT, MAE, CLIP, Mamba, SAM, diffusers and more). The parser returns a graph for 86% of files and a graph a person would recognise as the model for 41% (Llama, Qwen2, Mistral and Gemma come back as 58-node graphs; nanoGPT as 72), up from 63% and 8% in August. Re-measured 2026-09-09 with per-edge provenance: every edge the importer chained from statement order rather than read out of forward() is marked, the rules that are about adjacency hold back on those, and block+warn findings fell from 92 to 37 with two thirds of the parser artefacts gone. Real defects found on either engine: still zero. The graph is good enough to orient with and not yet good enough to lint from; run trace_model before acting on a finding from a .py.

Three consequences are in this release. A graph from source carries a parseQuality grade (full, partial, thin) on describe_architecture and lint_model, with the fix named. Dimension rules are held back on layers whose dimension is still source text, and the count is reported as suppressed rather than dropped. And find_models marks thin parses partial so an agent does not build a plan on two layers. For real repositories, use neurarch-trace: it reads the numbers at runtime, which is the only place they exist.

Every read tool also takes an optional model_path, so one server covers a whole repository: ask about baseline.py, then variant_b.neurarch.json, then zoo:llama-3-8b, without restarting anything. find_models tells the agent what is there.

Tools

Start here: size the job before it launches

Before a multi-GPU or serving launch

check_parallel_layout says whether a TP / PP / DP / CP / EP split is legal, which pipeline stage is the straggler, the predicted step slowdown against a balanced split and the split that removes it, every time labelled predicted (per-card matmul efficiency fitted on public GEMM measurements, the 1F1B schedule simulated op by op, never timed):

check_parallel_layout { model_path: "hf:Qwen/Qwen3-8B", tp: 4, pp: 4, micro_batch: 1, global_batch: 32, seq_len: 4096, gpu: "h100" }
-> legal on 16 x h100-sxm; predicted 15.5% slower per step than a balanced split (slowest stage 3);
   split 10,10,9,7 is predicted 11.4% faster; bubble 8.6%; 1 warning

check_serving_config reads a vLLM, SGLang or llama.cpp launch line against the model's config.json, tokenizer_config.json, chat_template.jinja and generation_config.json and the card, and returns findings on TP against the heads, served length against the context, KV memory and concurrency, quantization against the card, and the chat template and sampler defaults (with against, what changed from the model it replaces):

check_serving_config { command: "vllm serve Qwen/Qwen3-8B -tp 4 --max-model-len 131072 --max-num-seqs 64", gpu: "l4", gpus: 4 }
-> blocked: Served length 131072 is past the model's 40960-token context
   (+ warn: --max-num-seqs 64, but at most 3 requests fit at the full 131072 tokens; info: no --reasoning-parser)

Both are the app's own checks (npx neurarch layout, npx neurarch serve-check), vendored in the plan bundle and offline; an hf: model needs --hf the first time.

Before a Hugging Face download moves under you

check_pins finds downloads that load whatever main points at on the day the job runs (from_pretrained, load_dataset, hf_hub_download, snapshot_download, pipeline, vllm serve, the SGLang server, hf download, YAML model keys), with the fix spelled for each file. It is the scanner behind npx neurarch pin-check, aligned with Bandit B615, and offline. model_changes says what a tracked model changed between revisions (config, tokenizer, chat template, generation defaults, weights), whether each change is breaking under the published rule, and with since_revision only what landed after your pin. For a model that declares a base_model, weights says what its tensors changed against that base, compared by sha256 fingerprint of every tensor (for example, ISxOdin/vit-base-oxford-iiit-pets matches google/vit-base-patch16-224 except its 2 classifier tensors); a hash is equal or not, so this says which tensors an edit touched and never what it does to behaviour. It reads public files from the change record; a change record says what a revision does mechanically, not that anything broke, and an untracked model has no record rather than no changes.

check_pins { paths: ["."] }
-> 4 downloads not pinned to a commit in 3 files
   train.py:2  AutoModel.from_pretrained("Qwen/Qwen3-8B") has no revision: it loads whatever main is when the job runs
   fix: Pin a full 40-character commit: revision="<sha>", from https://huggingface.co/Qwen/Qwen3-8B/commits/main (`neurarch pin-check --resolve` looks it up).
model_changes { hf_id: "Qwen/Qwen3-8B" }
-> 1 recorded change, 0 breaking; main is b968826d9c46 (2025-07-26)

The plan card, and the memory behind it

These two are the only two tools in this package that reach the network. plan is the artifact: the same card the Neurarch CI bot posts on a pull request and the neurarch-trace CLI prints, so the agent and the reviewer read the same words about the same graph.

Why these exist: a frontier model reading your code can reason about the architecture, and cannot know that this shape trained here three days ago and reached 98.65% in 34 seconds for under a cent. That fact is not in the weights, not in the repository, and not derivable from the graph.

Without NEURARCH_API_KEY, history makes no request and says so. It does not return an empty list: an unread ledger and an empty one are different answers, and only one of them means nobody has trained this. Keys come from neurarch.com/developer.

Then whether it forward-passes: the offline ladder

Across three datasets we found agents rarely write a structurally illegal model, and the one failure a structure-focused agent hit in our experiment was an out-of-memory, which is why sizing comes first. When the structure is in question, these grade it, and they are a ladder worth climbing in order. Each is free, offline and instant; check_design runs five pipeline stages, so an agent that starts at the top still pays for an answer two thirds of which a cheaper tool had.

| 5 | suggest_fix | The finding as a change to the file. A unified diff per finding: exact where the rule pins a number or an order (the head-dim crash above becomes a 7-line diff that changes every 258 to 256), proposal where a layer is missing. Apply, then lint again. |

Inspect

Reference library and other models

Write (opt in with --write)

add_layer, modify_layer, add_connection, delete_layer, delete_connection, save_model. Mutations always target the file passed on the command line; write tools refuse model_path, so an agent cannot edit, and then save over, a path it invented. Refused on a .py (the graph was derived from it; use export_pytorch to emit new source).

Every tool declares what it does to your files (MCP annotations): read tools are read-only and closed-world, load_hf_model is open-world, the three that can destroy something say so. Results carry structuredContent alongside the JSON text.

Prompts and resources

In Claude Desktop, Cursor and VS Code these show up as slash commands. Each is the tool ladder written out in order, with one rule on top: every number in the answer comes from a tool result, never from memory of similar models.

Resources a client can pin as context: neurarch://model (the graph), neurarch://model/mermaid, neurarch://model/pytorch, neurarch://zoo, neurarch://zoo/{id}, neurarch://rules (the provenance table), neurarch://docs and neurarch://docs/{tool} (every tool's full contract).

check_design can also ask the person when the verdict ends in a decision only they can make (which data, whether to spend the money): pass ask_user: true and, in a client that supports MCP elicitation, the question is put to them and their answer comes back with the verdict.

Whether an agent reaches for the right tool is measured, not assumed: npm run eval:tools runs six fixed asks through Claude Code against the built server and grades the tool calls (lint before proposing an edit, rank_designs for a which-of-k question). The latest result is in docs/tool-selection-eval.json.

Also a CLI

npx -y neurarch-mcp lint model.py                 # findings, exit 1 on a block
npx -y neurarch-mcp lint a.py b.py --json         # for CI
npx -y neurarch-mcp check model.py                # the full verdict
npx -y neurarch-mcp check zoo:qwen2.5-7b          # on a reference architecture

The same estimate in a shell: npx neurarch

The neurarch CLI runs the estimate this server vendors on a Hugging Face id, with no agent in the loop.

Data the config cannot take. Both of these pass the architecture checks and crash on the first batch, after the GPU is reserved:

Past jobs, requested against needed, from a CSV of what your team already ran:

Real output, every string verbatim: rightsize from neurarch 0.1.1 on the examples/jobs.sample.csv it ships, with columns cut; the data-fit run cut to its data-fit block, long sentences wrapped and none reworded.

A Claude Code hook: refuse the launch that will not fit

neurarch-mcp hook is a PreToolUse hook for Claude Code. Before each Bash call it reads the pending command from stdin; when the command launches training (python train.py, accelerate launch, torchrun, deepspeed, sky launch) it sizes the job exactly as size_training_job does, and when the job will not fit the card it declares it exits 2, which blocks the call and hands the agent the reason: the peak, the card, the largest batch that fits it, and the smallest card that holds the job. Every other command runs untouched, and the hook prints nothing.

Add it to .claude/settings.json in the repository (or ~/.claude/settings.json):

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "npx -y neurarch-mcp hook --hf" }
        ]
      }
    ]
  }
}

--hf lets it read config.json from huggingface.co for a model named as org/name (cached for a day); drop it to stay offline, and then only local models (a .py, a .neurarch.json, a checkpoint directory with a config.json, zoo:<id>, or an hf: id already in the cache) are sized. For a hook that runs on every Bash call, npm i -g neurarch-mcp and "command": "neurarch-mcp hook --hf" skip npx's startup.

The model, batch, sequence length and card come from the command line (--model / --model_name_or_path, --batch_size / --per_device_train_batch_size times --nproc_per_node / --num_processes, --gradient_accumulation_steps, --max_seq_length / --seq_len, --gpu, sky launch --gpus A100-80GB:8, --attn_implementation), and anything the command leaves out from the job: block in the nearest .neurarch.yml.

That block is the one neurarch-bot reads for the memory line on its pull request comment, with the same semantics, so one file drives both: the agent is refused before the launch for the same reason the pull request would turn red. A top-level job: applies to every model and a model entry's own job: merges over it key by key. The keys are gpu, batch (the per-step batch the memory is sized at), seq_len, grad_accum (only sets the effective batch the reason quotes), attention, epochs and samples; each is a value or a file:key pointer into your own YAML or JSON training config, read relative to the repository root, dotted keys allowed. Unknown keys are ignored. One key is the hook's own: model, because the bot takes the model from its traced file list and the hook has no trace to read it from.

job:
  model: meta-llama/Llama-3.2-1B               # hook only: a path, zoo:<id>, hf:<org/name> or org/name
  gpu: A10G                                    # T4, L4, A10G, L40S, A100 40GB, A100 80GB, H100, 8xH100
  batch: configs/pretrain.yaml:batch_size      # a number, or file:key into your training config
  seq_len: configs/pretrain.yaml:seq_len
  grad_accum: configs/pretrain.yaml:grad_accum
  attention: sdpa                              # sdpa (default), flash or eager

A per-model job: applies when its entry's path (or its own model) names the model being launched, or when it is the only entry with one. The command line wins over the block, key by key. A pointer that does not resolve leaves its key unset rather than guessed.

It fails open. A command it does not recognise, a job with no declared card or batch (including a file:key pointer that does not resolve), a model it cannot load, a card it cannot parse (a bare A100 is ambiguous), or any error at all lets the call run. So does a job the estimate does not model: --gradient_checkpointing, LoRA or PEFT flags, 4- or 8-bit loading and CPU offload, since the number is a full fine-tune's peak. The estimate is a fit check, not a measurement, so NEURARCH_ALLOW_OOM=1 in front of a command lets a refused launch through.

The same hook pre-checks a vLLM or SGLang launch (vllm serve, python -m vllm.entrypoints..., python -m sglang.launch_server) with check_serving_config, and blocks only on a finding read from the model's own config.json and the flags, such as a TP that does not divide the heads or a served length past the context; NEURARCH_ALLOW_SERVE=1 lets it through:

$ vllm serve Qwen/Qwen3-8B --tensor-parallel-size 3
neurarch: this vLLM launch has 2 blocking findings for Qwen/Qwen3-8B.
  TP 3 does not divide 32 attention heads.

Claude Code plugin

The server, the hook above and the skill install together as one Claude Code plugin. This repository is its marketplace:

/plugin marketplace add neurarch-ai/neurarch-mcp
/plugin install neurarch@neurarch-ai

On Claude Code 2.1.275 or later, /plugin install neurarch --marketplace neurarch-ai/neurarch-mcp does both in one step. From a shell, the same two steps are claude plugin marketplace add neurarch-ai/neurarch-mcp and claude plugin install neurarch@neurarch-ai.

What it adds, all from .claude-plugin/plugin.json and hooks/hooks.json:

• The MCP server, as npx -y neurarch-mcp --hosted --hf: no model of its own, so every tool takes model_path (a .py, a .neurarch.json, zoo:<id> or hf:<org/name>) or hf_id. --hf lets an hf: model read config.json from huggingface.co.
• The hook, npx -y neurarch-mcp hook --hf before every Bash call, exactly as configured by hand above: training launches are sized, vLLM and SGLang launches are pre-checked.
• The skill, /neurarch:neurarch-skill: size the job before it launches, then the evidence-gated edit loop.

Both commands contact huggingface.co only for a model named by its Hugging Face id. To stay offline, or to point the server at one model, configure the server and the hook by hand as above instead of installing the plugin.

Client setup

Documentation truncated — see the full README on GitHub.