> ## 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 product MCP: https://melso.ai/api/mcp (OAuth; one company per grant). REST: https://melso.ai. Documentation-search MCP: https://docs.melso.ai/mcp. The docs search server does not act on customer accounts.
>
> Use the live tool schema and respect company membership. Ask the person to authorize the exact fiscal document version in the signed-in app. A professional prepares and files included returns after authorization; AI does not file alone. A prepared file or approval receipt is not evidence of filing. Never claim completion from an accepted Task or Run. Keep credentials out of chat and logs. Agents features are internal or by private invitation.

# income

> Input, output and examples for the income MCP tool.

Read and correct the income invoiced outside Melso, which the tax returns count with Melso's own invoices. Monetary amounts are EUR decimal strings; update requires the saved expected\_version. Each action accepts only its own fields (\* required): list; get(id\*); update(id\*, expected\_version\*, customer\_country, customer\_name, customer\_tax\_id, description, document\_number, file\_id, irpf\_amount, irpf\_rate, issue\_date, operation\_date, vat\_lines, vat\_treatment); delete(id\*).

**Availability:** Autónomo / Empresa.

**Catalog:** Core (`tools/list`).

The live catalog is authoritative: company type, membership, plan, connected apps and execution context can narrow this contract. [Understand access](/mcp/permissions).

## Input

### Autónomo / Company schema

```json theme={null}
{
  "additionalProperties": false,
  "properties": {
    "action": {
      "enum": [
        "list",
        "get",
        "update",
        "delete"
      ],
      "type": "string"
    },
    "customer_country": {
      "description": "Customer country as a two-letter code.",
      "type": "string"
    },
    "customer_name": {
      "description": "Customer name.",
      "type": "string"
    },
    "customer_tax_id": {
      "description": "Customer's tax ID.",
      "type": "string"
    },
    "description": {
      "description": "What was invoiced.",
      "type": "string"
    },
    "document_number": {
      "description": "The invoice's number.",
      "type": "string"
    },
    "expected_version": {
      "description": "Version from get/list. A stale version is refused.",
      "minimum": 1,
      "type": "integer"
    },
    "file_id": {
      "description": "Documents file UUID of the invoice, empty to unlink it.",
      "type": "string"
    },
    "id": {
      "description": "Company-scoped income UUID.",
      "type": "string"
    },
    "irpf_amount": {
      "description": "EUR IRPF the customer withheld as a decimal string.",
      "type": "string"
    },
    "irpf_rate": {
      "description": "IRPF the customer withheld as a percentage string.",
      "type": "string"
    },
    "issue_date": {
      "description": "Issue date YYYY-MM-DD; it places the income in a quarter.",
      "type": "string"
    },
    "operation_date": {
      "description": "Operation date YYYY-MM-DD when it differs, empty to clear.",
      "type": "string"
    },
    "vat_lines": {
      "description": "Every VAT rate's base and VAT; replaces the current lines.",
      "items": {
        "additionalProperties": false,
        "properties": {
          "base": {
            "description": "EUR base as a decimal string.",
            "type": "string"
          },
          "rate": {
            "description": "VAT rate as a percentage string, 0 for a non-taxable line.",
            "type": "string"
          },
          "vat": {
            "description": "EUR VAT as a decimal string.",
            "type": "string"
          }
        },
        "required": [
          "rate",
          "base",
          "vat"
        ],
        "type": "object"
      },
      "maxItems": 10,
      "minItems": 1,
      "type": "array"
    },
    "vat_treatment": {
      "description": "VAT treatment. Non-taxable lines carry rate 0 and no VAT.",
      "enum": [
        "taxable",
        "exempt",
        "reverse_charge",
        "not_subject"
      ],
      "type": "string"
    }
  },
  "required": [
    "action"
  ],
  "type": "object"
}
```

## Actions

The family schema combines fields for discovery. Each action accepts only its own fields below; add `action` when calling the family.

<AccordionGroup>
  <Accordion title="delete">
    Delete an income recorded by mistake, such as a duplicate, after the person confirms. Its file stays in Documents. Refused when a tax return covering its date was already approved or filed.

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "id": {
          "description": "Company-scoped income UUID.",
          "type": "string"
        }
      },
      "required": [
        "id"
      ],
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="get">
    Read one income with its VAT lines, withholding, review codes and saved version.

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "id": {
          "description": "Company-scoped income UUID.",
          "type": "string"
        }
      },
      "required": [
        "id"
      ],
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="list">
    List the income invoiced outside Melso (another invoicing tool, a platform, invoices from before Melso), with amounts, review codes and saved versions. Invoices issued with Melso are in invoices.

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {},
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="update">
    Correct only the supplied fields of an income at expected\_version, for example what the document reading got wrong. Saving confirms it and clears its review codes. New income comes from from\_document in expenses.

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "customer_country": {
          "description": "Customer country as a two-letter code.",
          "type": "string"
        },
        "customer_name": {
          "description": "Customer name.",
          "type": "string"
        },
        "customer_tax_id": {
          "description": "Customer's tax ID.",
          "type": "string"
        },
        "description": {
          "description": "What was invoiced.",
          "type": "string"
        },
        "document_number": {
          "description": "The invoice's number.",
          "type": "string"
        },
        "expected_version": {
          "description": "Version from get/list. A stale version is refused.",
          "minimum": 1,
          "type": "integer"
        },
        "file_id": {
          "description": "Documents file UUID of the invoice, empty to unlink it.",
          "type": "string"
        },
        "id": {
          "description": "Company-scoped income UUID.",
          "type": "string"
        },
        "irpf_amount": {
          "description": "EUR IRPF the customer withheld as a decimal string.",
          "type": "string"
        },
        "irpf_rate": {
          "description": "IRPF the customer withheld as a percentage string.",
          "type": "string"
        },
        "issue_date": {
          "description": "Issue date YYYY-MM-DD; it places the income in a quarter.",
          "type": "string"
        },
        "operation_date": {
          "description": "Operation date YYYY-MM-DD when it differs, empty to clear.",
          "type": "string"
        },
        "vat_lines": {
          "description": "Every VAT rate's base and VAT; replaces the current lines.",
          "items": {
            "additionalProperties": false,
            "properties": {
              "base": {
                "description": "EUR base as a decimal string.",
                "type": "string"
              },
              "rate": {
                "description": "VAT rate as a percentage string, 0 for a non-taxable line.",
                "type": "string"
              },
              "vat": {
                "description": "EUR VAT as a decimal string.",
                "type": "string"
              }
            },
            "required": [
              "rate",
              "base",
              "vat"
            ],
            "type": "object"
          },
          "maxItems": 10,
          "minItems": 1,
          "type": "array"
        },
        "vat_treatment": {
          "description": "VAT treatment. Non-taxable lines carry rate 0 and no VAT.",
          "enum": [
            "taxable",
            "exempt",
            "reverse_charge",
            "not_subject"
          ],
          "type": "string"
        }
      },
      "required": [
        "id",
        "expected_version"
      ],
      "type": "object"
    }
    ```
  </Accordion>
</AccordionGroup>

## Output

Income records or the result of the selected update or deletion. Read identifiers from the company’s current records.

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. The server does not currently declare an `outputSchema`, so treat additional fields as extensible. [Result handling](/mcp/results).

## Example

Use an OAuth access token issued for this MCP resource (a Run token for Run-only tools). Replace example identifiers with values from your own account. Write actions change data.

```bash theme={null}
curl --fail-with-body https://melso.ai/api/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": "income",
    "arguments": {
      "action": "list"
    }
  }
}
JSON
```


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