> ## 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.

# taxes

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

The company's tax calendar and the returns Melso calculates (303, 130, 111, 115, 390 and the informative returns). Read and explain them; request\_approval gives the authenticated web link where the owner authorizes the exact version for Melso's professionals to review and file under the required authority. An unchanged authorized version proceeds; a changed draft needs new approval. Filing requires the actual external reference and receipt. An estimate (is\_preview) has no approval link. No action approves, files or pays a return. Each action accepts only its own fields (\* required): calendar; list; get(id\*); request\_approval(id\*); aeat\_file(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": [
        "calendar",
        "list",
        "get",
        "request_approval",
        "aeat_file"
      ],
      "type": "string"
    },
    "id": {
      "description": "Tax return UUID from list or calendar (filing_id), or an estimate's preview:<model>:<period> id from list.",
      "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="aeat_file">
    The 303, 130, 111 or 115 import file as content\_base64. Write the decoded bytes unchanged (ISO-8859-1) under filename. This is preparation, not authorization or proof of filing. Share approval\_url so the owner authorizes the exact version in the web app for Melso's professionals to review and file under the required authority; do not ask the owner or an agent to file the included return.

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "id": {
          "description": "Tax return UUID from list or calendar (filing_id).",
          "type": "string"
        }
      },
      "required": [
        "id"
      ],
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="calendar">
    What the company files and when: each form due from its fiscal profile and records, with its deadline, the last day to pay by direct debit, whether Melso calculates it (filing\_id links the return) or only reminds, and its status. Past deadlines appear while unfiled. The person marks a reminder filed at taxes\_url.

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

  <Accordion title="get">
    One calculated return with its boxes, the lines of an informative return, review codes and whether an AEAT import file exists. Use it to explain a figure to the person. An estimate (is\_preview) has only its amount.

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "id": {
          "description": "Tax return UUID from list or calendar (filing_id), or an estimate's preview:<model>:<period> id from list.",
          "type": "string"
        }
      },
      "required": [
        "id"
      ],
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="list">
    The returns Melso calculated, newest first: model, period, status (draft, reviewed, approved, filed), amount (negative to compensate or refund), deadlines and what to check before filing. Drafts are recalculated from the records while their window is open. is\_preview true marks an estimate (id preview:\<model>:\<period>) for a company without an active Pro or Plus tax service: no boxes, approval page or AEAT file.

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

  <Accordion title="request_approval">
    Answer the authenticated web link where the owner reviews the exact calculated return and authorizes its version. This starts a case for Melso's professionals to review and file with Hacienda under the required authority. An unchanged authorized version proceeds; a changed draft needs new approval. Filing is complete only with the actual external reference and receipt. Share approval\_url; no agent tool approves, files or pays a return. An estimate (is\_preview) has no approval page: it answers approval\_required false and no link; say it is an estimate.

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "id": {
          "description": "Tax return UUID from list or calendar (filing_id), or an estimate's preview:<model>:<period> id from list.",
          "type": "string"
        }
      },
      "required": [
        "id"
      ],
      "type": "object"
    }
    ```
  </Accordion>
</AccordionGroup>

## Output

Return records, calendar entries, an export, or the saved preview and human approval link. `aeat_file` produces an import file; it does not submit a return to the tax authority.

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": "taxes",
    "arguments": {
      "action": "list"
    }
  }
}
JSON
```


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