MCP workflow for empirical economists¶
This guide is for the common agent workflow: a researcher has a local .dta,
CSV, Parquet, or Arrow file and wants Claude Code, Codex, Cursor, or another
MCP client to run a defensible empirical design without hand-copying arrays
between tools.
StatsPAI's MCP server is deliberately local-first. It loads the file you point it at, fits StatsPAI estimators, returns strict JSON, and caches fitted result handles so follow-up diagnostics can reuse the same object.
Configure the server¶
Let StatsPAI write the entry for you. Run this in the environment where you installed StatsPAI:
statspai mcp config --client claude-code # prints `claude mcp add ...`
statspai mcp config --client cursor --write # edits ~/.cursor/mcp.json
statspai mcp doctor # checks every configured client
The entry runs this interpreter by absolute path
(<python> -m statspai.agent.mcp_server). That matters because a client
that launches statspai-mcp by name gets whichever environment comes first
on its PATH, which is often an older StatsPAI than the one you just
upgraded. doctor asks each configured interpreter which StatsPAI it
imports and says so when they differ. --write keeps your other servers and
saves the old file as a timestamped backup. Clients: claude-code,
claude-desktop, cursor, windsurf, vscode and codex.
The package also exposes statspai-mcp and the module entry point
python -m statspai.agent.mcp_server. A hand-written Claude Desktop entry:
{
"mcpServers": {
"statspai": {
"command": "python",
"args": ["-m", "statspai.agent.mcp_server"]
}
}
}
For clients that prefer a console script, use:
The server speaks stdio JSON-RPC and serves both generations of the MCP
protocol. Clients of the current revision (2026-07-28) send no handshake and
name the version on every request. Older clients open with initialize and
negotiate 2025-11-25 or an earlier revision. Results carry
structuredContent with a compact outputSchema, and the same object as
compact JSON text. statspai-mcp --version prints the package version, the
interpreter and the revisions the server speaks.
Useful server settings (set them in the client's env block):
{
"mcpServers": {
"statspai": {
"command": "statspai-mcp",
"env": {
"STATSPAI_MCP_DATA_ROOTS": "/Users/me/research/data",
"STATSPAI_MCP_MAX_OUTPUT_BYTES": "262144"
}
}
}
}
STATSPAI_MCP_DATA_ROOTS limits which directories the model may read;
network URLs stay off unless you add "STATSPAI_MCP_ALLOW_REMOTE": "1".
Data handoff¶
Every data-bound tool accepts one of four sources:
| Argument | What it is | When to use it |
|---|---|---|
data_path |
absolute file path or URL | the first time a file enters the session |
data_id |
handle (d_…) returned by load_data / transform_data |
every later call — no re-upload, lineage recorded |
data_records |
JSON array of row objects | a small table you built by hand |
data_csv |
CSV text with a header row | the same, as text |
The recommended pattern is load_data once, then handles:
{"name": "load_data", "arguments": {"data_path": "/abs/cfps_panel.dta", "name": "CFPS"}}
→ {"data_id": "d_3f9a1c2e", "n_rows": 41230, "dtypes": {...}, "missing": {"wage": 812}, "head": [...]}
{"name": "transform_data", "arguments": {"data_id": "d_3f9a1c2e", "operations": [
{"op": "dropna", "columns": ["wage"]},
{"op": "query", "expr": "year >= 2010 and age < 65"},
{"op": "assign", "column": "lwage", "expr": "log(wage)"},
{"op": "winsor", "columns": ["lwage"], "cuts": [1, 99]}
]}}
→ {"data_id": "d_8b02e7d4", "parent_id": "d_3f9a1c2e", "operations": [...], "n_rows": 28744}
{"name": "callaway_santanna", "arguments": {"data_id": "d_8b02e7d4", "y": "lwage", "g": "first_treat", "t": "year", "i": "id", "as_handle": true}}
transform_data operations: query, select, drop, rename, dropna,
fillna, assign, sort, sample, winsor, wide_to_long,
long_to_wide, mice, and function (any sp.<name> that takes data=
and returns a DataFrame). A failing step aborts the chain and reports the
step index, so a half-transformed frame is never registered. describe_data
profiles any handle; statspai://data/<id> reads it back with its lineage.
Handles live in the server process (LRU, STATSPAI_MCP_DATA_CACHE_SIZE,
default 16 frames, and STATSPAI_MCP_DATA_CACHE_BYTES, default 2 GiB); a
missing handle comes back as an isError result with
error_kind: "missing_data_handle" and a miss_reason saying whether it was
evicted (lru / bytes), expired or never existed — the fix is always
load_data again. query / assign expressions accept columns, constants,
operators, math functions and col.isnull()-style methods only; anything else
fails with error_kind: "unsafe_expression".
Every result fitted from a handle carries the full chain in
data_provenance (source_type: "handle", lineage, and the root file's
hash), so a table note can state exactly how the analysis sample was built.
Supported local and remote formats include:
| Format | Notes |
|---|---|
.dta |
Native Stata files through pandas.read_stata |
.csv, .tsv, .txt |
Delimited text |
.parquet, .pq, .feather, .arrow |
Column projection supported |
.xlsx, .xls |
Spreadsheet inputs |
.json, .jsonl |
JSON records |
file:// |
Local file URL (subject to STATSPAI_MCP_DATA_ROOTS) |
https://, http://, s3://, gs:// |
Network URLs — only with STATSPAI_MCP_ALLOW_REMOTE=1; http(s) via urllib, s3/gs via fsspec |
For large files, pass:
data_columns narrows the read when the backend supports it. data_sample_n
uses deterministic random sampling for quick exploration. Raise or disable the
loader cap with STATSPAI_MCP_MAX_DATA_BYTES only when the host has enough
memory; the same cap applies to remote downloads (checked against
Content-Length / object size, and enforced while streaming).
When the MCP server loads a local file, tool results include
data_provenance: source path, format, requested columns/sample, file size,
mtime, and SHA-256. statspai://result/<id> exposes the same provenance through
the cached result metadata. Remote URLs are recorded after dropping query tokens;
StatsPAI does not hash remote bytes unless the data are first saved locally.
Results are bounded too: max_output_bytes (default 256 KiB) trims the
longest lists / tables and lists each cut under truncated; estimates, SEs,
CIs and p-values are never cut. Every estimator result carries replay, the
Python call (sp.<fn>(data=data, ...) # data = data_path '...') that
reproduces it outside the agent loop — paste it into the replication script.
The core loop¶
Use result handles. They keep the agent from copying fitted objects through chat text.
detect_design -> preflight/recommend -> fit(as_handle=true)
-> audit_result -> sensitivity_from_result / plot_from_result
-> bibtex
The fitted estimator returns result_id. Pass it to:
| Tool | Purpose |
|---|---|
audit_result |
Reviewer checklist of missing diagnostics |
brief_result |
One-line estimate summary |
interpret_result |
Grounded explanation, optionally using MCP sampling |
plot_from_result |
Inline PNG diagnostic plot; kind= picks one of the reply's valid_kinds (rdplot, synth_gap, event_study, ...), any other kind is refused |
sensitivity_from_result |
E-value / Oster / Cinelli-Hazlett style checks |
honest_did_from_result |
Rambachan-Roth sensitivity from DID/event-study results |
bibtex |
Verified BibTeX from StatsPAI's citation registry |
One-call empirical pipelines¶
StatsPAI includes high-level MCP pipeline tools for the most common designs.
DID¶
{
"name": "pipeline_did",
"arguments": {
"data_path": "/abs/cfps_panel.dta",
"y": "lwage",
"treat": "treated",
"time": "year",
"id": "pid",
"cohort": "first_treat",
"covariates": ["age", "age2", "edu", "industry"],
"as_handle": true
}
}
When id and cohort are supplied, the pipeline dispatches the
Callaway-Sant'Anna path. Otherwise it falls back to the 2x2 DID path. It then
adds the audit, honest-DID sensitivity where possible, Bacon diagnostics where
available, a narrative, and follow-up calls.
IV¶
{
"name": "pipeline_iv",
"arguments": {
"data_path": "/abs/card.dta",
"formula": "lwage ~ exper + expersq + black + south + smsa + (educ ~ nearc4)",
"as_handle": true
}
}
The IV pipeline reports the fitted estimate and weak-IV diagnostics, and prioritizes Anderson-Rubin-style inference when first-stage evidence is weak.
RD¶
{
"name": "pipeline_rd",
"arguments": {
"data_path": "/abs/lee_senate.dta",
"y": "voteshare_next",
"x": "margin",
"c": 0,
"as_handle": true
}
}
The RD pipeline fits rdrobust, attempts the canonical RD plot, checks density
manipulation, and returns bandwidth-sensitivity follow-ups.
Stata and R command migration¶
StatsPAI ships translator tools for one command at a time:
| Source | MCP tool | Examples |
|---|---|---|
| Stata | from_stata |
regress, xtreg, reghdfe, ivreg2, ivreghdfe, csdid, did_imputation, synth, rdrobust, psmatch2, count-panel commands |
| R | from_r |
feols, felm, lm, glm, plm, matchit, att_gt, did, synth |
Use the built-in prompts:
| Prompt | Use |
|---|---|
stata_command_workflow |
Translate a single Stata command, fit the translated StatsPAI tool, then audit |
r_command_workflow |
Translate a single R expression, fit, then audit |
cross_language_command_check |
Translate Stata and R snippets, compare estimand/covariance conventions, then fit comparable StatsPAI calls |
These prompts are conservative. If a translator returns ok=false, the agent
should report suggestions instead of guessing. If Stata and R snippets imply
different controls, fixed effects, cohorts, or covariance conventions, treat
that as a mismatch before fitting.
For psmatch2, from_stata maps the common nearest-neighbor, kernel, radius,
common, and ai() paths onto sp.psmatch2. Convention-changing options such
as Stata's probit propensity score or ATE-focused requests are surfaced as
notes rather than silently claimed as exact parity; use sp.match directly for
ATE-oriented matching.
For ivreghdfe, from_stata maps the IV-with-fixed-effects command to the
same StatsPAI/fixest shape produced by R feols(... | fe | endog ~ instr):
the formula contains the IV block and fe=[...] carries the absorbed fixed
effects. This is a migration contract for dispatching StatsPAI; it is not a
live Stata run.
Cross-software verification discipline¶
StatsPAI already stores committed R and Stata parity artifacts under
tests/r_parity/ and tests/stata_parity/. The Track A 3-way report compares
Python, R, and Stata outputs with pre-registered tolerances. Use it to decide
whether a StatsPAI result is:
| Status | Meaning |
|---|---|
| machine-level agreement | Point estimates match at tight tolerance |
| iterative/cross-fit agreement | Random folds or optimizers need a wider registered tolerance |
| convention gap | Backends target different estimands or covariance conventions |
| unavailable | No committed external artifact yet |
In MCP clients, read statspai://parity/track-a-summary for a compact JSON
summary of the committed Track A report. It includes strictness-tier counts,
module ids, Stata command labels, convention notes, and a tool_evidence index
keyed by common StatsPAI tool names, without loading the full markdown artifact
into the model context.
Do not call a live Stata/R comparison unless a separate Stata or R MCP server is configured and actually invoked. The StatsPAI translators check whether command semantics align; they are not themselves Stata or R runtimes.
External data MCP servers¶
For World Bank, OECD, FRED, IMF, or OpenEcon-style data MCP servers, keep the responsibilities separate:
- Use the data MCP server to search and retrieve indicators.
- Save the returned table to CSV, Parquet, Arrow, or
.dta. - Pass the saved file path to StatsPAI through
data_path. - Preserve the source metadata in your notebook, table notes, or paper appendix: provider, indicator id, query, retrieval date, and transformation code.
StatsPAI should analyze the bytes it receives. It should not invent missing indicator values, source names, or retrieval provenance.
Suggested first prompt¶
Use the statspai MCP server. Load /abs/cfps_panel.dta.
Run pipeline_did with y=lwage, treat=treated, time=year, id=pid,
cohort=first_treat, controls age age2 edu industry, as_handle=true.
Then audit the result, run the first feasible high-importance follow-up,
render the canonical plot, and return a short methods paragraph plus a
regression-table export suggestion.