MCP server for agents

vaft.mcp lets an MCP client (Claude Code, Codex or any other) ask VAFT what it can do and read small numerical views of the packaged reference data. You bring the agent; VAFT runs locally, in your own environment, over the stdio transport.

The server is an adapter, not a second API. Each tool calls an existing VAFT function, such as vaft.help(), the formula and process catalogs, the validation registry, vaft.plot.available_plots, vaft.plot.dd, vaft.plot.extract or vaft.data.sample_manifest, and returns the answer as bounded JSON.

Install and register

pip install 'vaft[mcp]'
claude mcp add vaft -- python -m vaft.mcp     # Claude Code; `vaft mcp` is the same server

Any client that launches a stdio server can run python -m vaft.mcp the same way. Use the Python interpreter of the environment where VAFT is installed. import vaft never needs the extra: only vaft.mcp.server.build_server() imports the MCP SDK.

Do not start the server with the vaft/ package directory as the working directory. Python puts the working directory first on sys.path, so vaft/mcp/ would shadow the SDK’s own mcp package. The repository root or any other directory is fine.

Tools

extract_plot_data returns the plot’s view model, with labels and units as VAFT stores them. Each array comes back as its shape, dtype, and finite minimum and maximum over all values, plus a strided preview. The preview is array[::stride], a transport bound, not a resampling. max_points is a budget for the whole result, shared across its arrays, so a panel overview with hundreds of arrays gets a few points per array. A result that would exceed about 50 kB keeps array statistics only. options takes VAFT’s extraction options only; the tool description lists the allowed keys.

Every result carries truncated: the count of places something was shortened (a list cut to limit, a long string, an array preview) and the first 20 of those paths. Shot 39915 ships in the wheel; the other samples load from a Git checkout.

Tools run one at a time in a worker thread, so a slow extraction does not stall the protocol. The server keeps the JSON-RPC stream on a private copy of standard output and points file descriptor 1 at stderr, so output printed by Python, C or Fortran code VAFT calls cannot corrupt the stream.

Read-only by construction

Every tool is annotated readOnlyHint. None of them writes a file, publishes to the database, reaches HSDS or the network, runs EFIT, CHEASE or any other solver or pipeline, or executes caller-supplied code or shell commands. Results never carry credentials: help pages say whether HSDS is configured, not with what, and the server also scrubs the values of HS_PASSWORD and HS_API_KEY and replaces the home directory with ~ in every result and error message. Tool inputs name scientific things: a plot, a formula or a shot. They never name a data representation. During the DD migration (#1127, #1132, #1135), the loading code can change behind the same tool schema.

Datasets

A dataset is named by shot or by artifact, never by a storage format:

Every result carries the dataset’s provenance: its kind, the shot or the artifact path relative to its directory, the loader, the Data Dictionary version when the data records one, and the VAFT version. Database failures report the exception class only, never the server’s text.

Slices are matched by time, never by index. get_equilibrium_summary(time=...) and inspect_data_path("equilibrium.time_slice.*.global_quantities.q_95", time=...) take the slice nearest that time. They refuse when it is further away than tolerance (default: half the slice spacing), and they report the time they matched.

Atlas tables

The campaign atlas is the directory the lanes write their tables to (~/runs/campaign/atlas on vestserver). Point VAFT_ATLAS_DIR at it. The server knows each table by name, together with the lane that owns it, the schema that describes its columns, and the rules for reading it:

describe_atlas_table returns each column’s unit and definition from the lane’s own schema, the row key, the lane’s rules and caveats, its README, and provenance: the file’s sha256 and the build commit. Read it before comparing rows.

query_atlas_table filters with where clauses ({"column", "op", "value"}; ==, !=, <, <=, >, >=, in, not_in, isnull, notnull), selects columns, sorts with order_by ("-name" for descending) and counts rows per value with count_by. It does not join tables and does not aggregate beyond counting. A lane’s “never combine” rules are refusals:

• stability needs n_tor ==.
• stability_surfaces needs n_tor == and solver ==.
• transport_sensitivity needs tglf_config ==.

Older spellings (efit_label, magnetics-only, electron-kinetic) are accepted and returned in State key contract v1 spelling (efit_quality, magnetics, electron_kinetic). Tables are read-only, limited to 50 MB, and every result stays under about 50 kB.

Environment

claude mcp add vaft \
  -e VAFT_ATLAS_DIR=$HOME/runs/campaign/atlas \
  -e VAFT_ARTIFACT_DIR=$HOME/runs/artifacts \
  -- python -m vaft.mcp

A client configured by file (Claude Desktop, a project .mcp.json) takes the same command:

{
  "mcpServers": {
    "vaft": {
      "command": "/path/to/env/bin/python",
      "args": ["-m", "vaft.mcp"],
      "env": {"VAFT_ATLAS_DIR": "/path/to/campaign/atlas"}
    }
  }
}

Demo scenarios

workflow/mcp_demo/run_demo.py replays four questions through a real stdio session and writes the transcripts. The questions are the equilibrium summary of shot 39915, the Tier A states ideal-unstable at n = 1, the surfaces with the largest SAT-rule flux spread, and the identified resistive Z_eff windows. Its README lists the same questions to ask an agent live.