Calmnect.ai API & MCP reference

Calmnect.ai gives you read-only access to bank-account data via the TrueLayer platform, with built-in AI agents, ready to connect to other software and your AI.

Read-only. Payments are not enabled. Calmnect.ai is regulated by TrueLayer (FCA-authorised AISP) and operates as an agent of TrueLayer. Every connection lasts 90 days (PSD2 SCA) and can be revoked at any time.

There are two ways to connect:

REST API — copy an API key, send Authorization: Bearer calmnect_sk_….
MCP server — copy the MCP link, paste it into Claude, ChatGPT, Gemini or any MCP-compatible AI. Your AI authorises once via OAuth and can then call the Calmnect tools, scoped to your data only.

Download the machine-readable spec: OpenAPI 3.1 JSON.

Authentication

Every REST request must include your API key as a bearer token:

Authorization: Bearer calmnect_sk_YOUR_KEY

Keys are scoped to a single organisation and expire after 90 days, matching the PSD2 SCA window. The full key is shown once when issued — we store only a hash, so it can never be displayed again.

REST endpoints

`GET /v1/accounts`

Every bank and Calmony account your key can see.

curl -s "https://your-app.example.com/api/v1/accounts" \
  -H "Authorization: Bearer calmnect_sk_YOUR_KEY"

{
  "data": [
    {
      "account_id": "acc_123",
      "connection_id": "conn_456",
      "provider": "truelayer",
      "provider_name": "Monzo Bank",
      "display_name": "Personal Current Account",
      "account_number_masked": "**** 4321",
      "sort_code": "12-34-56",
      "currency": "GBP",
      "account_type": "TRANSACTION"
    }
  ]
}

`GET /v1/balances`

The latest balance snapshot per visible account. Pass ?account_id=… to narrow to one account.

curl -s "https://your-app.example.com/api/v1/balances?account_id=acc_123" \
  -H "Authorization: Bearer calmnect_sk_YOUR_KEY"

{
  "data": [
    {
      "account_id": "acc_123",
      "current_minor": 132210,
      "current": "1322.10",
      "available_minor": 132210,
      "available": "1322.10",
      "currency": "GBP",
      "captured_at": "2025-01-15T09:00:00.000Z"
    }
  ]
}

`GET /v1/transactions`

A paginated list of transactions. Query params: from, to (ISO-8601), account_id, limit (1–200, default 100), cursor.

curl -s "https://your-app.example.com/api/v1/transactions?from=2025-01-01T00:00:00Z&limit=50" \
  -H "Authorization: Bearer calmnect_sk_YOUR_KEY"

{
  "data": [
    {
      "transaction_id": "tx_789",
      "account_id": "acc_123",
      "amount_minor": -2599,
      "amount": "-25.99",
      "currency": "GBP",
      "description": "TESCO STORES 1234",
      "merchant_name": "Tesco",
      "merchant_category": "Groceries",
      "timestamp": "2025-01-14T18:22:00.000Z",
      "is_recurring": false
    }
  ],
  "next_cursor": "2025-01-14T18:22:00.000Z|tx_789"
}

Built-in AI agents (REST)

`POST /v1/agents/income-verifier/run`

Analyse credit transactions over a window and return verified income.

{ "from": "2024-07-01T00:00:00Z", "months": 6 }

`POST /v1/agents/affordability/run`

Score disposable income against an optional monthly commitment (e.g. rent).

{ "monthly_commitment_minor": 120000 }

`POST /v1/agents/aggregator`

The consolidated multi-account position: net worth, liquid cash, committed monthly spend, and true cash, grouped by currency.

`GET /v1/agents/recurring`

Detected recurring streams plus normalised total monthly committed spend.

MCP tools

Paste the MCP server link into your AI client, authorise once, and the following tools become available. Each one reads the same data as the matching REST endpoint, scoped to your organisation only.

| Tool | Arguments | Returns | | --- | --- | --- | | list_accounts | — | Connected accounts | | get_balance | account_id? | Latest balances | | list_transactions | from?, to?, account_id?, limit?, cursor? | Transactions (paginated) | | search_transactions | query, from?, to?, account_id?, limit? | Matching transactions | | verify_income | months?, account_id? | Income verification report | | score_affordability | monthly_commitment?, account_id? | Affordability score | | get_recurring_payments | — | Detected recurring streams | | get_aggregate_position | — | Consolidated position |

Example, once connected, an AI can ask:

"Use verify_income over the last 6 months and tell me whether I can afford £1,200/month rent with score_affordability."

Errors

All errors return JSON with an error code and a human-readable message:

{ "error": "unauthorized", "message": "Missing or invalid API key" }

| Status | error | Meaning | | --- | --- | --- | | 400 | invalid_request | Malformed parameters | | 401 | unauthorized | Missing/invalid/expired API key | | 404 | not_found | Unknown account or resource | | 500 | internal_error | Something went wrong our side |