hydroemu-mcp-server

An MCP server that exposes HACC cosmological hydrodynamic simulation emulators as tools for any LLM agent.

Powered by the cosmohydro_emu package — pre-trained SEPIA Gaussian Process models for 14 summary statistics from the CRK-HACC CosmoHydro simulation suite.

The one idea this repo teaches

The science code stays in usual Python. The MCP wrapper only publishes it.

• tools/ is an ordinary science package. It never imports MCP. The emulator tools live in tools/hydro_tools.py; the emulator backend is provided by the cosmohydro_emu package (lazily imported inside each tool function).

• mcp_server/ is a ~70-line generic wrapper. It reads one line of config from pyproject.toml, imports the science package, and registers every function listed in its __all__ as an MCP tool.

[tool.mcp-server]
tool_modules = ["tools"]

Your type hints, Pydantic Field constraints, and docstrings become the tool schema agents see. To build your own server: drop your modules into tools/ (or point that one config line at your own package), list the public functions in __all__, done.

Related MCP server: MCP Refana Server

Layout

tools/
  hydro_tools.py                 The 5 MCP tool functions + ArtifactResult contract
  __init__.py                    __all__ — ONLY these names become tools
mcp_server/                      Generic drop-in wrapper (FastMCP)
tests/test_tools.py              Tools tested as plain Python, no MCP needed
docs/mcp-clients.md              Multi-client setup guide

Parameters

Most statistics use 7 parameters (5 subgrid + 2 cosmology). Gravity-only statistics (Pk_GO) use only the 2 cosmology parameters.

Design: 110 simulations (400 Mpc/h boxes) from a Latin hypercube design.

Observables

Tools

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

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest                        # tests pass — fixture data for plots, real models for predictions

The cosmohydro_emu package (and its SEPIA GP backend) is installed automatically as a dependency. All trained models are shipped inside cosmohydro_emu — no manual model copying needed.

Related: cosmohydro_emu Python package

The standalone cosmohydro_emu package provides the same SEPIA emulators as a pip-installable Python library (with additional statistics: Pk suppression, CSFR, and gravity-only Pk). This MCP server wraps the same underlying models for agent access.

Run the server

Streamable HTTP — the server is a visible process with a URL:

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

Clients connect to http://127.0.0.1:8000/mcp. Stop the server with Ctrl+C (Ctrl+Z only suspends it, leaving the port taken — if that happens, just start the server again: it detects a leftover mcp_server holding the port and clears it automatically).

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.

Architecture

This server follows the same architecture as spectra-mcp-server:

• mcp_server/ is a generic drop-in MCP wrapper (copy between repos)

• tools/ contains the domain-specific science functions

• pyproject.toml [tool.mcp-server] config wires them together

• All cosmohydro_emu imports are lazy (inside functions, not at module scope)

• Emulators are loaded on first use per tool call

Emulator Package

The emulator backend is cosmohydro_emu, which ships:

• Pre-trained SEPIA GP models for all 14 statistics

• Training data arrays (parameter designs, x-grids, redshifts)

• Metadata registry (plot info, parameter ranges, output transforms)

• Redshift interpolation between trained snapshot models

See the cosmohydro_emu documentation for the full Python API.