Summary and Setup

In most analyses the bottleneck is not the physics but the software around it: finding data, decoding a data model, getting branch names and units right, iterating on fitting and plotting code. This lesson shows how to hand that overhead to an AI assistant without giving up rigor: every step produces a number you can check, and the whole procedure is reproducible.

The worked example is a real measurement from the ePIC experiment: reconstructing the weak decay Λ⁰ → p π⁻ and extracting its yield from the proton–pion invariant-mass spectrum.

The lesson develops three ideas and applies them end to end:

  • an agentic assistant: a language model placed in a loop where it can read files, run code, and react to the results, rather than only returning text;
  • the Model Context Protocol (MCP): an open standard for offering analysis tools to any assistant, so the workflow is portable; and
  • persistent instructions (AGENTS.md and SKILL.md): versioned context and procedures that make a run repeatable and auditable.

The lesson uses opencode, but the parts you build (MCP tool servers, a skill) work with any assistant.

Prerequisite

Prerequisites

  • Comfort at the command line (running commands, editing files).
  • Working knowledge of Python or ROOT is useful; the assistant writes most of the code.
  • Introductory particle-physics concepts (four-momentum, invariant mass, histograms, fitting).
  • No prior experience with AI tooling is assumed, and the core episodes need no paid account or GPU.

See the Setup page for installation.

This lesson originated at an ePIC workshop on generative AI for physics. It complements the other EIC tutorials, which cover locating and reading the data.

eic-shell contains everything this lesson needs: the three MCP servers (uproot, xrootd, rucio), the eic-mcp command that starts them, and the opencode assistant. You need no grid certificate and download no data: rucio is already signed in to the shared read-only eicread account.

Checklist

Quick checklist

1. eic-shell

See the environment setup guide if you do not have eic-shell yet. Then, in the folder with ./eic-shell:

BASH 

cd ~/eic                  # yours may differ
./eic-shell --upgrade

2. Start the servers and the assistant

BASH 

./eic-shell
mkdir -p lambda && cd lambda     # a working directory for the analysis
eic-mcp up                       # uproot, xrootd, rucio on 127.0.0.1:9101-9103
eic-mcp config opencode          # writes opencode.jsonc here
opencode

In opencode, /mcp should list uproot, xrootd, and rucio as connected. The free hosted models need no login. The servers stop when you leave eic-shell: keep that shell open.

On macOS the container’s home (/root) is wiped on exit: keep your work in the eic-shell folder.

Callout

Check it works

Ask: “Create hello.py that prints the PDG Λ⁰ baryon mass in GeV, then run it.” The assistant should write the file and run it, printing 1.115683. If it only shows the code, switch it to agent (build) mode.

Then ask: “Use the xrootd tools to list /eic/EPIC/RECO.” The answer should be a list of campaign versions (26.04.1, …). This checks the servers and the data store.

Other assistants

gold ring engraved with the words EIC

One assistant to rule them all? Any agentic assistant — one that can read/write your files and run commands, not just emit text — works, and MCP works with any.

Tool Interface Free access
opencode terminal free hosted models, an API key, or a local model
GitHub Copilot VS Code, CLI free tier; free Pro for students and educators
Antigravity terminal (agy), IDE free preview; replaces Gemini CLI
Codex terminal, IDE paid ChatGPT plans
Claude Code terminal, IDE Claude plans
Cursor dedicated editor free tier
Cline VS Code extensions needs an API key

eic-shell also has claude and copilot: run eic-mcp config claude (or copilot), then start it.

Callout

Assistant outside eic-shell

The servers must run in eic-shell, but the client can run on your machine, started in the directory that holds its config file.

  • Linux, WSL: apptainer shares the host network and your home directory. Run eic-mcp config <client> inside eic-shell, in the directory where you will start the client.

  • macOS: start eic-shell with the server ports published, run eic-mcp up in it, and download the client config on the Mac (eic-mcp does not run on the Mac itself):

    BASH 

    DOCKER_OPTIONS="$(./eic-shell -- eic-mcp docker-args)" ./eic-shell

    BASH 

             # on Mac: the directory where you will launch opencode
curl -fsSLO https://raw.githubusercontent.com/eic/tutorial-mcp/main/files/mcp-config/opencode.jsonc