# FireFolio Planning MCP

Calculate financial independence targets, timelines, life changes, and simulated retirement outcomes using the same engine as the FireFolio website.

Model version: 1.0.0
Endpoint: https://www.firefolio.com/mcp
Transport: Streamable HTTP (JSON responses, no persistent session).

## Connect

1. Add a remote Streamable HTTP MCP server at https://www.firefolio.com/mcp in your AI client.
2. Choose Connect or Authorize. Sign in to FireFolio (or create an account) and approve **Run FIRE calculations**.
3. Your client stores the OAuth credentials and renews access automatically. No personal API key or visit to a developer setup page is needed.

Use a client that supports MCP OAuth, authorization code with PKCE, and CIMD (or DCR if enabled by the service operator). Discovery is public at https://www.firefolio.com/.well-known/oauth-protected-resource/mcp. Clients request `firefolio:calculate` and may request `offline_access` for renewal. The client sends the resulting OAuth access token in its Authorization Bearer header. Browser cookies, session tokens, and API keys do not authorize this endpoint.

Each authorized person has a limit of 1,000 POST requests per UTC day across their connected assistants, including protocol initialization, discovery, notifications, invalid protocol requests, and calculations. Successful responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (Unix seconds). A 429 includes Retry-After. View your usage at https://www.firefolio.com/a/developer. Public OAuth metadata requests do not consume quota.

POST requests must accept both application/json and text/event-stream and use application/json request bodies. The maximum body size is 16 KB. GET and DELETE return 405 because this service has no persistent event stream or session. Native and server clients should omit Origin; browser requests are restricted to the configured site and deployment origins. Public OAuth metadata allows cross-origin discovery.

Missing, invalid, revoked, or expired access tokens return 401 with an OAuth discovery challenge. A valid token without `firefolio:calculate` returns 403 with insufficient_scope. Unavailable authentication or usage storage returns 503; there is no anonymous fallback. Credentials are checked against Clerk's OAuth verification endpoint on every request. Follow your client's reconnect flow when authorization expires or is revoked.

## Vercel Connect

Use an OAuth connection method with this MCP target: https://www.firefolio.com/mcp. Discovery points to FireFolio's Clerk authorization server, which handles sign-in, consent, PKCE, and token renewal. Request the user subject for the person connecting, with `firefolio:calculate` and `offline_access` scopes.

The consuming application obtains an OAuth access token through Connect and sends it to FireFolio. Vercel's OIDC credential authenticates that application to Connect; it does not authorize FireFolio requests. A user's authorized connections share their FireFolio account quota.

See [Vercel's connector guide](https://vercel.com/docs/connect/concepts/connectors) and [authentication guide](https://vercel.com/docs/connect/concepts/authentication).

## Tools

- `calculate_fire_target`: Calculate retirement portfolio targets
- `project_fire`: Project time to financial independence
- `compare_fire_scenario`: Compare a life change with a FIRE plan
- `simulate_fire`: Simulate a FIRE plan through changing markets

Call `tools/list` for complete input schemas. Supply every personal assumption explicitly. Do not invent missing income, savings, spending, or expected returns. All monetary inputs are USD in today's dollars. Rates are annual percentages: 5 means 5%.

## Example: project a FIRE plan

Illustrative inputs, not a recommended plan:

```json
{
  "name": "project_fire",
  "arguments": {
    "currentSavings": 100000,
    "monthlyInvestment": 2000,
    "annualSpending": 40000,
    "annualReturn": 5,
    "retirementReturn": 4,
    "retirementYears": 40,
    "legacy": 0,
    "otherIncome": 0,
    "otherIncomeStartsAfter": 0,
    "volatility": 12
  }
}
```

Use the same plan with `simulate_fire` as `{"plan": {...}, "paths": 2000, "seed": 42}`. For `calculate_fire_target`, omit currentSavings, monthlyInvestment, and annualReturn.

## Example: compare a lower-paid job

```json
{
  "name": "compare_fire_scenario",
  "arguments": {
    "plan": {
      "currentSavings": 35000,
      "monthlyInvestment": 1200,
      "annualSpending": 33600,
      "annualReturn": 5,
      "retirementReturn": 4,
      "retirementYears": 40,
      "legacy": 0,
      "otherIncome": 0,
      "otherIncomeStartsAfter": 0,
      "volatility": 12
    },
    "monthlyTakeHome": 4800,
    "monthlyLivingCosts": 2800,
    "cashSavings": 15000,
    "protectedCash": 10000,
    "change": {
      "kind": "job",
      "startInMonths": 12,
      "monthlyTakeHome": 3800
    }
  }
}
```

The comparison also supports a `break` change with startInMonths and durationMonths, or a `contribution` change with startInMonths and monthlyInvestment. Current spending plus investing must fit take-home pay. Lower-paid job income cannot exceed current income. A career break must end within the 600-month horizon. Check fundingCovered, cashShortfall, and monthlyGap before calling a scenario funded.

## Methodology

- Amounts are USD in today’s dollars. Returns are annual percentages after inflation; 5 means 5%, not 0.05.
- The target uses 2,000 lognormal annual-return paths, seed 42, and a 90% modeled retirement survival threshold. This is not a real-world probability or a guarantee.
- Retirement withdrawals occur at the beginning of each year. Other income reduces withdrawals only after its specified start; excess income is not reinvested.
- The steady target assumes constant retirement returns. The 4% reference is annual spending divided by 0.04, before other income.
- Taxes, fees, changing spending, correlations, and historical market sequences are not modeled. Treat spending and other income as net amounts.
- Accumulation uses constant real returns and month-end contributions, with a 600-month horizon.
- months = null means the target is not reached within 50 years; months = 0 means it is already reached. Neither is a retirement recommendation.

The target engine transforms the arithmetic mean and standard deviation of annual simple returns into a lognormal gross-return distribution. It calculates the starting balance needed for each of 2,000 seeded retirement paths and takes the 90th-percentile requirement. Other income offsets spending after its start date. It never creates a negative portfolio withdrawal.

The Monte Carlo tool uses independent annual return draws. It retires at the steady projection's first target crossing rounded up to a full year; when no crossing exists, it uses year 50 and returns projectedRetirementReached=false. It does not choose a separate retirement date for each simulated path. Contributions are aggregated at each saving year's end, whereas the steady projection contributes monthly. Retirement spending occurs before that year's return.

successRate is the fraction of paths that cover every withdrawal and leave the requested legacy. targetRate is the fraction reaching the target on the fixed retirement date. Both range from 0 to 1. Annual low, median, and high balances are pointwise 10th, 50th, and 90th percentiles, not individual trajectories. The simulation accepts 100–2,000 paths and an unsigned 32-bit seed; defaults are 2,000 and 42. The target engine always uses its own fixed 2,000 paths and seed 42.

Results include modelVersion, validated input, assumptions, methodologyUrl, and calculatorUrl in structuredContent and a matching JSON text block. Projection and simulation links open the exact plan in the website's simple FIRE calculator. The link stores inputs in the URL fragment, which browsers do not send in HTTP requests; anyone given the full link can read those inputs. Target and life-change results link to their corresponding calculators without prefilled inputs.

## Reference cases

- With zero return and volatility, $10/year spending for 10 retirement years and no legacy or other income requires exactly $100. A $100 starting portfolio can fund those withdrawals and finish at zero.
- With those same assumptions, starting at $0 and contributing $1/month reaches the $100 target in 100 months.
- If other income covers all spending from retirement year zero and no legacy is requested, the target is zero and the projection reports zero months.
- If savings and contributions are zero while spending is positive and other income is zero, the projection reports null months.

These cases are checked alongside website/MCP parity and protocol tests. Reproducibility describes the model, not future markets. This version does not model tax rules, fees, changing spending, historical sequences, or the advanced Paycheck planner. Results are planning illustrations, not recommendations to retire or trade.

## Data boundaries

Tools calculate from supplied inputs. They do not read saved portfolios, broker connections, or personal plans, and do not save results or execute trades. The service must not log tool arguments or result bodies. Do not include names, account numbers, or unrelated personal information in calculation inputs.

Website: https://www.firefolio.com/calculators/fire
Terms: https://www.firefolio.com/terms
Privacy: https://www.firefolio.com/privacy