> ## 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 gastos — expenses_read MCP

> MCP expenses_read: list and read received invoices and receipts. Live in the app and MCP.

Read-only actions. Read and record this company's expenses, and read any invoice or receipt with from\_document, which records it as an expense or an income. Monetary amounts are EUR decimal strings. vat\_country is the VAT jurisdiction printed on the invoice, separately from supplier\_country. Spanish VAT from a foreign supplier stays pending until Melso reviews invoice entitlement and vat\_deductible is true. Ask customers only whether an undecided expense belongs to their professional activity; technical warnings are Melso's responsibility. Save the answer with only id, expected\_version and deductible, preserving internal review codes. Other edits retain fiscal evidence validation. Deductible is an activity classification, not approval of a deduction. category is the AEAT expense concept code; deductibility is Melso's estimate (likely, review or unlikely) with the rule behind it, never a confirmed deduction. An expense in another currency counts at the ECB rate of its date; update records when it was paid and the euros that went out (paid\_date, paid\_amount), and the 130 counts the difference then. Each action accepts only its own fields (\* required): list(contact\_id, cursor, document\_number, due\_date\_end, due\_date\_start, end\_date, limit, q, sort, start\_date, status); get(id\*); document\_status(job\_id).

**Availability:** Autónomo / 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 `expenses_read` for `document_status`, `get`, `list`. Use [`expenses`](https://docs.melso.ai/mcp/tools/expenses) for the companion actions. The live tool list determines availability.

## Input

```json theme={null}
{
  "additionalProperties": false,
  "oneOf": [
    {
      "additionalProperties": false,
      "properties": {
        "action": {
          "const": "list"
        },
        "contact_id": {
          "description": "Customer or supplier contact UUID from contacts_read; includes its merged identities.",
          "type": "string"
        },
        "cursor": {
          "description": "Opaque next_cursor from the previous page; keep every filter and sort unchanged.",
          "type": "string"
        },
        "document_number": {
          "description": "Literal substring of the document number, case insensitive.",
          "type": "string"
        },
        "due_date_end": {
          "description": "Inclusive due-date upper bound, YYYY-MM-DD.",
          "type": "string"
        },
        "due_date_start": {
          "description": "Inclusive due-date lower bound, YYYY-MM-DD.",
          "type": "string"
        },
        "end_date": {
          "description": "Inclusive issue/expense date upper bound, YYYY-MM-DD.",
          "type": "string"
        },
        "limit": {
          "default": 50,
          "maximum": 200,
          "minimum": 1,
          "type": "integer"
        },
        "q": {
          "description": "Literal words of the counterparty name, tax ID or document number.",
          "type": "string"
        },
        "sort": {
          "default": "-date",
          "enum": [
            "date",
            "-date",
            "due_date",
            "-due_date",
            "total",
            "-total"
          ],
          "type": "string"
        },
        "start_date": {
          "description": "Inclusive issue/expense date lower bound, YYYY-MM-DD.",
          "type": "string"
        },
        "status": {
          "description": "pending: no payment; partial: partly paid; completed: settled; outstanding: positive balance excluding drafts; overdue: outstanding and due before today in Europe/Madrid. Expense due dates come from saved maturities. Balances include recorded reconciliations; they do not confirm a bank transfer.",
          "enum": [
            "pending",
            "partial",
            "completed",
            "outstanding",
            "overdue"
          ],
          "type": "string"
        }
      },
      "required": [
        "action"
      ],
      "type": "object"
    },
    {
      "additionalProperties": false,
      "properties": {
        "action": {
          "const": "get"
        },
        "id": {
          "description": "Company-scoped expense UUID.",
          "type": "string"
        }
      },
      "required": [
        "action",
        "id"
      ],
      "type": "object"
    },
    {
      "additionalProperties": false,
      "properties": {
        "action": {
          "const": "document_status"
        },
        "job_id": {
          "description": "Job from from_document; omit for the latest twenty.",
          "type": "string"
        }
      },
      "required": [
        "action"
      ],
      "type": "object"
    }
  ],
  "properties": {
    "action": {
      "enum": [
        "list",
        "get",
        "document_status"
      ],
      "type": "string"
    },
    "contact_id": {
      "description": "Customer or supplier contact UUID from contacts_read; includes its merged identities.",
      "type": "string"
    },
    "cursor": {
      "description": "Opaque next_cursor from the previous page; keep every filter and sort unchanged.",
      "type": "string"
    },
    "document_number": {
      "description": "Literal substring of the document number, case insensitive.",
      "type": "string"
    },
    "due_date_end": {
      "description": "Inclusive due-date upper bound, YYYY-MM-DD.",
      "type": "string"
    },
    "due_date_start": {
      "description": "Inclusive due-date lower bound, YYYY-MM-DD.",
      "type": "string"
    },
    "end_date": {
      "description": "Inclusive issue/expense date upper bound, YYYY-MM-DD.",
      "type": "string"
    },
    "id": {
      "description": "Company-scoped expense UUID.",
      "type": "string"
    },
    "job_id": {
      "description": "Job from from_document; omit for the latest twenty.",
      "type": "string"
    },
    "limit": {
      "default": 50,
      "maximum": 200,
      "minimum": 1,
      "type": "integer"
    },
    "q": {
      "description": "Literal words of the counterparty name, tax ID or document number.",
      "type": "string"
    },
    "sort": {
      "default": "-date",
      "enum": [
        "date",
        "-date",
        "due_date",
        "-due_date",
        "total",
        "-total"
      ],
      "type": "string"
    },
    "start_date": {
      "description": "Inclusive issue/expense date lower bound, YYYY-MM-DD.",
      "type": "string"
    },
    "status": {
      "description": "pending: no payment; partial: partly paid; completed: settled; outstanding: positive balance excluding drafts; overdue: outstanding and due before today in Europe/Madrid. Expense due dates come from saved maturities. Balances include recorded reconciliations; they do not confirm a bank transfer.",
      "enum": [
        "pending",
        "partial",
        "completed",
        "outstanding",
        "overdue"
      ],
      "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] document\_status
>
> What documents queued with from\_document became: one job by job\_id, or the company's latest twenty. Each says queued, done (with the expense or income recorded, its review codes and deductibility) or failed (with a code; direction\_unknown means ask and queue it again with direction; country\_unknown means ask the supplier/customer country and retry with counterparty\_country and the direction from the error).
>
> ```json theme={null}
> {
>   "additionalProperties": false,
>   "properties": {
>     "job_id": {
>       "description": "Job from from_document; omit for the latest twenty.",
>       "type": "string"
>     }
>   },
>   "type": "object"
> }
> ```

> [accordion] get
>
> Read one expense belonging to this company, including its saved version, deductibility and review codes.
>
> ```json theme={null}
> {
>   "additionalProperties": false,
>   "properties": {
>     "id": {
>       "description": "Company-scoped expense UUID.",
>       "type": "string"
>     }
>   },
>   "required": [
>     "id"
>   ],
>   "type": "object"
> }
> ```

> [accordion] list
>
> List bounded expense summaries with saved versions, category, classification and settlement balances. Get an expense for its full evidence, review codes and deductibility estimate. Follow next\_cursor while has\_more and keep filters unchanged.
>
> ```json theme={null}
> {
>   "additionalProperties": false,
>   "properties": {
>     "contact_id": {
>       "description": "Customer or supplier contact UUID from contacts_read; includes its merged identities.",
>       "type": "string"
>     },
>     "cursor": {
>       "description": "Opaque next_cursor from the previous page; keep every filter and sort unchanged.",
>       "type": "string"
>     },
>     "document_number": {
>       "description": "Literal substring of the document number, case insensitive.",
>       "type": "string"
>     },
>     "due_date_end": {
>       "description": "Inclusive due-date upper bound, YYYY-MM-DD.",
>       "type": "string"
>     },
>     "due_date_start": {
>       "description": "Inclusive due-date lower bound, YYYY-MM-DD.",
>       "type": "string"
>     },
>     "end_date": {
>       "description": "Inclusive issue/expense date upper bound, YYYY-MM-DD.",
>       "type": "string"
>     },
>     "limit": {
>       "default": 50,
>       "maximum": 200,
>       "minimum": 1,
>       "type": "integer"
>     },
>     "q": {
>       "description": "Literal words of the counterparty name, tax ID or document number.",
>       "type": "string"
>     },
>     "sort": {
>       "default": "-date",
>       "enum": [
>         "date",
>         "-date",
>         "due_date",
>         "-due_date",
>         "total",
>         "-total"
>       ],
>       "type": "string"
>     },
>     "start_date": {
>       "description": "Inclusive issue/expense date lower bound, YYYY-MM-DD.",
>       "type": "string"
>     },
>     "status": {
>       "description": "pending: no payment; partial: partly paid; completed: settled; outstanding: positive balance excluding drafts; overdue: outstanding and due before today in Europe/Madrid. Expense due dates come from saved maturities. Balances include recorded reconciliations; they do not confirm a bank transfer.",
>       "enum": [
>         "pending",
>         "partial",
>         "completed",
>         "outstanding",
>         "overdue"
>       ],
>       "type": "string"
>     }
>   },
>   "type": "object"
> }
> ```

## Output

`list` and `get` return expenses with their amounts, category, review and saved version. `document_status` returns what a queued document became.

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.

### Declared output schema

```json theme={null}
{
  "anyOf": [
    {
      "properties": {
        "expenses": {
          "items": {
            "properties": {
              "category": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "date": {
                "type": "string"
              },
              "deductible": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "document_number": {
                "type": "string"
              },
              "due_date": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "id": {
                "type": "string"
              },
              "party": {
                "type": "string"
              },
              "payment_status": {
                "type": "string"
              },
              "payments_pending": {
                "type": "string"
              },
              "payments_total": {
                "type": "string"
              },
              "total": {
                "type": "string"
              },
              "version": {
                "type": [
                  "integer",
                  "null"
                ]
              }
            },
            "required": [
              "id",
              "date",
              "party",
              "total",
              "payments_total",
              "payments_pending",
              "payment_status"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "has_more": {
          "type": "boolean"
        },
        "next_cursor": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "expenses",
        "has_more",
        "next_cursor"
      ],
      "type": "object"
    },
    {
      "properties": {
        "account": {
          "type": [
            "string",
            "null"
          ]
        },
        "booked_account": {
          "type": "string"
        },
        "category": {
          "type": [
            "string",
            "null"
          ]
        },
        "deductibility": {
          "properties": {
            "reason": {
              "type": "string"
            },
            "status": {
              "type": "string"
            }
          },
          "type": "object"
        },
        "deductible": {
          "type": "string"
        },
        "deductible_question": {
          "type": [
            "string",
            "null"
          ]
        },
        "deductible_reason": {
          "type": [
            "string",
            "null"
          ]
        },
        "document_number": {
          "type": [
            "string",
            "null"
          ]
        },
        "expense_date": {
          "type": "string"
        },
        "file_id": {
          "type": [
            "string",
            "null"
          ]
        },
        "id": {
          "type": "string"
        },
        "irpf_amount": {
          "type": [
            "string",
            "null"
          ]
        },
        "irpf_rate": {
          "type": [
            "string",
            "null"
          ]
        },
        "paid_amount": {
          "type": [
            "string",
            "null"
          ]
        },
        "paid_date": {
          "type": [
            "string",
            "null"
          ]
        },
        "review": {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "subtotal": {
          "type": "string"
        },
        "supplier_name": {
          "type": "string"
        },
        "supplier_tax_id": {
          "type": [
            "string",
            "null"
          ]
        },
        "total": {
          "type": "string"
        },
        "vat_amount": {
          "type": "string"
        },
        "vat_rate": {
          "type": [
            "string",
            "null"
          ]
        },
        "version": {
          "type": "integer"
        }
      },
      "required": [
        "id",
        "version",
        "supplier_name",
        "total"
      ],
      "type": "object"
    },
    {
      "anyOf": [
        {
          "properties": {
            "error": {
              "type": [
                "object",
                "string",
                "null"
              ]
            },
            "job_id": {
              "type": "string"
            },
            "record": {
              "type": [
                "object",
                "null"
              ]
            },
            "review": {
              "type": [
                "array",
                "null"
              ]
            },
            "status": {
              "type": "string"
            }
          },
          "required": [
            "job_id",
            "status"
          ],
          "type": "object"
        },
        {
          "properties": {
            "jobs": {
              "items": {
                "properties": {
                  "error": {
                    "type": [
                      "object",
                      "string",
                      "null"
                    ]
                  },
                  "job_id": {
                    "type": "string"
                  },
                  "record": {
                    "type": [
                      "object",
                      "null"
                    ]
                  },
                  "review": {
                    "type": [
                      "array",
                      "null"
                    ]
                  },
                  "status": {
                    "type": "string"
                  }
                },
                "required": [
                  "job_id",
                  "status"
                ],
                "type": "object"
              },
              "type": "array"
            }
          },
          "required": [
            "jobs"
          ],
          "type": "object"
        }
      ],
      "type": "object"
    }
  ],
  "type": "object"
}
```

## 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. See what the document became**

```json theme={null}
{
  "action": "document_status",
  "job_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": "expenses_read",
    "arguments": {
      "action": "document_status",
      "job_id": "11111111-1111-4111-8111-111111111111"
    }
  }
}
JSON
```


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