Use the models

The same tools three ways: MCP, CLI and Python. The hosted MCP server needs no install, account or key.

Copy the server URL

https://policyengine--policyengine-macro-mcp-serve.modal.run/mcp

Add it to your client

Settings → Connectors → Add custom connector → paste the URL. Some plans gate this.

Claude Code

claude mcp add --transport http policyengine-macro https://policyengine--policyengine-macro-mcp-serve.modal.run/mcp

Ask a policy question

* BoE SVAR: no forecast skill against a drifting random walk

Click a prompt to copy it. Every tool →

Run the same server on your machine (stdio)

No request ceiling; local-only tools run where installed. After the CLI install:

claude mcp add policyengine-macro -- python -m policyengine_macro.mcp_server

What runs where

Every MCP tool, by model. The CLI and core expose the same adapters.

tool runs as a job when slow or coldtool runs only on your machine

MCP tools by model, split into hosted and local-only
ModelTools
PolicyEngine microsimulationpe-microsimcalculate_householdhousehold_reform_impactlist_reform_parameterspopulation_reform_impact
OBR emulatorobr-macroscore_reformobr_shocklist_reform_variables
BoE SVARboe-svarforecast_uklatest_shocksmodel_summarysvar_inflation_incidence
FRB/USfrb-usfrbus_shockfrbus_list_variablesfrbus_summaryfrbus_shock_incidence
US HANKus-hankhank_shockhank_summaryhank_shock_incidence
OG-UKpsl-og, og+microsimdynamic_reform_impactscore_reform model='og'
DEFINE-UKdefine-ukdefine_scenario_incidencedefine_list_scenariosdefine_scenario
Routing and reportslist_model_capabilitiesget_model_statusrecommend_modelformat_score_report
Jobsstart_jobget_job_result
Notes on incidence and local models
  • Incidence tools (*_incidence) are experimental: a macro path laid onto households, not a reform score. Hosted, each runs only as a job.
  • DEFINE-UK scenarios are never hosted (the upstream is unlicensed): hosted calls return run instructions, and the incidence tool runs hosted on a locally produced define_payload. pip install git+https://github.com/PolicyEngine/define-uk-model fetches the pinned upstream at runtime; scenario deltas come from a cached local run, and a fresh one needs local R.
  • OG-UK + microsimulation is experimental and UK only: an OG-UK steady-state solve feeds long-run wage changes back into a second microsimulation run. Until OG-UK#68 the solve needs its own environment: run pe-macro og-score --reform '{"gov.hmrc.income_tax.rates.uk[0].rate":0.21}' --json > og.json there, then pe-macro dynamic-score --reform '{"gov.hmrc.income_tax.rates.uk[0].rate":0.21}' --og-payload og.json; both steps need the same --reform.
  • Tool names are a fixed contract (tool_surface.py), so renaming one is a reviewed, breaking change.

Limits and cold starts

Free, with a spend cap.

Request ceiling150 s

Longer calls run as 30-minute jobs

Containers at once3

Scales to zero when idle

Warm after last request5 min

Cold start ~20 s; UK forecast takes minutes

Limits in detail
  • The hosting transport drops any request after 150 seconds. start_job hands a slow call to a worker with a 30-minute budget and returns a job id; poll get_job_result. score_reform and the four *_incidence tools always run as jobs hosted (each takes longer than the ceiling); obr_shock, frbus_shock, hank_shock and a population run (pe_population_impact) when cold. Locally, call the tool directly.
  • get_job_result blocks at most 60 seconds per call; keep polls short. A poll that errors is not a failed job: call again with the same id. Job names are the adapter names: score_reform, obr_shock, frbus_shock, hank_shock, pe_population_impact, dynamic_population_reform_impact, the four *_incidence tools under their own names, and svar_forecast for a forecast_uk with thousands of draws.
  • A container stays warm five minutes after the last request. In a fresh one the first PolicyEngine call pays a ~20 s import and the first UK forecast a couple of minutes of estimation.
  • Only a local UK population or reform score needs HUGGING_FACE_TOKEN (private policyengine-uk-data-private).
  • Local only: model='og', dynamic_reform_impact (tens of minutes; not formally timed) and the DEFINE-UK scenarios. Called hosted they return run instructions or an import error.
  • Every score_reform result carries a score block: model class, horizon, provenance, units and time basis, assumptions, caveats and a comparability label. Scores from different model classes are complementary: never average or rank them.

Source code

Six open-source models, plus an open wrapper for DEFINE-UK (upstream unlicensed, never hosted).