> ## Documentation Index
> Fetch the complete documentation index at: https://docs.melso.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Melso MCP: https://mcp.melso.ai/mcp (OAuth; one company per connection). Documentation-search MCP: https://docs.melso.ai/mcp; it does not act on customer accounts.
>
> Use the live tool list and respect company membership. Ask the person to approve the exact invoice or tax return version in the signed-in app. Melso's professionals prepare and file included returns after approval; an AI assistant does not file. A prepared file or an approval is not evidence of filing: only the AEAT's reference and receipt are. Keep credentials out of chat and logs.

# Consultar cuentas y movimientos — bank_read MCP

> MCP bank_read: accounts, movements and documents available for reconciliation. Live for an empresa.

Read-only actions. A company's bank movements, worked as its adviser does in Contabilidad › Por revisar. accounts lists the bank accounts, each with its assigned ledger account (null means unmapped and blocks reconciliation; account\_update assigns a subaccount such as 57200001, cash 570, savings 574 or a credit line 520). Mapping changes are audited; existing reconciliation snapshots and posted entries keep their captured accounts. movements lists the movements newest first (status to\_review: those not reconciled, each with the document Melso proposes, its reasons and batch\_eligible: identifying evidence with no equally strong candidate); movement reads one; documents lists the open invoices and tickets a movement can settle. reconcile records the confirmed matching and prepares a journal proposal without posting: documents it settles (an invoice less its credit note; a difference for a bank's fee or an exchange rate), lines for what no document says (kind tax with its model: 303 paid to 4750 or refunded from 4700, 111, 115, 123 and 216 to 4751, 202 to 473, 200 to 4752 or from 4709; kind account with any account of the plan: a loan 170/520 and its interest 662, capital 100, a partner 551, the Seguridad Social 476, a supplier's or customer's balance carried from imported books), or a transfer to or from another of the company's accounts, which pairs both movements and proposes one transfer entry. An authorized batch may reconcile batch\_eligible proposals with their exact displayed document amounts; conflicts stay pending. A professional reviews and explicitly posts the exact proposal in the app. unreconcile clears the matching and updates proposals; posted entries remain unchanged and require explicit reversal in the app. Bring statements in with bank\_statements. Amounts are EUR decimal strings: movements are positive in, negative out; lines and documents are always positive. Each action accepts only its own fields (\* required): accounts; movements(amount, bank\_account\_id, cursor, from, limit, q, status, to); movement(id\*); documents(id\*, amount, q).

**Availability:** Empresa.

**Access:** Live in the Melso app and over MCP for a signed-in person. Where the partner REST API covers the same area, that path is private beta until Melso enables your account. See [Access and pricing](https://docs.melso.ai/api/access.md).

The live tool list is authoritative: the company's plan and your role can narrow this contract. [Understand access](https://docs.melso.ai/mcp/permissions.md).

## When to use

Use `bank_read` for `accounts`, `documents`, `movement`, `movements`. Use [`bank`](https://docs.melso.ai/mcp/tools/bank) for the companion actions. The live tool list determines availability.

## Input

```json theme={null}
{
  "additionalProperties": false,
  "oneOf": [
    {
      "additionalProperties": false,
      "properties": {
        "action": {
          "const": "accounts"
        }
      },
      "required": [
        "action"
      ],
      "type": "object"
    },
    {
      "additionalProperties": false,
      "properties": {
        "action": {
          "const": "movements"
        },
        "amount": {
          "description": "EUR decimal string: what moved, either way.",
          "type": "string"
        },
        "bank_account_id": {
          "description": "Only this account's movements.",
          "type": "string"
        },
        "cursor": {
          "description": "next_cursor of the previous page.",
          "type": "string"
        },
        "from": {
          "description": "First day YYYY-MM-DD.",
          "type": "string"
        },
        "limit": {
          "description": "Movements per page, 50 by default.",
          "maximum": 200,
          "minimum": 1,
          "type": "integer"
        },
        "q": {
          "description": "Words of the concept, counterparty, reference, or a reconciled document or line.",
          "type": "string"
        },
        "status": {
          "description": "to_review: only the movements not reconciled.",
          "enum": [
            "all",
            "to_review"
          ],
          "type": "string"
        },
        "to": {
          "description": "Last day YYYY-MM-DD.",
          "type": "string"
        }
      },
      "required": [
        "action"
      ],
      "type": "object"
    },
    {
      "additionalProperties": false,
      "properties": {
        "action": {
          "const": "movement"
        },
        "id": {
          "description": "The movement's id, from movements.",
          "type": "string"
        }
      },
      "required": [
        "action",
        "id"
      ],
      "type": "object"
    },
    {
      "additionalProperties": false,
      "properties": {
        "action": {
          "const": "documents"
        },
        "amount": {
          "description": "EUR decimal string.",
          "type": "string"
        },
        "id": {
          "description": "The movement's id, from movements.",
          "type": "string"
        },
        "q": {
          "description": "Words of the party or the number.",
          "type": "string"
        }
      },
      "required": [
        "action",
        "id"
      ],
      "type": "object"
    }
  ],
  "properties": {
    "action": {
      "enum": [
        "accounts",
        "movements",
        "movement",
        "documents"
      ],
      "type": "string"
    },
    "amount": {
      "anyOf": [
        {
          "description": "EUR decimal string: what moved, either way.",
          "type": "string"
        },
        {
          "description": "EUR decimal string.",
          "type": "string"
        }
      ],
      "description": "movements: what moved, either way; documents: a document's total or what it still owes. EUR decimal string."
    },
    "bank_account_id": {
      "description": "Only this account's movements.",
      "type": "string"
    },
    "cursor": {
      "description": "next_cursor of the previous page.",
      "type": "string"
    },
    "from": {
      "description": "First day YYYY-MM-DD.",
      "type": "string"
    },
    "id": {
      "description": "account_update: the bank account's id, from accounts; movement, documents, reconcile and unreconcile: the movement's id, from movements.",
      "type": "string"
    },
    "limit": {
      "description": "Movements per page, 50 by default.",
      "maximum": 200,
      "minimum": 1,
      "type": "integer"
    },
    "q": {
      "anyOf": [
        {
          "description": "Words of the concept, counterparty, reference, or a reconciled document or line.",
          "type": "string"
        },
        {
          "description": "Words of the party or the number.",
          "type": "string"
        }
      ],
      "description": "movements: words of the concept, counterparty, reference, or a reconciled document or line; documents: words of a document's party or number."
    },
    "status": {
      "description": "to_review: only the movements not reconciled.",
      "enum": [
        "all",
        "to_review"
      ],
      "type": "string"
    },
    "to": {
      "description": "Last day YYYY-MM-DD.",
      "type": "string"
    }
  },
  "required": [
    "action"
  ],
  "type": "object"
}
```

## Actions

The tool's schema combines the fields of every action. Each action accepts only its own fields below; send `action` with them.

### Read actions

These actions only read. They change nothing.

> [accordion] accounts
>
> The company's bank accounts: each one's id, name, IBAN and account, its assigned ledger account (null means unmapped and blocks reconciliation).
>
> ```json theme={null}
> {
>   "additionalProperties": false,
>   "properties": {},
>   "type": "object"
> }
> ```

> [accordion] documents
>
> The open documents a movement can settle, the likeliest first: money in with sales (income and invoices), money out with purchases (expenses), and the credit notes that correct them. Each with its type, id, party, number, day, total and what it still owes. q finds a party or number; amount a total or what is owed.
>
> ```json theme={null}
> {
>   "additionalProperties": false,
>   "properties": {
>     "amount": {
>       "description": "EUR decimal string.",
>       "type": "string"
>     },
>     "id": {
>       "description": "The movement's id, from movements.",
>       "type": "string"
>     },
>     "q": {
>       "description": "Words of the party or the number.",
>       "type": "string"
>     }
>   },
>   "required": [
>     "id"
>   ],
>   "type": "object"
> }
> ```

> [accordion] movement
>
> One movement with its reconciliation or proposal. The proposal includes its document evidence and fingerprint; pass that fingerprint as expected\_fingerprint when confirming reviewed evidence.
>
> ```json theme={null}
> {
>   "additionalProperties": false,
>   "properties": {
>     "id": {
>       "description": "The movement's id, from movements.",
>       "type": "string"
>     }
>   },
>   "required": [
>     "id"
>   ],
>   "type": "object"
> }
> ```

> [accordion] movements
>
> The company's bank movements, newest first: each with its account, day, amount (positive in, negative out), the bank's concept, counterparty and reference, and its reconciliation (documents, lines and difference) or, when not reconciled, the document Melso proposes with its reasons and batch\_eligible (identifying evidence with no equally strong candidate). status to\_review lists only the movements not reconciled. q finds a concept, counterparty, reference, a reconciled document's party or number, or a line's concept; amount finds what moved that much either way. A full page carries next\_cursor.
>
> ```json theme={null}
> {
>   "additionalProperties": false,
>   "properties": {
>     "amount": {
>       "description": "EUR decimal string: what moved, either way.",
>       "type": "string"
>     },
>     "bank_account_id": {
>       "description": "Only this account's movements.",
>       "type": "string"
>     },
>     "cursor": {
>       "description": "next_cursor of the previous page.",
>       "type": "string"
>     },
>     "from": {
>       "description": "First day YYYY-MM-DD.",
>       "type": "string"
>     },
>     "limit": {
>       "description": "Movements per page, 50 by default.",
>       "maximum": 200,
>       "minimum": 1,
>       "type": "integer"
>     },
>     "q": {
>       "description": "Words of the concept, counterparty, reference, or a reconciled document or line.",
>       "type": "string"
>     },
>     "status": {
>       "description": "to_review: only the movements not reconciled.",
>       "enum": [
>         "all",
>         "to_review"
>       ],
>       "type": "string"
>     },
>     "to": {
>       "description": "Last day YYYY-MM-DD.",
>       "type": "string"
>     }
>   },
>   "type": "object"
> }
> ```

## Output

`accounts` returns bank accounts and their ledger mapping. `movements` returns movements newest first with their reconciliation or proposal and a cursor on a full page. `movement` returns one; `documents` returns the open documents it can settle.

The result uses MCP `content` blocks; JSON payloads are encoded in text and may also appear in `structuredContent`. Check `isError` before reading a success payload. When the server declares an `outputSchema`, it is reproduced below. Check the action result and its declared fields before reporting success.

## Example

Use the actions of this tool in the order shown; its companion tool covers the other actions. These are the `arguments` of each call, in order.

**1. List the movements still to review**

```json theme={null}
{
  "action": "movements",
  "status": "to_review"
}
```

**2. Find the documents that movement can settle**

```json theme={null}
{
  "action": "documents",
  "id": "11111111-1111-4111-8111-111111111111"
}
```

The first call as a request. Use an OAuth access token issued for this MCP resource and replace the example identifiers with values from your own company.

```bash theme={null}
curl --fail-with-body https://mcp.melso.ai/mcp \
  -H "Authorization: Bearer $MELSO_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  --data-binary @- <<'JSON'
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "bank_read",
    "arguments": {
      "action": "movements",
      "status": "to_review"
    }
  }
}
JSON
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.