Prerequisites
- An AI2Fin account (Free or Premium)
- An authentication method: OAuth (bearer token) or an API key
- Basic familiarity with REST APIs and JSON-RPC 2.0
Authentication Methods
- OAuth (JWT Token)
- API Key
For OAuth-based integrations
Method 1: OAuth (JWT Token)
Step 1: Authenticate
Connect your AI assistant using OAuth. After you authorize AI2Fin, your assistant receives a bearer token it uses for all MCP calls. For scripted or server-to-server access, generate an API key instead and skip to Method 2.Step 2: Initialize MCP Connection
Step 3: List Available Financial Tools
title, readOnlyHint and destructiveHint annotations so a client can tell read tools from write tools.
Step 4: Call a Financial Tool
Example: Get Tax Deductible Expensesperiod presets (this_month, last_month, this_quarter, this_fy, last_fy, ytd, and so on) save you computing date bounds; pass startDate and endDate instead for a custom range.
Response:
Method 2: API Key - MCP Inspector & Automation
Step 1: Generate API Key
The simplest way is to create a key from your AI2Fin dashboard. You can also create one programmatically with an authenticated request:Step 2: Use API Key with MCP Inspector Endpoint
Step 3: Query Financial Data
Example: Get Spending by CategoryReal-World Financial Queries
Try these common financial queries using MCP tools:Common Financial Use Cases
Use Case 1: Tax Deduction Analysis
User Intent: “I need to know what expenses are tax deductible”Use Case 2: Spending Analysis
User Intent: “Where does my money go?”Use Case 3: Bill Management
User Intent: “What bills are due soon?”Use Case 4: Receipt Processing
User Intent: “I need to process this receipt” One call withmode: "smart" extracts the fields, matches a bill and creates the transaction. Use the two-step analyze_only then commit flow when the user should confirm the extracted fields first:
Understanding MCP Responses
Successful Tool Call Response
Error Response
Write Operation (Requires Confirmation)
For write operations (create, update, delete), clients other than Meta Muse (which asks the user itself before each write) receive a confirmation token first, so nothing changes until the call is repeated with it:confirmToken to execute. A token that has expired, been reused, or whose arguments changed fails with 403 confirmation_required.
Key Features
Conversation Memory
Your assistant remembers context across messages for natural follow-up questions. You control your data and can delete it any time.
Function Calling
Your assistant automatically calls the right tools based on your question.
Account Isolated
Your data is scoped to your account only and is never shared with other users.
AI Powered
Intelligent, accurate answers grounded in your real financial data.
High-Value Financial Queries
Tax & Deduction Queries
Tax & Deduction Queries
User Intent: Maximize tax deductions and prepare for tax seasonMCP Tools:
get_tax_summary- Complete tax deduction reportanalyze_transactions(action: "tax") - AI analysis of specific transactionsget_suggestions(type: "tax_deductions") - Find deduction opportunitiesquery_bills(view: "financial") - FY summaries for tax reporting
- “Show all tax deductible expenses this financial year”
- “What percentage of my expenses are tax deductible?”
- “Which categories have the most tax deductions?”
- “Am I missing any potential tax deductions?”
Spending Analysis
Spending Analysis
User Intent: Understand spending patterns and optimize budgetMCP Tools:
analyze_spending(view: "by_category") - Spending by categoryanalyze_spending(view: "top_merchants") - Top vendors by spendinganalyze_spending(view: "compare_periods") - Month-over-month comparisonanalyze_spending(view: "analytics") - Comprehensive insights with flexible filters
- “What’s my biggest expense category this month?”
- “How much did I spend on groceries vs dining out?”
- “Did I spend more this month than last month?”
- “Where do I spend the most money?”
Bill Management
Bill Management
User Intent: Track and pay recurring bills on timeMCP Tools:
query_bills(view: "upcoming") - Bills due soonquery_bills(view: "overdue") - Past due billsmanage_bill_payment(action: "pay") - Record paymentsget_upcoming_money- Everything due in and out over the next fortnight
- “What bills are due this week?”
- “Do I have any overdue bills?”
- “How much do I spend on bills monthly?”
- “Mark Netflix as paid for this month”
Transaction Organization
Transaction Organization
User Intent: Organize and categorize transactions efficientlyMCP Tools:
modify_transactions(action: "categorize") - Batch categorisation by merchant or IDanalyze_transactions(action: "categorize") - Get AI suggestionsanalyze_transactions(action: "find_duplicates") - Detect duplicatesquery_rules/manage_rule- Automate it with a rule
- “Categorize all my uncategorized transactions”
- “Categorize all Uber rides as Transport”
- “Find duplicate transactions”
- “What category should this transaction be?”
Rate Limits
Both MCP endpoints are rate limited to keep the service fast and fair for everyone. Some heavier operations (such as bulk actions and AI analysis) have their own limits. On the API key endpoint, write tools need a key with themcp:tools:call or mcp:full scope; a key limited to mcp:read and mcp:tools:list can only read.
If you exceed a limit you’ll receive a 429 Too Many Requests response. Wait for the window to reset and retry with exponential backoff.
Rate Limit Headers
All responses include rate limit information so you can pace your requests:Handling Rate Limits
Common Issues & Solutions
Authentication Errors
Authentication Errors
Error:
401 Unauthorized or Invalid tokenCauses:- Missing or expired JWT token
- Invalid API key
- Token/key has been revoked
- ✅ Re-authenticate and get new token
- ✅ Check token expiration time
- ✅ Verify API key hasn’t been revoked
- ✅ Ensure token/key is in correct header (
Authorization: BearerorX-API-Key)
Rate Limit Exceeded
Rate Limit Exceeded
Error:
429 Too Many RequestsCauses:- Too many requests in 15-minute window
- Per-tool rate limit exceeded
- ✅ Wait for rate limit window to reset (15 minutes)
- ✅ Implement exponential backoff retry logic
- ✅ Use batch operations instead of individual calls
- ✅ Check
X-RateLimit-Resetheader for reset time
Invalid Request Format
Invalid Request Format
Error:
400 Bad Request or -32600 Invalid RequestCauses:- Missing required JSON-RPC fields (
jsonrpc,id,method) - Invalid tool parameters
- Missing required tool arguments
- ✅ Ensure request follows JSON-RPC 2.0 format
- ✅ Check tool parameter requirements
- ✅ Validate all required fields are present
- ✅ Review tool documentation for correct parameter types
Tool Not Found
Tool Not Found
Error:
-32601 Method not found or tool execution failsCauses:- Tool name misspelled
- Tool not available for your subscription tier
- API key doesn’t have required scope
- ✅ Use
tools/listto see available tools - ✅ Check tool name spelling (case-sensitive)
- ✅ Verify subscription tier includes the tool
- ✅ Ensure API key has
mcp:tools:callscope
Timeout Errors
Timeout Errors
Error: Request times outCauses:
- Querying too much data at once
- Network connectivity issues
- Server under heavy load
- ✅ Use summary tools instead of fetching all data
- ✅ Add date filters to limit scope
- ✅ Use pagination for large datasets
- ✅ Check network connectivity
- ✅ Retry with exponential backoff
Next Steps
Explore All Tools
See complete tool reference with parameters
Authentication and scopes
OAuth, API keys and how data isolation works
Code Examples
Ready-to-use integration code
Connector reference
Scopes, confirmation flow, errors and rate limits
