Finance MCP Quickstart

Connect your AI assistant to AI2Fin financial data in minutes. This guide covers both OAuth (JWT) and API Key authentication methods for finance MCP integration.

Prerequisites

AI2Fin account (Free or Premium)
Authentication method: JWT token (OAuth) or API Key
Basic understanding of 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

Get your JWT token by logging in:

curl -X POST https://app.ai2fin.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password"
  }'

Response:

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "user": {
      "id": "user-abc-123",
      "email": "[email protected]"
    }
  }
}

Save the token - you’ll need it for all MCP calls!

Step 2: Initialize MCP Connection

curl -X POST https://api.ai2fin.com/mcp \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {}
  }'

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": { "listChanged": false },
      "prompts": { "listChanged": false },
      "resources": { "subscribe": false, "listChanged": false }
    },
    "serverInfo": {
      "name": "ai2fin-mcp",
      "version": "1.0.0"
    },
    "systemPrompt": "You are AI2Fin Assistant..."
  }
}

Step 3: List Available Financial Tools

curl -X POST https://api.ai2fin.com/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'

Response: Returns list of 65+ financial tools (transactions, bills, tax, analytics, etc.)

Step 4: Call a Financial Tool

Example: Get Tax Deductible Expenses

curl -X POST https://api.ai2fin.com/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "get_tax_deductible_summary",
      "arguments": {
        "startDate": "2024-01-01",
        "endDate": "2024-12-31"
      }
    }
  }'

Response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [{
      "type": "json",
      "json": {
        "success": true,
        "data": {
          "totalCount": 23,
          "totalAmount": 4532.67,
          "byCategory": [
            {"category": "Office Supplies", "total": 1234.56, "count": 12},
            {"category": "Travel", "total": 987.43, "count": 8}
          ]
        }
      }
    }]
  }
}

Method 2: API Key - MCP Inspector & Automation

Step 1: Generate API Key

Prerequisites: Authenticated user account (use your JWT token from login)

# User endpoint (recommended - creates key for your account)
curl -X POST https://api.ai2fin.com/api/api-keys \
  -H "Authorization: Bearer <YOUR_JWT_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MCP Inspector - Production",
    "scopes": ["mcp:full"],
    "expiresInDays": 90
  }'

Default Scope: If you don’t specify scopes, it defaults to ["mcp:full"] for full MCP Inspector capability. You can also use specific scopes like ["mcp:read", "mcp:tools:list", "mcp:tools:call"].

Response:

{
  "success": true,
  "data": {
    "id": "key_abc123",
    "name": "MCP Inspector - Production",
    "key": "mcp_a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456",
    "scopes": ["mcp:read", "mcp:tools:list", "mcp:tools:call"],
    "expiresAt": "2024-04-01T00:00:00Z"
  }
}

Save the key value immediately - it’s only shown once during creation!

Step 2: Use API Key with MCP Inspector Endpoint

curl -X POST https://api.ai2fin.com/mcp/inspector \
  -H "X-API-Key: mcp_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {}
  }'

Step 3: Query Financial Data

Example: Get Spending by Category

curl -X POST https://api.ai2fin.com/mcp/inspector \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "get_category_spending_summary",
      "arguments": {
        "startDate": "2024-01-01",
        "endDate": "2024-12-31"
      }
    }
  }'

Response:

{
  "success": true,
  "data": {
    "conversationId": "conv-xyz-789",
    "message": {
      "id": "msg-abc-123",
      "role": "assistant",
      "content": "You have 47 transactions in your account...",
      "metadata": {
        "tokens": 450,
        "duration": 1200
      }
    },
    "toolsUsed": ["get_transactions"]
  }
}

Real-World Financial Queries

Try these common financial queries using MCP tools:

# Get all tax deductible expenses for financial year
curl -X POST https://api.ai2fin.com/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_tax_deductible_summary",
      "arguments": {
        "startDate": "2024-07-01",
        "endDate": "2025-06-30"
      }
    }
  }'

Common Financial Use Cases

Use Case 1: Tax Deduction Analysis

User Intent: “I need to know what expenses are tax deductible”

# Get comprehensive tax deductible summary
curl -X POST https://api.ai2fin.com/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_tax_deductible_summary",
      "arguments": {
        "startDate": "2024-07-01",
        "endDate": "2025-06-30"
      }
    }
  }'

Use Case 2: Spending Analysis

User Intent: “Where does my money go?”

# Get spending breakdown by category
curl -X POST https://api.ai2fin.com/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "get_category_spending_summary",
      "arguments": {
        "startDate": "2024-01-01",
        "endDate": "2024-12-31"
      }
    }
  }'

Use Case 3: Bill Management

User Intent: “What bills are due soon?”

# Get upcoming and overdue bills
curl -X POST https://api.ai2fin.com/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "get_overdue_bills",
      "arguments": {}
    }
  }'

Use Case 4: Receipt Processing

User Intent: “I need to process this receipt”

# Step 1: Analyze receipt image
curl -X POST https://api.ai2fin.com/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "analyze_receipt",
      "arguments": {
        "receiptUrl": "https://example.com/receipt.jpg"
      }
    }
  }'

# Step 2: Create expense from receipt
curl -X POST https://api.ai2fin.com/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
      "name": "commit_receipt",
      "arguments": {
        "receiptUrl": "https://example.com/receipt.jpg",
        "action": {
          "type": "create_expense",
          "merchant": "Office Supplies Co",
          "amount": -45.67,
          "date": "2024-01-15"
        }
      }
    }
  }'

Understanding MCP Responses

Successful Tool Call Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "json",
      "json": {
        "success": true,
        "data": {
          "totalCount": 23,
          "totalAmount": 4532.67,
          "byCategory": [...]
        }
      }
    }]
  }
}

Error Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": 401,
    "message": "Unauthorized",
    "data": {
      "errorType": "INVALID_TOKEN",
      "message": "Invalid or expired authentication token"
    }
  }
}

Write Operation (Requires Confirmation)

For write operations (create, update, delete), you’ll receive a confirmation token:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [{
      "type": "json",
      "json": {
        "ok": false,
        "needsConfirmation": true,
        "confirmToken": "confirm_abc123...",
        "expiresAtMs": 1705320000000,
        "preview": {
          "tool": "create_transaction",
          "arguments": {...}
        }
      }
    }]
  }
}

Then call again with the confirmToken to execute.

Key Features

Conversation Memory

Chat history retained permanently. AI remembers context across messages.

Function Calling

AI automatically calls appropriate tools based on your question.

User Isolated

Your data never mixes with other users. Complete privacy guaranteed.

AI Powered

Advanced AI model for intelligent, accurate responses.

High-Value Financial Queries

Tax & Deduction Queries

User Intent: Maximize tax deductions and prepare for tax seasonMCP Tools:

get_tax_deductible_summary - Complete tax deduction report
analyze_transaction_tax_deductibility - AI analysis of specific transactions
suggest_tax_deductions - Find deduction opportunities
get_bill_pattern_financial_summary - FY summaries for tax reporting

Example Queries:

“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

User Intent: Understand spending patterns and optimize budgetMCP Tools:

get_category_spending_summary - Spending by category
get_top_merchants - Top vendors by spending
compare_spending_periods - Month-over-month comparison
get_spending_analytics - Comprehensive insights

Example Queries:

“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

User Intent: Track and pay recurring bills on timeMCP Tools:

get_upcoming_bills - Bills due soon
get_overdue_bills - Past due bills
mark_bill_as_paid - Record payments
get_bill_pattern_financial_summary - Annual totals

Example Queries:

“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

User Intent: Organize and categorize transactions efficientlyMCP Tools:

trigger_smart_categorization - AI-powered categorization
bulk_categorize_transactions - Batch operations
analyze_transaction_categorization - Get AI suggestions
find_duplicate_transactions - Detect duplicates

Example Queries:

“Categorize all my uncategorized transactions”
“Categorize all Uber rides as Transport”
“Find duplicate transactions”
“What category should this transaction be?”

Rate Limits

OAuth Endpoint (`/mcp`)

Per-user: 200 requests per 15 minutes
Burst: 30 requests
Per-tool limits: Some tools have additional limits (bulk operations, AI analysis)

API Key Endpoint (`/mcp/inspector`)

Per-key: 50 requests per 15 minutes
Burst: 10 requests
Read-only by default (write access requires mcp:full scope)

Rate Limit Headers

All responses include rate limit information:

X-RateLimit-Limit: 200
X-RateLimit-Remaining: 187
X-RateLimit-Reset: 1705320000

Handling Rate Limits

// Exponential backoff retry
async function callWithRetry(fn: () => Promise<any>, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429 && i < retries - 1) {
        const waitTime = Math.pow(2, i) * 1000; // 1s, 2s, 4s
        await new Promise(resolve => setTimeout(resolve, waitTime));
        continue;
      }
      throw error;
    }
  }
}

Common Issues & Solutions

Authentication Errors

Error: 401 Unauthorized or Invalid tokenCauses:

Missing or expired JWT token
Invalid API key
Token/key has been revoked

Solutions:

✅ 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: Bearer or X-API-Key)

Rate Limit Exceeded

Error: 429 Too Many RequestsCauses:

Too many requests in 15-minute window
Per-tool rate limit exceeded

Solutions:

✅ Wait for rate limit window to reset (15 minutes)
✅ Implement exponential backoff retry logic
✅ Use batch operations instead of individual calls
✅ Check X-RateLimit-Reset header for reset time

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

Solutions:

✅ 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

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

Solutions:

✅ Use tools/list to see available tools
✅ Check tool name spelling (case-sensitive)
✅ Verify subscription tier includes the tool
✅ Ensure API key has mcp:tools:call scope

Timeout Errors

Error: Request times out after 20 secondsCauses:

Querying too much data at once
Network connectivity issues
Server under heavy load

Solutions:

✅ 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

Security Model

Understand how data isolation works

Code Examples

Ready-to-use integration code

RAG System

How docs.ai2fin.com knowledge works

Getting Started

Authentication

Tools Reference

Integration

​Finance MCP Quickstart

​Prerequisites

​Authentication Methods

​Method 1: OAuth (JWT Token)

​Step 1: Authenticate

​Step 2: Initialize MCP Connection

​Step 3: List Available Financial Tools

​Step 4: Call a Financial Tool

​Method 2: API Key - MCP Inspector & Automation

​Step 1: Generate API Key

​Step 2: Use API Key with MCP Inspector Endpoint

​Step 3: Query Financial Data

​Real-World Financial Queries

​Common Financial Use Cases

​Use Case 1: Tax Deduction Analysis

​Use Case 2: Spending Analysis

​Use Case 3: Bill Management

​Use Case 4: Receipt Processing

​Understanding MCP Responses

​Successful Tool Call Response

​Error Response

​Write Operation (Requires Confirmation)

​Key Features

Conversation Memory

Function Calling

User Isolated

AI Powered

​High-Value Financial Queries

​Rate Limits

​OAuth Endpoint (/mcp)

​API Key Endpoint (/mcp/inspector)

​Rate Limit Headers

​Handling Rate Limits

​Common Issues & Solutions

​Next Steps

Explore All Tools

Security Model

Code Examples

RAG System

Finance MCP Quickstart

Prerequisites

Authentication Methods

Method 1: OAuth (JWT Token)

Step 1: Authenticate

Step 2: Initialize MCP Connection

Step 3: List Available Financial Tools

Step 4: Call a Financial Tool

Method 2: API Key - MCP Inspector & Automation

Step 1: Generate API Key

Step 2: Use API Key with MCP Inspector Endpoint

Step 3: Query Financial Data

Real-World Financial Queries

Common Financial Use Cases

Use Case 1: Tax Deduction Analysis

Use Case 2: Spending Analysis

Use Case 3: Bill Management

Use Case 4: Receipt Processing

Understanding MCP Responses

Successful Tool Call Response

Error Response

Write Operation (Requires Confirmation)

Key Features

High-Value Financial Queries

Rate Limits

OAuth Endpoint (`/mcp`)

API Key Endpoint (`/mcp/inspector`)

Rate Limit Headers

Handling Rate Limits

Common Issues & Solutions

Next Steps