Skip to content

Chat assistants (MCP)

Lumped-element detectors, cavity haloscopes and SRF heterodyne detectors search for axion dark matter. In this guide we configure chat assistants to use axionMultiPhysics's server for the Model Context Protocol (MCP), an open standard through which chat assistants such as Claude Code and Claude Desktop call external tools. With it, an assistant can build, solve, plot and optimize lumped-element detector designs and work with the beta modules for cavity haloscopes, SRF heterodyne detectors and dc SQUID readout chains and with COMSOL files on the local machine through axionMultiPhysics; the results it reports are the solver's.

Installation

In the source checkout from the Installation page, install the MCP extra (after the MPI build; after the sequential build, AXIONMULTIPHYSICS_DEPS=$PWD/third_party/install-seq pip install ".[mesh,mcp]"):

pip install --no-build-isolation -e ".[mcp]"

Once the 0.2.0 wheels are on PyPI, the same extra is pip install "axionmultiphysics[mcp]". The server is the command axionmultiphysics-mcp in the environment's bin directory.

The server keeps designs (designs/<name>.json) and results (runs/<name>/) in the directory AXMP_WORKSPACE (default ./axmp_workspace). It inherits the environment of the client that starts it, so we set AXMP_WORKSPACE (and, if needed, AXMP_THREADS, AXMP_MESHER or LD_LIBRARY_PATH) in the client configuration.

Client configuration

Claude Code

We register the server with Claude Code to enable axionMultiPhysics tool calls.

claude mcp add axionmultiphysics -e AXMP_WORKSPACE=$HOME/axmp_workspace -- /path/to/axionMultiPhysics/.venv/bin/axionmultiphysics-mcp

Claude Desktop

We add the server to claude_desktop_config.json to enable axionMultiPhysics tool calls.

{
  "mcpServers": {
    "axionmultiphysics": {
      "command": "/path/to/axionMultiPhysics/.venv/bin/axionmultiphysics-mcp",
      "env": {"AXMP_WORKSPACE": "/path/to/axmp_workspace"}
    }
  }
}

Other MCP clients that start a local (stdio) server take the same command and environment. Some clients stop waiting for a tool after a fixed time; for long sweeps and optimizations, we raise the client's tool timeout if it has one.

The assistant should start with the axionmultiphysics_guide tool, which explains the workflow, units and conventions; most clients read it automatically when the server starts.

Example

User: “Build an ABRACADABRA-style toroid with R = H = 2 m and inner radius ratio y = 0.6, solve it, show me a section plot and tell me the pickup inductance and the signal coupling.”

The assistant calls create_design (template "toroid", R = 2, H = 2, y = 0.6), solve_design and render_design (section, Bmag).

Assistant: “The pickup inductance is L_p ≈ 1.458 µH and the signal coupling is Ψ ≈ 3.09 × 10⁻⁷ H T m² (0.246 T m³ in natural units). The static field stays inside the winding box and falls off as 1/r, from 0.167 T at the inner wall to 0.10 T at the outer wall, matching μ₀NI/(2π · 1.2 m). L_p computed from flux and from energy agrees to 5 × 10⁻¹³. To reach the optimistic benchmark the peak field would have to rise to about 7.4 T.”

A convergence check (order 3) should be requested and the warnings read before quoting a number.

Tools

Tool Purpose
axionmultiphysics_guide Workflow, units and physics conventions
list_templates, create_design, put_design, get_design, list_designs, design_schema Starting from a template or writing a design document
set_parameters Changing parameters of a saved design, or saving a variant under a new name
solve_design Meshing and solving: Ψ, L_p, F, fields, forces, benchmarks, cost metric
render_design, start_viewer PNG section or 3D cutaway; live browser viewer
requirement F_req for a noise benchmark
sweep Solving for several values of one parameter
sensitivities, list_objectives Shape derivatives of the figures of merit
optimize_design, optimize_global, optimize Gradient-based (adjoint), global (differential evolution) or derivative-free (bounded Powell) optimization
set_fullwave, set_hts, make_3d, list_conductors Full-wave sweep, HTS screening currents, 3D designs, conductor critical surfaces
list_jobs, cancel_job Following or stopping long jobs

Other detector types

These tools wrap the same Python functions as the walkthroughs for cavity haloscopes, SRF heterodyne detectors, dc SQUID readout chains and COMSOL export and import. The cavity, SRF and SQUID modules, and the COMSOL importer, are beta.

Tool Purpose
cavity_presets, cavity_preset_limit Published cavity haloscope runs and the exclusion recomputed from their numbers
cavity_scan Scan rate, optimal coupling, excluded coupling and time to cover a band for one cavity mode
create_cavity Pillbox or coaxial cavity design; solve_design then returns its modes, form factors and Q
srf_design, srf_mode_pair Volume, frequency, RF power and cost metric of an SRF heterodyne detector (geometry: projectx, the computed default cell, or equator_diagnostic); figures of merit of a mode pair
squid_chain, squid_reach Added noise of a dc SQUID readout chain; reach of a solved design read out by it
export_comsol, inspect_comsol, import_comsol Writing a design for COMSOL; summarising or importing a .mph file
export_touchstone A solved design's full-wave S-, Z- or Y-parameters as a Touchstone v1 file, with passivity and reciprocity checks

Asked for the scan rate of a cavity at 5.75 GHz with B = 9 T, V = 1.5 L, C = 0.5, Q0 = 30 000, a quantum-limited amplifier and the cavity at 50 mK, the assistant called cavity_scan and reported 4.6 Hz/s at the KSVZ coupling, with β = 2, and 125 days to cover 5.75–5.80 GHz.