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

[![npm](https://img.shields.io/npm/v/@finology/mcp-server?logo=npm&label=%40finology%2Fmcp-server)](https://www.npmjs.com/package/@finology/mcp-server)
[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-tech.finology%2Fstudent--loan-4F46E5)](https://registry.modelcontextprotocol.io/v0.1/servers/tech.finology%2Fstudent-loan/versions/latest)
[![Finology-tech/finology-mcp MCP server](https://glama.ai/mcp/servers/Finology-tech/finology-mcp/badges/score.svg)](https://glama.ai/mcp/servers/Finology-tech/finology-mcp)
[![Claude Connectors Directory](https://img.shields.io/badge/Claude%20Directory-Finology%20Software-4F46E5)](https://claude.ai/directory/finology-student-loans)

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

`@finology/mcp-server` connects Claude, GitHub Copilot, Cursor, or any MCP client directly to
[Finology Software](https://finology.tech)'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 ICR are still open, with conditions, until no later than July 1, 2028.** Following
  Federal Student Aid, PAYE is open to a PAYE "new borrower" with no new loan or consolidation on
  or after July 1, 2026, and ICR is open to eligible loan types. Loans made on or after July 1, 2026
  can use only the tiered Standard plan or RAP. SAVE is closed to new enrollment.

## Tools

### `compare_federal_student_loan_repayment_plans`

Compares a balance across every plan the borrower is actually eligible for — Standard, tiered
Standard, RAP, IBR, PAYE and ICR — 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.**

**A balance and income are enough.** A linked loan account often shows the balance only. Omit
`ratePct` and the tool uses the 2026-27 federal rate for the loan type (undergraduate Direct
Unsubsidized or Subsidized 6.52%, Grad PLUS and Parent PLUS 9.07%) and says so as the first line
of the answer. Graduate and professional Direct Unsubsidized loans carry 8.07%; the answer names
it, so pass `ratePct: 8.07` for those. A consolidation loan has no federal rate (it is the weighted
average of the loans it repaid, rounded up to the next one-eighth of a percent), so it still needs
`ratePct`, and the tool asks for it.

Set `loansMadeOnOrAfterJuly2026: true` when the loans were first disbursed (or consolidated) on or
after July 1, 2026. The engine then prices only the plans new loans can elect: RAP and the tiered
Standard plan (a Parent PLUS loan: the tiered Standard plan only). Left false, the loans are run as
made before that date.

### `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.

A balance and both incomes are enough here too: `ratePct` and `loansMadeOnOrAfterJuly2026` work as
in the plan comparison above.

**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 favorable 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, no card required (add a card to keep the subscription after day 7). 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, ChatGPT and Microsoft Copilot connect, 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](https://claude.ai/directory/finology-student-loans). 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`).

**ChatGPT.** Finology Software is in the
[ChatGPT plugin directory](https://chatgpt.com/plugins/plugin_asdk_app_6abbf32753248191a0dbf90da0f2a5b6),
with the same free login.

**Microsoft Copilot.** GitHub Copilot (including its free plan) adds the remote server once:
`copilot mcp add --transport http finology https://mcp.finology.tech/free`, then signs in with a
Finology Software login the first time it calls a tool; GitHub Copilot in Visual Studio Code uses the
same address and sign-in. In Copilot Studio, add a Model Context Protocol tool with that URL and
OAuth 2.0 Dynamic discovery; running the agent uses your firm's Copilot credits. Setup:
https://finology.tech/finology-software-in-microsoft-copilot/

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

Claude Desktop — add to `claude_desktop_config.json`:

```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, the 2026-27 federal rate per loan type that is sent
when no rate is given (an award-year input, not repayment math), 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](https://finology.tech/?utm_source=mcp&utm_medium=ai_agent)**

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

## License

MIT