| name | neuralfn-mcp |
| description | Build, edit, train, and inspect NeuralFn neural-network graphs using the neuralfn MCP server tools. Use whenever the user asks to create a neural network, build a model (GPT, MoE, Llama, NanoGPT, etc.), train on a dataset, add or wire neurons, execute a graph, manage datasets, or do anything with NeuralFn. The MCP server name is "neuralfn". |
NeuralFn MCP Server
IMPORTANT: Do NOT read or edit the NeuralFn source code to perform graph operations. Use the neuralfn MCP tools directly. Every operation the visual editor supports is available as an MCP tool. The only time you should look at source code is if the user explicitly asks about the implementation itself.
All tool responses are compact summaries safe for LLM context. No tool returns oversized graph blobs.
The backend must be running: uvicorn server.app:app --reload --port 8000
For complete MCP tool reference, see docs/mcp/. For the Python SDK, see the neuralfn-python-sdk and neuralfn-torch skills.
Full API documentation lives in the repo at docs/ (index). For a single-file LLM-ready dump of all docs, see llms-full.txt.
Architecture quick reference
- Nodes have a
neuron_def (kind: function, subgraph, or module) with typed I/O ports.
- Edges connect
src_node:src_port to dst_node:dst_port with weight and bias.
- Graph I/O: designate nodes as graph inputs/outputs via
set_io.
- Variant library: reusable subgraph templates keyed by
family/version.
- GPT templates:
load_gpt_template builds AND loads a full model graph in one call.
- Common builtin IDs:
builtin-input, builtin-output, builtin-sigmoid, builtin-relu, builtin-tanh, builtin-add, builtin-multiply, builtin-identity, builtin-gelu, builtin-silu.
End-to-end workflow: train a model on a dataset
When the user asks to "train a [model] on [dataset]", follow these steps using MCP tools only:
Step 1 -- Build and load the model graph (one call)
load_gpt_template(name="my_model", preset="llama", config={
"n_layer": 4,
"n_head": 4,
"n_embd": 128,
"num_kv_heads": 2
})
Step 2 -- Download and wire the dataset (one call)
load_dataset_source(
hf_path="HuggingFaceFW/fineweb",
hf_split="train",
max_rows=10000,
seq_len=64
)
This downloads the dataset AND wires it into the graph's dataset_source node.
Step 3 -- Start training
train_start(method="torch", epochs=10, learning_rate=0.001)
Step 4 -- Monitor progress
poll_training_status(since_event_id=0, timeout_seconds=30)
Or check current state:
get_training_status()
That's it -- four tool calls for a complete train run.
Tool reference
Graph
| Tool | Purpose |
|---|
get_graph() | Compact summary: node IDs with name/kind, edges, settings, variant families. |
replace_graph(graph) | Replace the entire graph. Returns compact summary. |
update_graph_settings(name, training_method, runtime, ...) | Patch settings. Returns updated settings only. |
set_io(input_ids, output_ids) | Set graph input/output nodes. |
Nodes
| Tool | Purpose |
|---|
list_builtins() | List builtin neuron IDs and names (compact). |
add_node(neuron_id, instance_id, position) | Add a builtin node. Returns brief confirmation. |
add_custom_node(name, source_code, input_ports, output_ports, ...) | Add a custom function node. Ports: [{"name": "x", "range": [-10, 10]}]. |
add_subgraph_node(name, ...) | Add an empty subgraph with internal in/out nodes. |
add_variant_node(family, version, ...) | Add a node linked to a variant. |
get_node(node_id) | Inspect one node (ports, source truncated, subgraph summarized). |
update_node(node_id, name, source_code, input_ports, output_ports, module_config, ...) | Patch a node's definition. |
delete_node(node_id) | Remove a node. |
update_node_positions(positions) | Batch-move: {"id": [x, y], ...}. |
Edges
| Tool | Purpose |
|---|
add_edge(src_node, src_port, dst_node, dst_port, weight, bias) | Connect two ports. |
update_edge(edge_id, weight, bias) | Change weight/bias. |
delete_edge(edge_id) | Remove an edge. |
Variants
| Tool | Purpose |
|---|
list_variants() | List families and versions. |
save_node_as_variant(node_id, family, version, link_node) | Save a subgraph to the library. |
swap_node_variant(node_id, family, version) | Swap to a different variant version. |
Templates, execution, and training
| Tool | Purpose |
|---|
load_gpt_template(name, preset, config) | Build and load a GPT/Llama/MoE graph in one call. |
execute_graph(inputs) | Run with scalar inputs: {"node_id": [values]}. |
execute_trace(inputs) | Run and trace intermediates. |
trace_torch(inputs) | Torch tensor statistics. |
probe_node(node_id, n_samples) | Sample a node's response curve. |
train_start(method, epochs, learning_rate, train_inputs, train_targets, dataset_names) | Start training. Methods: surrogate, evolutionary, hybrid, torch. |
get_training_status() | Read the active training snapshot, latest loss, and recent events. |
poll_training_status(since_event_id, timeout_seconds, interval_seconds) | Wait for the next training update or until the run finishes. |
train_stop() | Stop training. |
Datasets
| Tool | Purpose |
|---|
list_datasets() | List datasets visible to the project. |
download_dataset(hf_path, hf_split, max_rows, ...) | Download from HuggingFace into project catalog. |
load_dataset_source(hf_path, dataset_names, seq_len, ...) | Download/load datasets AND wire into graph's dataset_source node. |
set_dataset_access(ds_name, project_ids) | Update which projects can use a dataset. |
delete_dataset(ds_name) | Delete a local dataset. |
Shipped GPT template presets
| Preset | Architecture | Objective |
|---|
nanogpt | GPT-2 style (LayerNorm, GELU, absolute pos) | AR |
gpt2 | GPT-2 (with bias) | AR |
llama | LLaMA (RMSNorm, SwiGLU, RoPE, GQA) | AR |
moe / mixllama | LLaMA + Mixture of Experts | AR |
llama_fast | LLaMA with torch.compile | AR |
mixllama_fast | MoE with torch.compile | AR |
jamba | Attention + Mamba hybrid, MoE | AR |
ternary_b158 | BitNet b1.58 ternary weights | AR |
seq2seq | Encoder-decoder, MoE | Seq2Seq |
diffusion | Discrete diffusion with denoising head | Diffusion |
ttt_llama | Test-Time Training layers | AR |
llm_jepa | JEPA with EMA target encoder | JEPA |
dense_jepa_evo | Non-semantic AR+JEPA Evo control with dense FFNs | AR+JEPA |
moe_jepa_evo | Non-semantic AR+JEPA Evo control with standard MoE routing | AR+JEPA |
semantic_router_moe | AR-only semantic router control with shared routed MoE blocks | AR |
semantic_dense_jepa_evo | Dense Semantic JEPA Evo control with chunk planner and no expert routing | Semantic JEPA |
semantic_moe_jepa_evo | Chunk-level Semantic MoE JEPA Evo with route evolution | Semantic MoE JEPA |
hnet_lm | Raw-byte input, byte patches | AR |
universal_llama | ACT-based universal transformer | AR |
llama_megakernel | Fused attention, max-autotune compile | AR |
kv_pca_llama | PCA-compressed KV cache | AR |
deepseek_v3 | MLA + auxfree-balanced MoE + shared experts | AR (MoE) |
deepseek_v4 | NSA + auxfree MoE + mHC residuals + QK-norm + FP8 | AR (MoE) |
gemma3 | Sliding-window attention + GeGLU + QK-norm + softcap | AR |
diff_transformer | Differential (two-softmax) attention + head-wise norm | AR |
qwen3_longctx | GQA + YaRN RoPE scaling + QK-norm | AR |
longctx_sparse_llama | Native-sparse / block-sparse / sliding-window / streaming | AR |
modern_norms_llama | DyT + QK-norm + GeGLU | AR |
fp8_llama / mxfp4_llama | FP8 E4M3 / MXFP4 weight linears (Blackwell) | AR |
auxfree_moe_jepa_evo | Auxfree balancing × route-evo × JEPA | Semantic MoE JEPA |
diff_semantic_moe_jepa_evo | Differential attention × semantic MoE JEPA evo | Semantic MoE JEPA |
dyt_geglu_semantic_dense_jepa_evo | DyT + GeGLU × semantic dense JEPA evo | Semantic JEPA |
<preset>_modern | Any base preset + modern recipe (RMSNorm/QK-norm/RoPE-YaRN/GeGLU/auxfree) | (inherits base) |
GPT template config keys
| Key | Default | Description |
|---|
n_layer | 4 | Number of transformer layers |
n_head | 4 | Attention heads |
n_embd | 128 | Embedding dimension |
vocab_size | 256 | Vocabulary size (auto-adjusted by trainer) |
num_kv_heads | 2 | GQA key/value heads |
mlp_multiplier | varies | MLP hidden dimension multiplier |
multiple_of | 256 | Round MLP width to this multiple |
experts | 8 | MoE: number of experts |
top_k | 2 | MoE: active experts per token |
router_aux_loss_coef | 0.01 | MoE load-balance loss coefficient |
semantic_vocab_ref | default vocab | Semantic vocabulary file for semantic routing presets |
route_chunk_size | 32 | Chunk interval for semantic_dense_jepa_evo planner updates and semantic_moe_jepa_evo route updates |
semantic_shared_experts | 2 | Always-on shared experts for semantic_moe_jepa_evo |
semantic_free_experts | 8 | Free learned experts for semantic_moe_jepa_evo |
route_evo_enabled | true | Enable periodic route evolution for semantic_moe_jepa_evo |
route_evo_fraction | 0.10 | Fraction of optimizer steps that run route evolution |
route_evo_population | 8 | Route-evolution candidate count |
route_evo_mutation_scale | 0.05 | Mutation scale for route-evolution candidates |
dropout_p | 0.0 | Dropout rate |
tie_embeddings | varies | Tie embedding and LM head weights |
logit_softcap | 0.0 | Tanh softcap value (>0 enables) |
ttt_hidden_dim | 32 | TTT hidden dimension |
byte_patch_size | 4 | H-Net byte patch size |
byte_patch_stride | 4 | H-Net byte patch stride |
max_recurrence_steps | 4 | Universal TX max steps |
halt_epsilon | 0.01 | Universal TX halt threshold |
Other common workflows
Build a scalar graph
1. add_node(neuron_id="builtin-input", instance_id="in", position=[100, 200])
2. add_node(neuron_id="builtin-sigmoid", instance_id="sig", position=[350, 200])
3. add_node(neuron_id="builtin-output", instance_id="out", position=[600, 200])
4. add_edge(src_node="in", src_port=0, dst_node="sig", dst_port=0)
5. add_edge(src_node="sig", src_port=0, dst_node="out", dst_port=0)
6. set_io(input_ids=["in"], output_ids=["out"])
7. execute_graph(inputs={"in": [0.5]})
Train on inline data (XOR example)
train_start(
method="surrogate",
epochs=200,
learning_rate=0.01,
train_inputs=[[0,0],[0,1],[1,0],[1,1]],
train_targets=[[0],[1],[1],[0]]
)
Non-AR template workflows
Seq2Seq:
load_gpt_template(name="s2s", preset="seq2seq", config={"n_layer": 4, "n_embd": 128, "experts": 4})
Dataset roles: enc_tokens, dec_tokens, targets.
Diffusion:
load_gpt_template(name="diff", preset="diffusion", config={"n_layer": 4, "n_embd": 128})
Dataset role: tokens only.
JEPA:
load_gpt_template(name="jepa", preset="llm_jepa", config={"n_layer": 4, "n_embd": 128})
Dataset role: tokens only. Uses EMA target encoder, supports jepa_mask_strategy ("random" or "block").
H-Net (byte-level):
load_gpt_template(name="hnet", preset="hnet_lm", config={"n_layer": 4, "n_embd": 128})
Uses raw bytes (vocab_size=256), byte patch embedding.
Experimental Tools
The following MCP tools are [Experimental] and target the jepa_semantic_hybrid semantic stack. They may change or be removed.
| Tool | Parameters [Experimental] | Purpose |
|---|
reverse_engineer_to_semantic | project_id, session_id, text | Encode text to the vocab-grounded 9-D semantic space used by the session graph’s JEPA semantic path. |
semantic_search | project_id, session_id, vector (list of floats), k (default 10) | k-nearest-neighbour lookup for a 9-D semantic vector. |
train_jepa_semantic | project_id, session_id, dataset_names (optional list), epochs (default 10), learning_rate (default 3e-4) | Start torch training (same entry as train_start) intended for graphs using the [Experimental] jepa_semantic_hybrid template. |
generate_with_semantics | project_id, session_id, prompt, target_vector (optional 9-D list), max_tokens (default 100) | Generate with the experimental semantic stack; optional target_vector steers toward a semantic target. |
Disclaimer [Experimental]: These tools are research prototypes; prefer the stable graph/dataset/training tools for production-like workflows.
