Skip to content

epiFi/mcp-docs

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

5 Commits
.idea
.idea
 
 
sample_responses
sample_responses
 
 
README.md
README.md
 
 

Repository files navigation

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
Response Format 
{
  "netWorthResponse": {
    "totalNetWorthValue": {
      "currencyCode": "string" // e.g. INR
      "units": "string" // e.g. total net worth amount
    },
    "assetValues": [
      {
        "netWorthAttribute": "string" // e.g. ASSET_TYPE_EPF
        "value": {
          "currencyCode": "string" // e.g. INR
          "units": "string" // e.g. individual asset value
        }
      }
      // Only one sample asset shown
    ]
  },
  "mfSchemeAnalytics": {
    "schemeAnalytics": [
      {
        "schemeDetail": {
          "amc": "string" // e.g. QUANT_MONEY_MANAGERS
          "nameData": {
            "longName": "string" // e.g. fund name
          },
          "planType": "string" // e.g. DIRECT
          "investmentType": "string" // e.g. OPEN
          "optionType": "string" // e.g. GROWTH
          "nav": {
            "currencyCode": "string" // e.g. INR
            "units": "string" // e.g. NAV whole part
            "nanos": "number" // e.g. NAV fractional part
          },
          "assetClass": "string" // e.g. EQUITY
          "isinNumber": "string" // e.g. INF123L01234
          "categoryName": "string" // e.g. ELSS_TAX_SAVING
          "fundhouseDefinedRiskLevel": "string" // e.g. VERY_HIGH_RISK
        },
        "enrichedAnalytics": {
          "analytics": {
            "schemeDetails": {
              "currentValue": {
                "currencyCode": "string"
                "units": "string"
                "nanos": "number"
              },
              "investedValue": {
                "currencyCode": "string"
                "units": "string"
                "nanos": "number"
              },
              "XIRR": "number" // e.g. % return
              "absoluteReturns": {
                "currencyCode": "string"
                "units": "string"
                "nanos": "number"
              },
              "unrealisedReturns": {
                "currencyCode": "string"
                "units": "string"
                "nanos": "number"
              },
              "navValue": {
                "currencyCode": "string"
                "units": "string"
                "nanos": "number"
              },
              "units": "number" // e.g. 123.01
            }
          }
        }
      }
    ]
  },
  "accountDetailsBulkResponse": {
    "accountDetailsMap": {
      "accountId": {
        "accountDetails": {
          "fipId": "string" // e.g. KotakMahindraBank-FIP
          "maskedAccountNumber": "string" // e.g. XXXXXX1234
          "accInstrumentType": "string" // e.g. ACC_INSTRUMENT_TYPE_DEPOSIT
          "ifscCode": "string" // e.g. ABCD0000123
          "accountType": {
            "depositAccountType": "string" // e.g. DEPOSIT_ACCOUNT_TYPE_SAVINGS
          },
          "fipMeta": {
            "name": "string" // e.g. Kotak Mahindra Bank
            "displayName": "string" // e.g. Kotak
            "bank": "string" // e.g. KOTAK
          }
        },
        "depositSummary": {
          "accountId": "string"
          "currentBalance": {
            "currencyCode": "string"
            "units": "string"
            "nanos": "number"
          },
          "balanceDate": "ISODate" // e.g. 2025-01-01T11:59:59.149Z
          "depositAccountType": "string"
          "branch": "string"
          "ifscCode": "string"
          "openingDate": "ISODate"
          "depositAccountStatus": "string"
        },
        "equitySummary": {
          "accountId": "string"
          "currentValue": {
            "currencyCode": "string"
            "units": "string"
            "nanos": "number"
          },
          "holdingsInfo": [
            {
              "isin": "string" // e.g. INE00H001014
              "issuerName": "string" // e.g. EPIFI LIMITED
              "type": "string" // e.g. EQUITY_HOLDING_TYPE_DEMAT
              "units": "number" // e.g. quantity held
              "lastTradedPrice": {
                "currencyCode": "string"
                "units": "string"
                "nanos": "number"
              },
              "isinDescription": "string" // e.g. EPIFI LIMITED-EQ
            }
          ]
        }
      }
    }
  }
}

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
Response Format 
{
  "creditReports": [
    {
      "creditReportData": {
        "userMessage": {
          "userMessageText": "string" // e.g. Normal Response
        },
        "creditProfileHeader": {
          "reportDate": "string" // e.g. 20250101
          "reportTime": "string" // e.g. 235959
        },
        "currentApplication": {
          "currentApplicationDetails": {
            "enquiryReason": "string" // e.g. 6
            "amountFinanced": "string" // e.g. 0
            "durationOfAgreement": "string" // e.g. 0
            "currentApplicantDetails": {
              "dateOfBirthApplicant": "string" // e.g. 19690131
            }
          }
        },
        "creditAccount": {
          "creditAccountSummary": {
            "account": {
              "creditAccountTotal": "string" // e.g. 2
              "creditAccountActive": "string" // e.g. 2
              "creditAccountDefault": "string" // e.g. 0
              "creditAccountClosed": "string" // e.g. 0
              "cadSuitFiledCurrentBalance": "string" // e.g. 0
            },
            "totalOutstandingBalance": {
              "outstandingBalanceSecured": "string" // e.g. 10000
              "outstandingBalanceSecuredPercentage": "string" // e.g. 20
              "outstandingBalanceUnSecured": "string" // e.g. 40000
              "outstandingBalanceUnSecuredPercentage": "string" // e.g. 80
              "outstandingBalanceAll": "string" // e.g. 50000
            }
          },
          "creditAccountDetails": [
            {
              "identificationNumber": "string" // e.g. AV12345678
              "subscriberName": "string" // e.g. Federal Bank
              "portfolioType": "string" // e.g. R
              "accountType": "string" // e.g. 10
              "openDate": "string" // e.g. 20250101
              "creditLimitAmount": "string" // e.g. 500000
              "highestCreditOrOriginalLoanAmount": "string" // e.g. 80000
              "accountStatus": "string" // e.g. 11
              "paymentRating": "string" // e.g. 0
              "paymentHistoryProfile": "string" // e.g. 000000000000000000000000?00000000000
              "currentBalance": "string" // e.g. 0
              "amountPastDue": "string" // e.g. 0
              "dateReported": "string" // e.g. 20250701
              "dateOfLastPayment": "string" // e.g. 20250701
              "repaymentTenure": "string" // e.g. 0
              "dateOfAddition": "string" // e.g. 20220101
              "currencyCode": "string" // e.g. INR
              "accountHolderTypeCode": "string" // e.g. 1
            }
          ]
        },
        "matchResult": {
          "exactMatch": "string" // e.g. Y
        },
        "totalCapsSummary": {
          "totalCapsLast7Days": "string" // e.g. 0
          "totalCapsLast30Days": "string" // e.g. 0
          "totalCapsLast90Days": "string" // e.g. 0
          "totalCapsLast180Days": "string" // e.g. 0
        },
        "nonCreditCaps": {
          "nonCreditCapsSummary": {
            "nonCreditCapsLast7Days": "string" // e.g. 0
            "nonCreditCapsLast30Days": "string" // e.g. 0
            "nonCreditCapsLast90Days": "string" // e.g. 0
            "nonCreditCapsLast180Days": "string" // e.g. 0
          }
        },
        "score": {
          "bureauScore": "string" // e.g. 800
        },
        "caps": {
          "capsSummary": {
            "capsLast7Days": "string" // e.g. 0
            "capsLast30Days": "string" // e.g. 0
            "capsLast90Days": "string" // e.g. 0
            "capsLast180Days": "string" // e.g. 0
          },
        }
      },
      "vendor": "EXPERIAN"
    }
  ]
}

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
Response Format 
{
  "uanAccounts": [
    {
      "phoneNumber": {}, // object (structure not specified)
      "rawDetails": {
        "est_details": [
          {
            "est_name": "string", // e.g. Company Name
            "member_id": "string", // e.g. RJRAJ12345690000012345
            "office": "string", // e.g. (RO)JAIPUR
            "doj_epf": "string", // e.g. 01-01-2020
            "doe_epf": "string", // e.g. 01-01-2025
            "doe_eps": "string", // e.g. 01-01-2025
            "pf_balance": {
              "is_pf_full_withdrawn": true, // boolean
              "employee_share": {
                "debit": "string", // e.g. 12345
                "credit": "string" // e.g. 12345
              },
              "employer_share": {
                "debit": "string", // e.g. 1234
                "credit": "string" // e.g. 1234
              }
            }
          },
         "overall_pf_balance": {
          "pension_balance": "string", // e.g. 12345
          "current_pf_balance": "string", // e.g. 54321
          "employee_share_total": {
            "debit": "string", // e.g. 12345
            "credit": "string", // e.g. 54321
            "balance": "string" // e.g. 12345
          },
          "employer_share_total": {
            "debit": "string", // e.g. 1234
            "credit": "string", // e.g. 12345
            "balance": "string" // e.g. 123456
          }
        }
      }
    }
  ]
}

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
Response Format 
{
  "transactions": [
    {
      "isinNumber": "string", // e.g. INF123L01234
      "folioId": "string", // e.g. 1234567890
      "externalOrderType": "string", // e.g. BUY
      "transactionDate": "string", // e.g. 2025-01-01T23:59:59Z (ISO format)
      "purchasePrice": {
        "currencyCode": "string", // e.g. INR
        "units": "string", // e.g. 250
        "nanos": "number" // e.g. 785200000
      },
      "transactionAmount": {
        "currencyCode": "string", // e.g. INR
        "units": "string", // e.g. 9999
        "nanos": "number" // e.g. 500000000
      },
      "transactionUnits": "number", // e.g. 98.765
      "transactionMode": "string", // e.g. N
      "schemeName": "string", // e.g. Epifi Tax Saver Fund - Direct Plan
      "stampDuty": "number" // e.g. 0.1
    }
  ]
}

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
Response Format 
{
  "schemaDescription": "A list of bank transactions. Each 'txns' field is a list of data arrays with schema: [transactionAmount, transactionNarration, transactionDate, transactionType (1 for CREDIT, 2 for DEBIT, 3 for OPENING, 4 for INTEREST, 5 for TDS, 6 for INSTALLMENT, 7 for CLOSING and 8 for OTHERS), transactionMode, currentBalance].\n We currently have have only last two month transaction, older transaction are coming soon...",
  "bankTransactions": [
    {
      "bank": "HDFC Bank",
      "txns": [
        [
          "80085",
          "UPI-SHEETAL RAVINDRA DA-SHEETAL.DAMBAL@OKSBI-SBIN0010411-109209224698-SUFYAN",
          "2025-07-09",
          1,
          "CARD_PAYMENT",
          "-79109"
        ],
        [
          "80677",
          "UPI-DREAMPLUG TECHNOLOGI-CRED@AXISB-UTIB0000114-009400589368-CREDIT CARD BILL P",
          "2025-07-09",
          2,
          "FT",
          "1568"
        ]
      ]
    }
  ]
}

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
Response Format 
{
  "schemaDescription": "A list of stock transactions. Each 'txns' field is a list of data arrays with schema: [transactionType (1 for BUY, 2 for SELL, 3 for BONUS, 4 for SPLIT), transactionDate, quantity, navValue]. nav value may not be present in some of the transactions",
  "stockTransactions": [
    {
      "isin": "INE0BWS23018",
      "txns": [
        [
          1,
          "2023-05-04",
          100
        ],
        [
          1,
          "2023-05-04",
          170
        ]
      ]
    },
    {
      "isin": "INF204KB14I5",
      "txns": [
        [
          1,
          "2023-05-04",
          100,
          10.51
        ]
      ]
    }
  ]
}

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.

About

This repository has documentation for the Fi MCP server

Resources

Readme
Activity
Custom properties

Stars

16 stars

Watchers

0 watching

Forks

9 forks
Report repository

Releases

No releases published

Packages

No packages published

Contributors 3

  •  
  •  
  •