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

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.

Most AI clients (Claude, Cursor, and others) handle the OAuth flow for you—just add the MCP server URL and approve access. Save your token or API key securely; you’ll need it for every MCP call.

Step 2: Initialize MCP Connection

curl -X POST https://api.ai2fin.com/mcp \
  -H "Authorization: Bearer <your_oauth_token>" \
  -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"
    }
  }
}

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

The simplest way is to create a key from your AI2Fin dashboard. You can also create one programmatically with an authenticated request:

# Creates an API key for your account
curl -X POST https://api.ai2fin.com/api/api-keys \
  -H "Authorization: Bearer <your_oauth_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": {
        "assetUrl": "https://example.com/receipt.jpg",
        "mimeType": "image/jpeg",
        "size": 245123
      }
    }
  }'

# 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": {
        "assetUrl": "https://example.com/receipt.jpg",
        "mimeType": "image/jpeg",
        "size": 245123,
        "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

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

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

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. The API key endpoint is read-only by default—write access requires the mcp:full scope. 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:

X-RateLimit-Limit: <limit>
X-RateLimit-Remaining: <remaining>
X-RateLimit-Reset: <reset-timestamp>

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 outCauses:

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

​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

Account Isolated

AI Powered

​High-Value Financial Queries

​Rate Limits

​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

Rate Limit Headers

Handling Rate Limits

Common Issues & Solutions

Next Steps