Fi MCP Documentation

Overview

The Fi MCP (Model Context Protocol) provides access to comprehensive financial data for users of the Fi Money platform. This MCP enables developers to build applications that can analyze users’ financial health, provide insights, and create personalized financial recommendations based on real account data.

Available Tools

1. fetch_net_worth

Purpose: Calculate comprehensive net worth using actual data from connected accounts

Use Cases:

• Portfolio analysis and asset allocation insights
• Net worth tracking and visualization
• Financial health assessments
• Investment performance analysis
• Debt-to-asset ratio calculations

Data Sources:

• Bank account balances
• Mutual fund holdings and current values
• Indian stock portfolio holdings
• US stock investments (if invested through Fi Money app)
• EPF account balances
• Credit card debt and loan balances
• Other connected assets/liabilities

Sample response

Error Handling:

• Returns empty result if no financial accounts are connected
• Prompts users to connect mutual fund accounts if not detected
• Only includes data from connected accounts (no estimations)

---

2. fetch_credit_report

Purpose: Retrieve comprehensive credit report information

Use Cases:

• Credit score monitoring
• Loan prioritization based on interest rates
• Credit utilization analysis

Data Included:

• Credit scores
• Active, closed loan details with interest rates
• Credit card utilization rates
• Recent credit inquiries
• Date of birth information

Sample response

Error Handling:

• Returns “No credit score data available” if not connected
• Prompts users to connect credit profile in Fi Money app

---

3. fetch_epf_details

Purpose: Access Employee Provident Fund account information

Use Cases:

• Retirement planning calculations
• EPF contribution tracking
• Interest earned analysis
• Employer contribution verification

Data Included:

• Current account balance
• Employer and employment details
• Total Employee contribution
• Total Employer contribution

Sample response

Error Handling:

• Directs users to link EPF account through Fi Money app if not connected

---

4. fetch_mf_transactions

Purpose: Retrieve mutual funds transaction history for portfolio analysis

Use Cases:

• XIRR (Extended Internal Rate of Return) calculations
• Investment performance tracking
• Transaction pattern analysis
• Portfolio rebalancing insights

Current Scope:

• Mutual fund transactions (buy, sell, SIP, etc.)
• Transaction dates and amounts
• Fund-wise transaction history

Sample response

Notes on Response Structure:

• purchasePrice: NAV at which transaction was executed
• transactionAmount: Total amount invested/redeemed
• transactionUnits: Number of units bought/sold
• transactionMode: “N” for Normal, other modes may include SIP, etc.
• externalOrderType: “BUY” for purchases, “SELL” for redemptions
• Amounts use units (main amount) and nanos (fractional part) structure
• XIRR calculation needs to be done separately using this transaction data

Error Handling:

• Returns available data with clear indication of limitations
• Specifies which transaction types are not included
• SIP performance evaluator

5. fetch_bank_transactions

Purpose: Access bank transactions data connected to Fi Money app

Use Cases:

• All bank transactions data connected to Fi Money app

Data Included:

• Transaction amount
• Narration of transactions
• Transaction date
• Current balance post transaction

Sample response

---

6. fetch_stock_transactions

Purpose: Access stock transaction from account connected to Fi Money app

Use Cases:

• All stock transactions connected

Data Included:

• ISIN as identifier of transactions
• Transaction type (Buy, Sell, Dividend)
• Transaction date
• Nav value of transaction

Sample response

---

Integration Guidelines

Error Handling Best Practices

1. Connection Status: Always check if required accounts are connected before displaying data
2. Data Availability: Handle cases where specific data types may not be available
3. User Guidance: Provide clear instructions on how to connect missing accounts
4. Graceful Degradation: Design UI to work with partial data when some accounts aren’t connected

Security Considerations

1. Data Privacy: Never store or cache sensitive financial data
2. Authentication: Ensure proper user authentication before accessing MCP
3. Data Display: Use appropriate formatting for financial data display

Performance Optimization

1. Batch Processing: Group related MCP calls when possible
2. Error Recovery: Implement retry mechanisms for failed calls

How to create the MCP Client

Simplest Python MCP client for connecting to server

from mcp.client.streamable_http import streamablehttp_client
from mcp.client.session import ClientSession
import asyncio
 
async def main():
    try:
        async with streamablehttp_client("https://mcp.fi.money:8080/mcp/stream") as (
            read_stream,
            write_stream,
            _,
        ):
            async with ClientSession(
                read_stream,
                write_stream,
            ) as session:
                await session.initialize()
                tools = await session.list_tools()
                print(tools)
    except Exception as e:
        print(f"error: {e}")

if __name__ == "__main__":
    asyncio.run(main())

Sample Integration Code

Basic Net Worth Fetch

Javascript snippet

async function getUserNetWorth() {
  try {
    const response = await mcp.call('networth:fetch_net_worth');
    if (response.netWorthResponse && response.netWorthResponse.totalNetWorthValue) {
      const totalValue = response.netWorthResponse.totalNetWorthValue.units;
      const assets = response.netWorthResponse.assetValues;
      displayNetWorth(totalValue, assets);
    } else {
      promptAccountConnection();
    }
  } catch (error) {
    handleError(error);
  }
}

Credit Score Monitoring

Javascript snippet

async function getCreditInsights() {
  try {
    const response = await mcp.call('networth:fetch_credit_report');
    if (response.creditReports && response.creditReports.length > 0) {
      const creditData = response.creditReports[0].creditReportData;
      const score = creditData.score.bureauScore;
      const dateOfBirth = creditData.currentApplication.currentApplicationDetails.currentApplicantDetails.dateOfBirthApplicant;
      const accounts = creditData.creditAccount.creditAccountDetails;
      
      analyzeCreditScore(score, dateOfBirth, accounts);
    } else {
      promptCreditConnection();
    }
  } catch (error) {
    showCreditError();
  }
}

EPF Balance Tracking

Javascript snippet

async function getEPFDetails() {
  try {
    const response = await mcp.call('networth:fetch_epf_details');
    if (response.uanAccounts && response.uanAccounts.length > 0) {
      const epfData = response.uanAccounts[0].rawDetails;
      const totalBalance = epfData.overall_pf_balance.current_pf_balance;
      const employeeShare = epfData.overall_pf_balance.employee_share_total.balance;
      const employerShare = epfData.overall_pf_balance.employer_share_total.balance;
      
      displayEPFBreakdown(totalBalance, employeeShare, employerShare);
    } else {
      promptEPFConnection();
    }
  } catch (error) {
    handleEPFError();
  }
}

Mutual Fund XIRR Calculation

Javascript snippet

async function calculatePortfolioXIRR() {
  try {
    const response = await mcp.call('networth:fetch_mf_transactions');
    if (response.transactions && response.transactions.length > 0) {
      const transactions = response.transactions;
      
      // Group transactions by scheme
      const groupedTransactions = transactions.reduce((acc, tx) => {
        if (!acc[tx.isinNumber]) {
          acc[tx.isinNumber] = [];
        }
        acc[tx.isinNumber].push({
          date: new Date(tx.transactionDate),
          amount: parseFloat(tx.transactionAmount.units) + 
                 (tx.transactionAmount.nanos / 1000000000),
          type: tx.externalOrderType
        });
        return acc;
      }, {});
      
      // Calculate XIRR for each scheme
      calculateXIRRByScheme(groupedTransactions);
    } else {
      showNoTransactionsMessage();
    }
  } catch (error) {
    handleTransactionError();
  }
}

Key Data Structure Notes

Currency Format

All monetary values in the API use the following structure:

{
  "currencyCode": "INR",
  "units": "string_value",
  "nanos": "numeric_fractional_value"
}

• units: Main currency amount as string
• nanos: Fractional part (1 nano = 1/1,000,000,000 of a unit)
• To get actual value: parseFloat(units) + (nanos / 1000000000)

Asset Type Mapping

• ASSET_TYPE_EPF: Employee Provident Fund balance
• ASSET_TYPE_INDIAN_SECURITIES: Indian stock holdings
• ASSET_TYPE_SAVINGS_ACCOUNTS: Bank account balances
• ASSET_TYPE_MUTUAL_FUND: Mutual fund portfolio value
• ASSET_TYPE_US_SECURITIES: US stock investments

Credit Account Types

• Account Type “10”: Credit Card accounts
• Account Status “11”: Active accounts
• Payment Rating “0”: Current (no delays)

Date Formats

• EPF dates: “DD-MM-YYYY” format
• Transaction dates: ISO 8601 format (“YYYY-MM-DDTHH:MM:SSZ”)
• Credit report dates: “YYYYMMDD” format

---

Common Issues

• Partial Data: Some tools may return limited data based on the accounts user has currently connected
• Authentication Errors: Ensure proper MCP authentication and permissions

Best Practices

• Provide clear error messages with actionable steps
• Implement proper loading states for async operations

Getting Help

• Check error messages for specific guidance
• Test with different account connection scenarios

---

This documentation covers the current version of the Fi MCP. Features and capabilities may be expanded in future versions.