Finology MCP Server — deterministic federal student loan math for AI agents

Language models guess at federal student loan rules. This doesn't.

@finology/mcp-server connects Claude, Cursor, or any MCP client directly to Finology Software's parity-verified federal repayment engine. Every number is computed server-side against current federal rules and returned with a parityVerified flag. No formulas are approximated, and none are hardcoded into this package.

Why this exists

Federal repayment eligibility is not arithmetic, it is regulation, and it is the part models get wrong most confidently:

• A Parent PLUS loan is not RAP-eligible. Ask a model for the best plan on a Parent PLUS balance and it will usually produce a RAP payment. This server returns the exclusion and the rule behind it.
• RAP is assessed on full AGI with no poverty-line shield, on a sliding 1%–10% scale, less $50 per qualifying dependent — and a spouse is not a dependent. Approximating it from older IDR formulas gives the wrong answer.
• A consolidation that repaid a PLUS loan is restricted to ICR.
• PAYE and SAVE are closed to new enrollment.

Tools

compare_federal_student_loan_repayment_plans

Compares a balance across every plan the borrower is actually eligible for — RAP, IBR, ICR, PAYE, SAVE, Graduated, Extended, tiered Standard — returning monthly payment, lifetime cost, projected forgiveness and tax on forgiveness for each, plus the plans that are excluded and the eligibility rule that excludes them.

compare_married_filing_jointly_vs_separately_student_loans

For a married borrower, prices the filing-status decision. Filing separately removes the spouse's income from the income-driven payment calculation, which routinely moves the lifetime loan cost by tens of thousands of dollars.

When both spouses carry federal loans, pass the spouse's own federal balance as well: under joint filing the household payment is split by each spouse's share of the combined balance (34 CFR 685.209(g)(1)(i)), and leaving it out overstates the borrower's payment.

It answers half the question on purpose, and says so. The engine models the loan side exactly and does not model the tax cost of filing separately — lost credits, worse brackets, community-property splits — which is often large enough to reverse the answer. Returning only the favourable half as if it were the whole decision would be the same confident half-truth this server exists to replace.

estimate_rap_monthly_payment

The RAP monthly payment alone, for the common case. Requires the borrower's AGI and refuses to proceed without it — an assumed zero returns the $10/month RAP floor, which reads exactly like a real answer.

Going further (no sales call, no marketing)

Every answer ends with the next rung, and finology_service_info returns it structured:

• Advisor: Finology Software, US $99 per advisor per month or $89 per month billed annually, with a self-serve 7-day trial (card on file, nothing charged until it ends). Includes client file import, saved scenarios, branded client reports, and the student loan and SAI calculators on up to 2 of the firm's own websites.
• Developer / operator: an instant free sandbox key (POST https://api.finology.tech/v1/keys/sandbox, 25 calls/month), then the keyed endpoints with X-Api-Key. The keyed rung is the answer-of-record surface: every answer is persisted with its rule version and an inputs hash before it is served. Production access is self-serve: Developer, US $49 a month for 2,000 calls, or Platform, US $499 a month for 100,000 calls. Docs: https://finology.tech/developers/
• Keyed remote MCP: https://mcp.finology.tech/mcp. Sign in with a Finology Software login (OAuth), which is how Claude connects, or send the X-Api-Key header. Every answer is logged and carries a verify link.

Install

Claude (web, desktop and mobile) — one click. Finology Software is listed in the Claude Connectors Directory. Add the connector there and sign in with a free Finology Software login (no card): 5 questions in total, no daily limit. Subscribers are unlimited, and a subscriber's login also lists their own clients in the same connector (list_my_clients, run_projection_for_client, get_balance_trajectory_for_client).

Everything below is the manual route, for other MCP clients or for a local install.

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "finology": {
      "command": "npx",
      "args": ["-y", "@finology/mcp-server"]
    }
  }
}

The local package needs no API key and no account: it calls the public calculation endpoints.

What is and is not in this repository

Not here, deliberately: the RAP/OBBB formulas, income-driven payment math, forgiveness and tax-bomb projection, plan-eligibility rules, and NSLDS parsing. Those run on Finology's servers.

That is not only about protecting the engine. Federal repayment rules move every year — poverty guidelines, tax brackets, RAP/OBBB implementation guidance, court challenges. A formula copied into an npm package is wrong within months and cannot be corrected in the installs that already exist. Calling a maintained endpoint is the only shape of this tool that stays true.

Here: the input schemas, the HTTP call, and error handling that passes the API's own field-level messages through to the model instead of flattening them into "request failed."

Limits

These tools return figures. They do not produce client-facing deliverables, save borrower records, parse NSLDS files, or track PSLF qualifying payments over time. For those, and for a book of borrowers kept current as the rules change: finology.tech

The local package is rate-limited per IP. Not financial advice.

License

MIT