lattice-mcp-server

An MCP server that exposes science tools — the thermodynamics of hot, strongly interacting matter from lattice QCD — to any LLM agent. Built on the same pattern as spectra-mcp-server and gaia-mcp-server; the multi-agent client in multiagent-client-demo drives any of these servers unchanged.

The science

Heat nuclear matter past about 156 MeV (~2 × 10¹² K) and hadrons dissolve into a quark–gluon plasma. This is not speculation: it is a first-principles result of lattice QCD, it is recreated on Earth in heavy-ion collisions at RHIC and the LHC, and the universe itself cooled through this transition about 10 μs after the Big Bang. The tools here compute the two descriptions that meet at the crossover:

• the equation of state of QCD matter — the published parameterization of continuum-extrapolated (2+1)-flavor lattice results (Bazavov et al., HotQCD collaboration, PRD 90, 094503 (2014)),
• the hadron resonance gas (HRG) — a non-interacting gas of ~1200 hadrons and resonances (QMHRG2020 list), the confined-phase description that must fail once quarks are liberated.

Where the dashed HRG curves peel away from the lattice curves is deconfinement:

Everything is computed with the LatticeQCD AnalysisToolbox (pip install latqcdtools), the HotQCD collaboration's public analysis package. The hadron list bundled in data/ comes from that repository (MIT license).

Tools

tool	what it does
describe_qcd_thermodynamics()	physics context, validity ranges, references — call it first
compute_qcd_eos(output_dir, ...)	lattice EoS: p/T⁴, ε/T⁴, s/T³, trace anomaly, c_s² on a T grid → CSV
compute_hrg_thermodynamics(output_dir, ...)	the same columns from the hadron resonance gas → CSV
plot_eos(eos_file, output_dir, hrg_file=None)	the classic ε/T⁴, 3p/T⁴, (3/4)s/T³ figure, crossover band, ideal-gas limit, optional HRG overlay
plot_speed_of_sound(eos_file, output_dir, ...)	c_s²(T) with the softest point + trace anomaly panels
compute_charge_cumulants(output_dir, ...)	HRG baryon-number susceptibilities χ₂ᴮ, χ₄ᴮ (heavy-ion fluctuation observables) → CSV
plot_charge_cumulants(cumulants_file, output_dir)	χₙᴮ(T) and the kurtosis ratio χ₄ᴮ/χ₂ᴮ against the hadron-gas expectation
compute_running_coupling(output_dir, ...)	2-loop α_s(μ): asymptotic freedom → CSV + PNG

Two conventions worth copying into any science MCP server:

1. Every tool returns {status, files, message, metadata} (ArtifactResult).
2. Arrays move between tools as file paths, never through the agent's context window.

Install

conda create -n lattice-tutorial python=3.12 -y
conda activate lattice-tutorial
pip install -e ".[dev]"
pytest

Already have the spectra-tutorial env from the other servers? You can reuse it: pip install latqcdtools, then always launch this server (and pytest) from this repo's root directory — all tutorial servers export packages named tools and mcp_server, so don't pip install -e several of them into one env; running from the repo root makes the local packages win.

Run the server

python -m mcp_server --transport streamable-http --port 8002

Clients connect to http://127.0.0.1:8002/mcp. Port 8002 by convention, so this server can run alongside spectra (8000), gaia (8001) and bbn (8003). Stop with Ctrl+C.

To use this server from Claude Code, the Claude desktop app, Codex, Cursor, or any other MCP client, see docs/mcp-clients.md — a checked-in .mcp.json already wires it into Claude Code.

A question to ask an agent

"At what temperature does hadronic matter melt? Compute the lattice QCD equation of state and the hadron resonance gas, overlay them, and tell me where and why they disagree."