← Back to Documentation Hub

Banking Tools Reference

Available banking operations via Model Context Protocol (MCP)

MCP Integration

Protocol: JSON-RPC 2.0 over Server-Sent Events

SSE Endpoint: /mcp/sse

Methods: tools/list, tools/call

Authentication: JWT in Authorization header (from httpOnly cookie via Agent), integration in X-Bancony-Integration

Note: User tokens are stored in httpOnly cookies for security. The Agent reads the cookie and forwards the token to MCP Server via headers.

Tools (11)

get-accounts

Get bank accounts and cards. Returns a list of accounts with balances, account numbers, and types.

Parameters

only_withdrawal_accounts (boolean, default: False) optional
Filter to only withdrawal-capable accounts
account_type (string) optional
Filter by account type
Allowed values: Current Savings Credit

Example Request

{ "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "get-accounts", "arguments": { "only_withdrawal_accounts": false, "account_type": "Current" } }, "id": 1 }

transactions

Get bank transactions. Returns a list of transactions with amounts, dates, descriptions, and categories.

Parameters

count (integer) optional
Maximum number of transactions to return
type (string, default: Any) optional
Transaction type filter
Allowed values: Any Income Expenses Savings
order (string, default: NewestFirst) optional
Sort order for transactions
Allowed values: NewestFirst OldestFirst
start_date (string) optional
Start date filter (ISO format: YYYY-MM-DD)
end_date (string) optional
End date filter (ISO format: YYYY-MM-DD)
description (string) optional
Search text to filter transactions by description

Example Request

{ "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "transactions", "arguments": { "count": 10, "type": "Any" } }, "id": 1 }

recipients-by-name

Lookup recipient of a payment or transfer by name. Returns matching recipients with their account details.

Parameters

name (string) required
Name to search for

Example Request

{ "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "recipients-by-name", "arguments": { "name": "example_name" } }, "id": 1 }

transfer-money-icelandic

Prepare an Icelandic domestic money transfer. Validates recipient and prepares transfer details for confirmation.

Parameters

amount (number) required
Amount to transfer
recipient_ssn (string) required
Recipient's social security number (kennitala)
recipient_account_number (string) required
Recipient's bank account number
description (string, default: ) optional
Transfer description/reference
withdrawal_account_number (string, default: ) optional
Account to withdraw from (uses default if not specified)
currency (string, default: ) optional
Currency code

Example Request

{ "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "transfer-money-icelandic", "arguments": { "amount": 10, "recipient_ssn": "example_recipient_ssn", "recipient_account_number": "example_recipient_account_number" } }, "id": 1 }

execute-transfer

Execute a money transfer after the user has confirmed the details. Use transfer-money-icelandic first to prepare and validate, then call this tool once the user approves.

Parameters

withdrawal_account_id (string) required
Source account ID to withdraw from
recipient_account_number (string) required
Destination account number
amount (number) required
Amount to transfer in ISK
description (string, default: Millifærsla) optional
Transfer description/reference

Example Request

{ "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "execute-transfer", "arguments": { "withdrawal_account_id": "example_withdrawal_account_id", "recipient_account_number": "example_recipient_account_number", "amount": 10 } }, "id": 1 }

create-recipient

Create a new payment recipient (viðtakandi) with their name, account number, and kennitala (social security number). The recipient can then be used for transfers.

Parameters

name (string) required
Recipient's full name
account_number (string) required
Recipient's bank account number (format: BBBB-LL-NNNNNN)
kennitala (string, default: ) optional
Recipient's kennitala (Icelandic national ID, format: DDMMYY-NNNN)

Example Request

{ "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "create-recipient", "arguments": { "name": "example_name", "account_number": "example_account_number" } }, "id": 1 }

get-categories

Get transaction categories. Returns a list of categories that transactions can be classified into. Useful for understanding spending patterns and categorization.

Parameters

Example Request

{ "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "get-categories", "arguments": {} }, "id": 1 }

spending-summary

Get an aggregated spending summary. Returns totals, counts, and averages grouped by category, category group, month, or merchant. Use this instead of fetching all transactions when the user asks about spending patterns, top expenses, or monthly trends.

Parameters

group_by (string, default: category) optional
How to group the spending data
Allowed values: category group month merchant
start_date (string) optional
Start date filter (ISO format: YYYY-MM-DD)
end_date (string) optional
End date filter (ISO format: YYYY-MM-DD)

Example Request

{ "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "spending-summary", "arguments": { "group_by": "category", "start_date": "example_start_date" } }, "id": 1 }

get-unpaid-bills

Get the user's unpaid Icelandic bills (kröfur / Ógreiddir reikningar) with status, due dates, amounts, and a summary. Use this when the user asks about pending bills, what they owe, or whether anything is overdue. Bills marked auto_pay=true are informational only — do not offer to pay them, they settle automatically on gjalddagi.

Parameters

status_filter (string, default: unpaid,overdue) optional
Comma-separated list of statuses: unpaid, overdue, scheduled, paid, cancelled. Default: 'unpaid,overdue'.
due_within_days (integer) optional
Only return bills due within N days from today.
limit (integer, default: 25) optional
Max number of bills to return (default 25, max 50).

Example Request

{ "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "get-unpaid-bills", "arguments": { "status_filter": "unpaid,overdue", "due_within_days": 10 } }, "id": 1 }

pay-bill

Prepare a bill payment for confirmation. Validates the bill exists, isn't already settled, and that the chosen source account has enough funds. Returns the prepared payment details — the user must explicitly confirm before execute-bill-payment is called.

Parameters

bill_id (string) required
ID of the bill (krafa) to settle.
from_account_id (string, default: ) optional
Account to debit. Optional; defaults to the user's default checking account.

Example Request

{ "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "pay-bill", "arguments": { "bill_id": "example_bill_id", "from_account_id": "" } }, "id": 1 }

execute-bill-payment

Execute a bill (krafa) payment after the user has confirmed. Use pay-bill first to prepare and validate, then call this tool once the user explicitly approves.

Parameters

bill_id (string) required
ID of the bill (krafa) to settle.
from_account_id (string) required
Account to debit (must belong to the user).

Example Request

{ "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "execute-bill-payment", "arguments": { "bill_id": "example_bill_id", "from_account_id": "example_from_account_id" } }, "id": 1 }

Integration Example (Agent → MCP Server)

This example shows how the Agent communicates with MCP Server. User tokens come from httpOnly cookies.

# Python example (Agent server-side code) import httpx_sse # Token is extracted from user's httpOnly cookie by the Agent # and forwarded to MCP Server via Authorization header headers = { "Authorization": f"Bearer {user_token}", "X-Bancony-Integration": "menigademo", "X-Bancony-Culture": "en-GB" } # Connect to MCP server via SSE async with httpx_sse.aconnect_sse( httpx.AsyncClient(), "GET", "http://mcp-server/mcp/sse", headers=headers ) as event_source: # Send tool call request response = await client.post( "http://mcp-server/mcp/messages", json={ "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "get-accounts", "arguments": {"only_withdrawal_accounts": True} }, "id": 1 } )