> ## 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 facturas Verifactu — invoices_read MCP

> MCP invoices_read: read invoices, PDFs and the owner’s approval link. Live in the app and MCP.

Read-only actions. Read invoices and prepare unnumbered drafts or corrections. issue submits the exact saved version when the owner asks, through their external OAuth connection, with paid tools and verified supplier authority. Pass the version from get as expected\_version. A reserved number or pending provider is not confirmed registration; inspect verifactu\_status, pdf\_ready and delivery state. Configured payment-link creation and email delivery may follow registration. Retry only the same invoice and version after an uncertain response. request\_approval offers web review instead. No action approves, files or pays a tax return. Each action accepts only its own fields (\* required): get(id\*); request\_approval(id\*); list(contact\_id, cursor, document\_number, due\_date\_end, due\_date\_start, end\_date, limit, q, sort, start\_date, status).

**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).

Without a plan that includes the tools, only the read actions are listed: `get`, `list`.

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 `invoices_read` for `get`, `list`, `request_approval`. Use [`invoices`](https://docs.melso.ai/mcp/tools/invoices) for the companion actions. The live tool list determines availability.

## Input

```json theme={null}
{
  "additionalProperties": false,
  "oneOf": [
    {
      "additionalProperties": false,
      "properties": {
        "action": {
          "const": "get"
        },
        "id": {
          "description": "Invoice UUID in this company.",
          "type": "string"
        }
      },
      "required": [
        "action",
        "id"
      ],
      "type": "object"
    },
    {
      "additionalProperties": false,
      "properties": {
        "action": {
          "const": "request_approval"
        },
        "id": {
          "description": "Invoice UUID in this company.",
          "type": "string"
        }
      },
      "required": [
        "action",
        "id"
      ],
      "type": "object"
    },
    {
      "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"
    }
  ],
  "properties": {
    "action": {
      "enum": [
        "get",
        "request_approval",
        "list"
      ],
      "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": "Invoice UUID in this company.",
      "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] get
>
> Read one of the company's invoices including its current reviewed-content version and totals.
>
> ```json theme={null}
> {
>   "additionalProperties": false,
>   "properties": {
>     "id": {
>       "description": "Invoice UUID in this company.",
>       "type": "string"
>     }
>   },
>   "required": [
>     "id"
>   ],
>   "type": "object"
> }
> ```

> [accordion] list
>
> List this company's local invoice summaries with settlement balances. Follow next\_cursor while has\_more; keep filters unchanged. The invoice record holds the legal registration and PDF.
>
> ```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"
> }
> ```

> [accordion] request\_approval
>
> Read the draft preview and return Emitir/Cambiar actions for authenticated web review. Present the preview and approval URL when the person prefers reviewing in Melso. This action does not issue the invoice; the owner's external OAuth connection can issue its exact version with issue.
>
> ```json theme={null}
> {
>   "additionalProperties": false,
>   "properties": {
>     "id": {
>       "description": "Invoice UUID in this company.",
>       "type": "string"
>     }
>   },
>   "required": [
>     "id"
>   ],
>   "type": "object"
> }
> ```

## Output

`list` and `get` return invoices with their totals and status. `request_approval` returns the saved preview and the signed-in page where the owner issues the exact version.

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": {
        "corrects_invoice_id": {
          "type": [
            "string",
            "null"
          ]
        },
        "created_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "currency": {
          "type": "string"
        },
        "customer_id": {
          "type": "string"
        },
        "customer_name": {
          "type": "string"
        },
        "customer_tax_id": {
          "type": "string"
        },
        "due_date": {
          "type": [
            "string",
            "null"
          ]
        },
        "email_delivery_error": {
          "type": [
            "string",
            "null"
          ]
        },
        "email_delivery_status": {
          "type": "string"
        },
        "fiscal_network": {
          "type": "string"
        },
        "id": {
          "type": "string"
        },
        "irpf_amount": {
          "type": "string"
        },
        "irpf_rate": {
          "type": "string"
        },
        "issue_date": {
          "type": [
            "string",
            "null"
          ]
        },
        "lines": {
          "items": {
            "properties": {
              "description": {
                "type": "string"
              },
              "quantity": {
                "type": "string"
              },
              "unit_price": {
                "type": "string"
              },
              "vat_rate": {
                "type": "string"
              }
            },
            "type": "object"
          },
          "type": "array"
        },
        "notes": {
          "type": "string"
        },
        "number": {
          "type": [
            "integer",
            "null"
          ]
        },
        "paid_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "payment_link": {
          "type": [
            "string",
            "null"
          ]
        },
        "payment_link_error": {
          "type": [
            "string",
            "null"
          ]
        },
        "payment_link_status": {
          "type": "string"
        },
        "pdf_ready": {
          "type": "boolean"
        },
        "sent_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "series": {
          "type": [
            "string",
            "null"
          ]
        },
        "status": {
          "type": "string"
        },
        "subtotal": {
          "type": "string"
        },
        "tax_label": {
          "type": "string"
        },
        "total": {
          "type": "string"
        },
        "type": {
          "type": "string"
        },
        "updated_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "vat_amount": {
          "type": "string"
        },
        "verifactu_status": {
          "type": "string"
        },
        "version": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "version",
        "status",
        "total",
        "verifactu_status",
        "pdf_ready",
        "email_delivery_status"
      ],
      "type": "object"
    },
    {
      "properties": {
        "approval_required": {
          "type": "boolean"
        },
        "approval_url": {
          "type": "string"
        },
        "invoice": {
          "properties": {
            "corrects_invoice_id": {
              "type": [
                "string",
                "null"
              ]
            },
            "created_at": {
              "type": [
                "string",
                "null"
              ]
            },
            "currency": {
              "type": "string"
            },
            "customer_id": {
              "type": "string"
            },
            "customer_name": {
              "type": "string"
            },
            "customer_tax_id": {
              "type": "string"
            },
            "due_date": {
              "type": [
                "string",
                "null"
              ]
            },
            "email_delivery_error": {
              "type": [
                "string",
                "null"
              ]
            },
            "email_delivery_status": {
              "type": "string"
            },
            "fiscal_network": {
              "type": "string"
            },
            "id": {
              "type": "string"
            },
            "irpf_amount": {
              "type": "string"
            },
            "irpf_rate": {
              "type": "string"
            },
            "issue_date": {
              "type": [
                "string",
                "null"
              ]
            },
            "lines": {
              "items": {
                "properties": {
                  "description": {
                    "type": "string"
                  },
                  "quantity": {
                    "type": "string"
                  },
                  "unit_price": {
                    "type": "string"
                  },
                  "vat_rate": {
                    "type": "string"
                  }
                },
                "type": "object"
              },
              "type": "array"
            },
            "notes": {
              "type": "string"
            },
            "number": {
              "type": [
                "integer",
                "null"
              ]
            },
            "paid_at": {
              "type": [
                "string",
                "null"
              ]
            },
            "payment_link": {
              "type": [
                "string",
                "null"
              ]
            },
            "payment_link_error": {
              "type": [
                "string",
                "null"
              ]
            },
            "payment_link_status": {
              "type": "string"
            },
            "pdf_ready": {
              "type": "boolean"
            },
            "sent_at": {
              "type": [
                "string",
                "null"
              ]
            },
            "series": {
              "type": [
                "string",
                "null"
              ]
            },
            "status": {
              "type": "string"
            },
            "subtotal": {
              "type": "string"
            },
            "tax_label": {
              "type": "string"
            },
            "total": {
              "type": "string"
            },
            "type": {
              "type": "string"
            },
            "updated_at": {
              "type": [
                "string",
                "null"
              ]
            },
            "vat_amount": {
              "type": "string"
            },
            "verifactu_status": {
              "type": "string"
            },
            "version": {
              "type": "string"
            }
          },
          "required": [
            "id",
            "version",
            "status",
            "total",
            "verifactu_status",
            "pdf_ready",
            "email_delivery_status"
          ],
          "type": "object"
        }
      },
      "required": [
        "invoice",
        "approval_required",
        "approval_url"
      ],
      "type": "object"
    },
    {
      "properties": {
        "has_more": {
          "type": "boolean"
        },
        "invoices": {
          "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"
        },
        "next_cursor": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "invoices",
        "has_more",
        "next_cursor"
      ],
      "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. Get the approval page for that draft**

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

**2. Read it again later to see whether it was issued**

```json theme={null}
{
  "action": "get",
  "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": "invoices_read",
    "arguments": {
      "action": "request_approval",
      "id": "11111111-1111-4111-8111-111111111111"
    }
  }
}
JSON
```


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