{
  "markdown": "# American Default Research — MCP Server\n\nA Model Context Protocol server that exposes American Default Research data — 96 economic distress indicators, the American Distress Index (ADI) composite score, and county-level distress scores across all 3,144 U.S. counties — to MCP-compatible AI agents.\n\n**Official MCP Registry namespace:** `org.americandefault/research`\n**Hosted endpoint:** `https://mcp.americandefault.org/mcp` (streamable HTTP)\n**Website:** [https://americandefault.org/press/mcp/](https://americandefault.org/press/mcp/)\n\n---\n\n## Use the hosted MCP (recommended)\n\nPoint any MCP-compatible client at the hosted streamable-HTTP endpoint. No install, no data files, no maintenance — every response is generated against the same data that powers [americandefault.org](https://americandefault.org).\n\n### Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"american-default-research\": {\n      \"url\": \"https://mcp.americandefault.org/mcp\",\n      \"transport\": \"streamable-http\"\n    }\n  }\n}\n```\n\nRestart Claude Desktop. The 5 tools appear under the hammer icon.\n\n### Smithery\n\nThe MCP is also available via the Smithery gateway at [smithery.ai/servers/americandefault/research](https://smithery.ai/servers/americandefault/research).\n\n### Cursor / other MCP clients\n\nAny client that speaks streamable HTTP can connect by adding the endpoint URL to its MCP server config. The exact config format varies by client — see your client's docs.\n\n---\n\n## Tool surface\n\n| Tool | Input | Returns |\n|---|---|---|\n| `get_indicator(slug)` | bundle slug (e.g. `the-buffer`) | compact snapshot + pre-computed aggregates + canonical citation |\n| `get_county_scorecard(fips)` | 5-digit FIPS (4-digit accepted with implicit leading zero) | CDI scorecard + 5-domain breakdown + pre-baked citations |\n| `get_adi_composite()` | (none) | latest quarter ADI + 5 components + zone + citation |\n| `search_indicators(query, limit=10)` | keyword + optional limit (max 50) | ranked matches (slug, branded_name, name, category, URL) |\n| `get_cross_correlations(slug)` | indicator slug | fully-validated leading/lagging pairs split into `as_leader` + `as_follower` |\n\n### Schema versioning\n\nEvery response carries `schema_version: \"v1\"`. Breaking changes ship as a new tool with a `_v2` suffix — v1 tools stay live for backward compatibility. Callers should assert the schema version they expect.\n\n### Response size budgets\n\n| Endpoint | Budget | Typical |\n|---|---|---|\n| `get_indicator` | ≤ 16 KB | ~13.8 KB |\n| `get_county_scorecard` | ≤ 25 KB | ~2.5 KB |\n| `get_adi_composite` | ≤ 4 KB | ~2.0 KB |\n\nRaw 300+ point indicator series is intentionally omitted from `get_indicator` to keep LLM context budgets manageable. The full series lives at `https://americandefault.org/api/indicators/{slug}.json`.\n\n---\n\n## Canonical attribution\n\nEvery response includes a `citation` object with APA, MLA, Chicago, and news-copy forms. Three-tier naming is enforced:\n\n- **American Default Research** — institutional name, used in citations, source lists, bibliographies\n- **American Default** — brand name, used for URLs and casual references\n- **American Distress Index (ADI)** — product name, used only when the composite score is the subject\n\nSee [`https://americandefault.org/llms.txt`](https://americandefault.org/llms.txt) § \"Canonical Attribution\" for the authoritative spec.\n\n---\n\n## Run locally (optional)\n\nThe recommended way to use this MCP is the hosted endpoint above. The local install path is provided for transparency, audit, and self-hosting — but the local server reads data files from sibling directories (`data/` and `site/src/data/`) that aren't included in this repo. To run locally end-to-end you need either:\n\n1. **Mirror the data files from the public API.** All indicator data is published at `https://americandefault.org/api/indicators/{slug}.json` and county scorecards at `https://americandefault.org/api/counties/{fips}.json`. A small companion script (not bundled) can fetch these into a local `data/` mirror.\n2. **Use this repo as a code reference only.** Read the source, audit the implementation, then point your client at the hosted endpoint.\n\nInstall:\n\n```bash\npython3 -m venv venv\n./venv/bin/pip install -r requirements.txt\n```\n\nProbe (confirms the server boots and discovers tools):\n\n```bash\nPYTHONPATH=. python3 -m scripts.machine_layer.mcp_server --probe\n```\n\nThis emits a JSON handshake to stdout and exits 0 without entering the stdio loop. Use it in CI or as a smoke test.\n\nRun the stdio loop:\n\n```bash\nPYTHONPATH=. python3 -m scripts.machine_layer.mcp_server\n```\n\nStdout is reserved for JSON-RPC framing. Logs go to stderr.\n\n---\n\n## Architecture\n\nThe server is built on `mcp >= 1.27.0` and supports two transports:\n\n- **stdio** (`mcp_server.py`) — for local Claude Desktop / Cursor / IDE plugins\n- **streamable-HTTP** (`http_app.py`) — for the hosted endpoint at `mcp.americandefault.org`\n\nThe HTTP transport adds a bearer-auth middleware (anonymous + issued tiers), two-level token-bucket rate limiting (per-minute burst + per-hour sustained), and per-tier rate limits. See `http_app.py` for the full middleware stack.\n\n### Slug ↔ indicator_id mapping\n\nSource JSONs carry both `indicator_id` (snake_case) and `slug` (kebab-case). 91 of 96 indicators have slugs that DO NOT mechanically transform from their id — branded indicators use marketing names like `the-buffer` (id: `savings_rate`), `the-horizon` (id: `ai_capability`), `the-pinch` (id: `census_htops_difficulty`).\n\nThe server builds a boot-time bidirectional map by scanning every source JSON once (~100ms). Lookups are O(1) thereafter.\n\n### Empty-data bundles\n\n10 of 96 bundles ship without populated data — indicators tracked but not yet backfilled (AI job postings, ABA consumer discretionary, NMHC rent tracker, utility disconnections, etc.). These return `status: \"awaiting_population\"` with full metadata and a null `latest_value`. Agents can discover the slug exists without receiving phantom data.\n\n### Rate limiting (HTTP transport)\n\nTwo-level token bucket keyed by IP and bearer-token contact:\n\n- **Per-minute burst** — `MCP_RATE_LIMIT_RPM`, default `60`\n- **Per-hour sustained** — `MCP_RATE_LIMIT_RPH`, default `600`\n\nAnonymous tier (no bearer) gets the default. Issued tier (valid bearer) gets a higher allowance configured server-side.\n\n---\n\n## Data sources\n\nThis MCP serves data sourced from FRED (Federal Reserve Economic Data), BLS (Bureau of Labor Statistics), NY Fed Household Debt and Credit Report, ATTOM Data Solutions, Mortgage Bankers Association, American Bankruptcy Institute / Epiq Systems, and additional primary government and industry sources. Data is updated daily via automated pipelines.\n\nPer-indicator source attribution is included in every `citation` field returned by the server. The full source-attribution methodology is at [https://americandefault.org/methodology/](https://americandefault.org/methodology/).\n\n---\n\n## About American Default Research\n\nAmerican Default Research is a nonpartisan data project tracking U.S. household financial distress. It publishes the American Distress Index (ADI) — a composite 0-100 score built from five statistically derived components — and the County Distress Index (CDI) for all 3,144 U.S. counties.\n\nWebsite: [https://americandefault.org](https://americandefault.org)\nPress: [https://americandefault.org/press/mcp/](https://americandefault.org/press/mcp/)\nMethodology: [https://americandefault.org/methodology/](https://americandefault.org/methodology/)\n\n---\n\n## License\n\nMIT — see `LICENSE`.\n\nData is free to use with attribution per the canonical attribution block at `https://americandefault.org/llms.txt`.\n\n---\n\n## Issues and contributions\n\nBug reports and feature requests welcome via GitHub Issues on this repo. Pull requests are reviewed against the data pipeline's correctness gates — see [`https://americandefault.org/llms.txt`](https://americandefault.org/llms.txt) for the data-accuracy standard.\n",
  "bytes": 8031,
  "sha": "153a05b73b608a2e4128408c330238b1036baa363fe386f4ea8513023c927e8b",
  "repo_slug": "vibecode1/american-default-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_org_americandefault_research_70d285de/readme"
}