{"_id":"@askcal/mcp-server","name":"@askcal/mcp-server","dist-tags":{"latest":"0.2.0"},"versions":{"0.2.0":{"name":"@askcal/mcp-server","version":"0.2.0","description":"MCP server for Cal — the AI mortgage platform at askcal.io. Exposes Cal's lender library, DPA programs, lender intel, ValueGuard valuations, and authoritative loan-limit / fee facts to any MCP-compatible client (Claude Desktop, Cursor, Continue, Goose, Ze","license":"MIT","type":"module","main":"dist/index.js","bin":{"cal-mcp-server":"dist/index.js"},"scripts":{"build":"tsc","start":"node dist/index.js","dev":"tsc --watch","smoke":"node scripts/smoke.mjs","prepublishOnly":"npm run build"},"engines":{"node":">=18"},"keywords":["mcp","modelcontextprotocol","model-context-protocol","claude","claude-desktop","mortgage","home-loans","lender","lending","real-estate","fha","va","fannie-mae","freddie-mac","dpa","valuation","askcal","cal"],"homepage":"https://askcal.io","repository":{"type":"git","url":"git+https://github.com/askcal/cal-mcp-server.git"},"bugs":{"url":"https://github.com/askcal/cal-mcp-server/issues"},"author":{"name":"Chris Black","email":"chris@askcal.io","url":"https://askcal.io"},"dependencies":{"@modelcontextprotocol/sdk":"^1.0.4"},"devDependencies":{"@types/node":"^22.7.5","typescript":"^5.6.3"},"_id":"@askcal/mcp-server@0.2.0","types":"./dist/index.d.ts","_nodeVersion":"22.22.3","_npmVersion":"10.9.8","dist":{"integrity":"sha512-9T9t7V70QZv1RHXA817+Z4IMhjmahjlheQPYLHVs/6CkXXBai2SbsH8XUP7GUVm41xrs9CHhFJYnLi2sBm9AAA==","shasum":"acaef1d0365d069581b75ea6c0fb2b2c2b8be367","tarball":"https://registry.npmjs.org/@askcal/mcp-server/-/mcp-server-0.2.0.tgz","fileCount":25,"unpackedSize":37514,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCniVg+J4tY7CdDwGywHu4b89f1T0hkLetwS36+LwOs8gIgMn9ChCnAr9u2+p9NAUaHp2+8lfAGh3+85w3yoE3FH90="}]},"_npmUser":{"name":"chrisblack","email":"chrisblack584@gmail.com"},"directories":{},"maintainers":[{"name":"chrisblack","email":"chrisblack584@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-server_0.2.0_1783121214930_0.8578747641038373"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-03T23:26:54.816Z","0.2.0":"2026-07-03T23:26:55.071Z","modified":"2026-07-03T23:26:55.267Z"},"maintainers":[{"name":"chrisblack","email":"chrisblack584@gmail.com"}],"description":"MCP server for Cal — the AI mortgage platform at askcal.io. Exposes Cal's lender library, DPA programs, lender intel, ValueGuard valuations, and authoritative loan-limit / fee facts to any MCP-compatible client (Claude Desktop, Cursor, Continue, Goose, Ze","homepage":"https://askcal.io","keywords":["mcp","modelcontextprotocol","model-context-protocol","claude","claude-desktop","mortgage","home-loans","lender","lending","real-estate","fha","va","fannie-mae","freddie-mac","dpa","valuation","askcal","cal"],"repository":{"type":"git","url":"git+https://github.com/askcal/cal-mcp-server.git"},"author":{"name":"Chris Black","email":"chris@askcal.io","url":"https://askcal.io"},"bugs":{"url":"https://github.com/askcal/cal-mcp-server/issues"},"license":"MIT","readme":"# Cal MCP Server\n\n> The mortgage MCP server, with a real lender data moat. **166+ wholesale lenders · 1,400+ indexed program documents · 250+ down‑payment‑assistance programs · 50 states.** First Model Context Protocol server in the mortgage industry with broker‑accessible matrix data behind it — not a calculator, not a rate scraper.\n\n`@askcal/mcp-server` exposes Cal — the AI mortgage platform at [askcal.io](https://askcal.io) — to any [Model Context Protocol](https://modelcontextprotocol.io) client: Claude Desktop, Cursor, Continue, Goose, Zed, Cody, your own agent. Loan officers, brokers, real‑estate agents, and consumer borrowers can ask their AI assistant questions like:\n\n- *\"What's the 2026 conforming loan limit in Alameda County, CA, for a 1‑unit?\"*\n- *\"Top 5 wholesale jumbo lenders in California for a 712‑FICO, 80% LTV, $1.4M loan with a departing residence still listed.\"*\n- *\"What DPA programs in Orange County California work for a first‑time buyer with 700 FICO?\"*\n- *\"Plaza Home Mortgage — what's their current master credit guideline document, and which AE covers Northern California?\"*\n- *\"Show me the structuring playbook for a sub‑580 FHA file.\"*\n\n…and Cal returns answers grounded in current matrix PDFs, FHFA / HUD / VA source documents, and tribal‑knowledge intel curated by working brokers.\n\n## Why this matters\n\nThe mortgage industry has spent a decade in the \"everybody buys Encompass\" era. AI hasn't touched the workflow because the source data is gated, fragmented, and expires. Cal's library — built from broker‑portal scrapes, indexed weekly, kept current — is the data layer that makes any mortgage AI actually useful. This MCP server is how that data reaches every agent platform built on top of MCP.\n\nIf you're an LO, this means asking Claude (or Cursor, or your own agent) the same questions you used to dig through PDFs to answer — and getting an answer in seconds with a source citation.\n\n## Tools\n\nThe server exposes eight tools:\n\n| Name | Purpose |\n|---|---|\n| `cal_fact_lookup` | FHFA conforming loan limits, FHA loan limits, VA funding fee, FHA MIP, agency DTI caps. County‑level. 50 states + DC. |\n| `cal_search_lenders` | Scenario‑aware wholesale‑lender finder. Pass FICO / LTV / loan amount / state / occupancy → ranked top 5 (or top 15 with `expand=true`) with score, qualifying reasons, blockers. |\n| `cal_lender_details` | Full record for one lender — programs, state licenses, AE contact, broker portal URL, status, recent matrix dates. |\n| `cal_lender_documents` | List indexed matrices / handbooks / overlays for a lender. Sorted master → current → superseded. Each doc includes a short extracted summary. |\n| `cal_dpa_search` | Down‑payment‑assistance programs by state / county / city / FTHB / type. Up to 25 ranked programs with provider URLs. |\n| `cal_lender_intel` | Tribal‑knowledge intel — strengths, watch‑outs, speed notes, scenarios they love, scenarios to avoid, AE contacts. Pass `intent` to narrow. |\n| `cal_scenario_pattern` | Structuring playbooks for hard scenarios: departing residence, ITIN / foreign national, sub‑580 FHA, renovation, super‑jumbo, plus the matrix‑freshness citation rule. |\n| `cal_valuation` | ValueGuard comparable-sales valuation. Pass the subject (price + sqft) and 4+ comps, get the indicated market value, a floor/ceiling range, an over/under-priced verdict, a confidence level, and the comps used. A list-price rebuttal in seconds. |\n\nThe tool surface mirrors Cal's internal tool‑use schema, so any model (Claude Sonnet, Opus, Haiku, GPT‑4o, Gemini, …) that calls them gets the same shape Cal itself uses.\n\n## Install\n\n### Claude Desktop (macOS / Windows)\n\nAdd this to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"cal\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@askcal/mcp-server\"],\n      \"env\": {\n        \"CAL_API_TOKEN\": \"your-token-here\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop. The `cal` tools appear in the slash menu.\n\n### Cursor\n\nSettings → MCP → Add Server, then paste the same JSON.\n\n### Continue / VS Code\n\n`~/.continue/config.json` → `mcpServers` block, same shape.\n\n### Local dev (clone + link)\n\n```bash\ngit clone https://github.com/askcal/cal-mcp-server.git\ncd cal-mcp-server\nnpm install\nnpm run build\n# Then point your MCP client at dist/index.js with `node` as the command\n# and an absolute path in args[0].\n```\n\n## Getting a token\n\n`CAL_API_TOKEN` is an opaque bearer token. **Use a long‑lived API key, not a session token** — session tokens from `/auth/login` expire after 8 hours, which means an MCP client config that worked today returns 401 tomorrow.\n\n### Recommended — long‑lived API key (`cal_live_…`)\n\nSign up at [api.askcal.io](https://api.askcal.io) (request access if you don't have a key yet — broker LOs are auto‑approved). Then:\n\n```bash\n# 1. Get a short‑lived session token from /auth/login\nSESSION=$(curl -s -X POST https://api.askcal.io/auth/login \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Origin: https://askcal.io\" \\\n  -d '{\"email\":\"<your-email>\",\"password\":\"<your-password>\",\"portal\":\"team\"}' \\\n  | sed -n 's/.*\"token\":\"\\([^\"]*\\)\".*/\\1/p')\n\n# 2. Mint a long‑lived API key\ncurl -X POST https://api.askcal.io/auth/api-keys \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Origin: https://askcal.io\" \\\n  -H \"Authorization: Bearer $SESSION\" \\\n  -d '{\"label\":\"my-claude-desktop\"}'\n```\n\nThe response includes a `key` field starting with `cal_live_`. **Copy it now — it's only shown once.** Use it as `CAL_API_TOKEN`. The key has no expiry; revoke it any time with `DELETE /auth/api-keys/<id>` (list yours with `GET /auth/api-keys`).\n\n### Fallback — session token\n\nIf you just want to try a tool call quickly, the session token from `/auth/login` works too (8‑hour TTL). Don't put one in a long‑lived MCP config.\n\n### v0.2 preview\n\nOAuth 2.1 with PKCE is on the roadmap so MCP clients can run the consent flow themselves. Until then, the API key flow above is the recommended path.\n\n## Verify it works\n\nAfter installing, ask your MCP client:\n\n> *\"What's the 2026 conforming loan limit in Alameda County CA?\"*\n\nYou should get back something like:\n\n```\n$1,229,100 (FHFA 2026 Conforming Loan Limits, announced 2025‑11‑26).\nHigh‑balance HCOL county. Anything above this is a jumbo loan.\n```\n\nIf you don't, check:\n\n1. The token isn't expired — Cal session tokens last 24 hours by default. Refresh via `/auth/login`.\n2. Network can reach `https://api.askcal.io`.\n3. Your MCP client picked up the config — restart it after editing.\n\n## Configuration\n\n| Env var | Required | Default | Notes |\n|---|---|---|---|\n| `CAL_API_TOKEN` | yes | — | Bearer token from `/auth/login`. |\n| `CAL_API_BASE_URL` | no | `https://api.askcal.io` | Override only if you're testing against a Cal instance other than production. |\n\n## Data scope\n\nCalls are scoped to the *list* tied to your token. If you're a broker LO with a curated approved‑lender list, results are filtered to lenders you can actually use. Cal will not leak across approved lists. The founder's demo list is the broadest, at 166 lenders.\n\n## License\n\nMIT. The wrapper code is open. Cal's curated lender library, DPA program data, and lender intel are proprietary and remain behind the API.\n\n## About Cal\n\nCal is the AI mortgage platform at [askcal.io](https://askcal.io), built by a 17‑year industry veteran (NMLS 275073) for working brokers. Production state at this release:\n\n- 166 wholesale lenders, 1,424 indexed program documents, 250 DPA programs, 50 states\n- 4 LOs in pilot, 342 questions answered in the first 24 hours of soft‑launch\n- $500K committed + $1.5M soft‑committed → $2M seed target\n\n\n## Roadmap\n\n- **v0.1** - 7 tools, API-key auth, stdio transport, npm + GitHub.\n- **v0.2** *(current)* - ValueGuard valuation (`cal_valuation`), 8 tools total; repointed to the askcal.io API.\n- **v0.3** - OAuth 2.1 with PKCE. `.dxt` Claude Desktop bundle. Optimal Blue MCP companion server.\n- **v0.4** - Streamable HTTP transport. Public agency MCPs (Fannie Selling Guide, Freddie Guide, FHA Handbook 4000.1, VA Handbook 26-7, FHFA limits, HUD AMI).\n- **v0.5** - Encompass MCP companion (LOS read/write). DocuSign MCP companion. One prompt fires across CRM + email + calendar + pricing + library.\n\n## Contributing\n\nIssues and PRs welcome. The roadmap above is the priority order; if you want to take a piece, open an issue first so we don't dual‑track.\n\n## Contact\n\nChris Black · NMLS 275073 · chris@askcal.io · 925‑286‑7681\n","readmeFilename":"README.md","_rev":"1-eb95e4d2d8b956e4454c113edb6bd89c"}