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/mcpAdd 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/mcpNeeds an eligible ChatGPT web plan: Settings → Apps → Advanced Settings → Developer mode → new custom app with the URL. Admins may need to grant access.
For Codex CLI
codex mcp add policyengine-macro --url https://policyengine--policyengine-macro-mcp-serve.modal.run/mcpAdd it as a remote HTTP MCP server in Gemini CLI, Cursor, VS Code, Windsurf, Le Chat or any MCP client.
Gemini CLI
gemini mcp add --transport http policyengine-macro https://policyengine--policyengine-macro-mcp-serve.modal.run/mcpAsk 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_serverInstall once
pip install "policyengine-macro[models] @ git+https://github.com/PolicyEngine/macro#subdirectory=integration"Run a command
- Which models run here
pe-macro model-status - Household calculation
pe-macro household --country us --people '[{"age":35,"employment_income":50000}]' --household '{"state_code":"CA","county_fips":"06037"}' - Score a UK reform
pe-macro score --country uk --reform '{"gov.hmrc.income_tax.rates.uk[0].rate":0.21}' --model obr - UK forecast
pe-macro forecast - US rate shock
pe-macro frbus-shock --var rffintay_aerr --shock 1.0 - US HANK shock
pe-macro hank-shock --kind monetary --size -0.0025 --persistence 0.61
Add --json to any command for machine-readable output.
Local UK population runs need private FRS access (HUGGING_FACE_TOKEN); hosted calls need nothing.
Shock units differ by lever and model: run pe-macro variables, pe-macro frbus-variables or pe-macro hank-summary first. Every CLI command on GitHub →
pip install "mcp>=1,<2"import asyncio, json
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client
URL = "https://policyengine--policyengine-macro-mcp-serve.modal.run/mcp"
async def call(tool, args=None):
async with streamablehttp_client(URL, timeout=300) as (read, write, _):
async with ClientSession(read, write) as session:
await session.initialize()
res = await session.call_tool(tool, args or {})
if res.isError: # a failed tool or job returns plain text, not JSON
raise RuntimeError(res.content[0].text)
return json.loads(res.content[0].text)
forecast = asyncio.run(call("forecast_uk", {"horizons": 4}))
Polling helper for slow tools
async def run_job(tool, args):
"""Slow tools: start a job, then poll until it is done."""
job = await call("start_job", {"tool": tool, "arguments": args})
while True:
r = await call("get_job_result", {"job_id": job["job_id"], "wait_seconds": 30})
if r["status"] == "done":
return r["result"]
if r["status"] in ("error", "failed"):
raise RuntimeError(r)
score = asyncio.run(run_job("score_reform", {
"country": "uk", "model": "obr",
"reform": {"gov.hmrc.income_tax.rates.uk[0].rate": 0.21},
"years": 2, # each scored year adds a microsimulation run; 2 keeps the job short
}))
from policyengine_macro import core
forecast = core.svar_forecast(horizons=4)
irf = core.frbus_shock(var="rffintay_aerr", shock=1.0)
hank = core.hank_shock(kind="monetary", size=-0.0025, persistence=0.61)
household = core.pe_household(
country="us",
people=[{"age": 35, "employment_income": 50000}],
household={"state_code": "CA", "county_fips": "06037"},
)
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
| Model | Tools |
|---|---|
| PolicyEngine microsimulationpe-microsim | calculate_householdhousehold_reform_impactlist_reform_parameterspopulation_reform_impact |
| OBR emulatorobr-macro | score_reformobr_shocklist_reform_variables |
| BoE SVARboe-svar | forecast_uklatest_shocksmodel_summarysvar_inflation_incidence |
| FRB/USfrb-us | frbus_shockfrbus_list_variablesfrbus_summaryfrbus_shock_incidence |
| US HANKus-hank | hank_shockhank_summaryhank_shock_incidence |
| OG-UKpsl-og, og+microsim | dynamic_reform_impactscore_reform model='og' |
| DEFINE-UKdefine-uk | define_scenario_incidencedefine_list_scenariosdefine_scenario |
| Routing and reports | list_model_capabilitiesget_model_statusrecommend_modelformat_score_report |
| Jobs | start_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-modelfetches 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.jsonthere, thenpe-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.
Longer calls run as 30-minute jobs
Scales to zero when idle
Cold start ~20 s; UK forecast takes minutes
Limits in detail
- The hosting transport drops any request after 150 seconds.
start_jobhands a slow call to a worker with a 30-minute budget and returns a job id; pollget_job_result.score_reformand the four*_incidencetools always run as jobs hosted (each takes longer than the ceiling);obr_shock,frbus_shock,hank_shockand a population run (pe_population_impact) when cold. Locally, call the tool directly. get_job_resultblocks 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*_incidencetools under their own names, andsvar_forecastfor aforecast_ukwith 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(privatepolicyengine-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_reformresult carries ascoreblock: 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).