Use cases

Each use case below starts from something a person asks and lists the calls an assistant makes, in order. Every example is a tools/call request body. The identifiers are placeholders: use the ones your own company returns. The connection lists only the tools and actions the company’s plan, your role and the setup state allow. If a call here is not listed for you, read Permissions and approvals.

The person asks	Tools
Which company is this?	`company`
Record this receipt	`expenses`
Add this expense by hand	`expenses`
Draft an invoice for a customer	`customers`, `invoices`
Correct an issued invoice	`invoices`
This invoice was paid	`payments`
What is due this quarter?	`taxes`
Explain my 303 and let me approve it	`taxes`
Give me the AEAT import file	`taxes`
Fix this record	`expenses`, `income`
Delete this duplicate	`expenses`, `income`
Finish my fiscal profile	`fiscal_profile`
Report a problem	`support_tickets_create`

Confirm the company

Do this first on every new connection. company takes no arguments and changes nothing.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "company",
    "arguments": {}
  }
}

Check name and kind with the person. kind is freelancer for an autónomo and company for an empresa. If the answer has onboarding, the autónomo’s setup is pending: go to Complete the fiscal profile.

Record a receipt or a supplier invoice

Use expenses. The file goes to Melso in three calls.

Ask for an upload link

Send the file’s name, type and exact size. Accepted types are PDF, JPEG, PNG, WebP and GIF, up to 15 MB.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "expenses",
    "arguments": {
      "action": "upload",
      "filename": "factura-0142.pdf",
      "content_type": "application/pdf",
      "size_bytes": 48211
    }
  }
}

The answer has upload_id, upload_url, the headers to send, expires_at and web_upload_url.

PUT the file to upload_url

Send the file’s exact bytes with the returned headers. This request goes to the upload link, not to the MCP endpoint.

Read the uploaded file

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "expenses",
    "arguments": {
      "action": "from_document",
      "upload_id": "11111111-1111-4111-8111-111111111111"
    }
  }
}

The file is read in the background. The answer has a job_id.

See what it became

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "expenses",
    "arguments": {
      "action": "document_status",
      "job_id": "11111111-1111-4111-8111-111111111111"
    }
  }
}

The job is queued, done or failed. A finished job names the expense or the income it recorded, with its review codes.

Two failures ask you for something:

direction_unknown: ask whether the company issued or received the document, then queue it again with direction.
country_unknown: ask the supplier’s or customer’s country, then retry with counterparty_country and the direction the error names.

Queue the document again with what the person answered:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "expenses",
    "arguments": {
      "action": "from_document",
      "upload_id": "11111111-1111-4111-8111-111111111111",
      "direction": "expense",
      "counterparty_country": "FR"
    }
  }
}

A client that cannot upload files shares web_upload_url instead. The person drops the files in the web app.

Record an expense from its details

When there is no file, record the expense by hand. total must equal subtotal plus vat_amount. Leave category out when you are not sure.

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "expenses",
    "arguments": {
      "action": "create",
      "supplier_name": "Example Telecom SA",
      "supplier_tax_id": "A00000000",
      "date": "2026-10-02",
      "subtotal": "40.00",
      "vat_amount": "8.40",
      "vat_rate": "21",
      "total": "48.40",
      "category": "G17"
    }
  }
}

deductible defaults to unsure. It is a classification, not approval of a deduction.

Draft an invoice for a customer

Use customers and invoices.

Find the customer

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "customers",
    "arguments": {
      "action": "list"
    }
  }
}

Save the customer if they are new

{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "tools/call",
  "params": {
    "name": "customers",
    "arguments": {
      "action": "upsert",
      "name": "Example Studio SL",
      "kind": "company",
      "tax_id": "B00000000",
      "address": "Calle Mayor 1, 28013 Madrid",
      "email": "billing@example.com"
    }
  }
}

Save an unnumbered draft

{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "tools/call",
  "params": {
    "name": "invoices",
    "arguments": {
      "action": "prepare",
      "customer_id": "11111111-1111-4111-8111-111111111111",
      "issue_date": "2026-10-13",
      "due_date": "2026-11-12",
      "irpf_rate": "15",
      "lines": [
        {
          "description": "Design work, October",
          "quantity": "1",
          "unit_price": "1200.00",
          "vat_rate": "21"
        }
      ]
    }
  }
}

irpf_rate is for an autónomo who is a professional. A company’s invoice leaves it out. To change the draft before it is approved, call prepare again with the draft’s id.

Get the approval page

{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "invoices",
    "arguments": {
      "action": "request_approval",
      "id": "11111111-1111-4111-8111-111111111111"
    }
  }
}

Show the person the preview and the approval_url. The owner issues the invoice there, in the signed-in web app.

Check the outcome later

{
  "jsonrpc": "2.0",
  "id": 11,
  "method": "tools/call",
  "params": {
    "name": "invoices",
    "arguments": {
      "action": "get",
      "id": "11111111-1111-4111-8111-111111111111"
    }
  }
}

request_approval returns a link, not an outcome. Do not say the invoice was issued until get shows it.

Correct an issued invoice

An issued invoice cannot be edited. correct prepares a corrective draft with the differences. A negative unit_price credits the original and a positive one increases it. The reason goes in notes, and it is required.

{
  "jsonrpc": "2.0",
  "id": 12,
  "method": "tools/call",
  "params": {
    "name": "invoices",
    "arguments": {
      "action": "correct",
      "invoice_id": "11111111-1111-4111-8111-111111111111",
      "customer_id": "11111111-1111-4111-8111-111111111111",
      "issue_date": "2026-10-13",
      "notes": "Full credit: the work was cancelled.",
      "lines": [
        {
          "description": "Design work, October",
          "quantity": "1",
          "unit_price": "-1200.00",
          "vat_rate": "21"
        }
      ]
    }
  }
}

The original stays as it was. Then call request_approval with the corrective draft’s id, as in the previous use case.

Record a payment received

Use payments once the person confirms the invoice was paid in full.

{
  "jsonrpc": "2.0",
  "id": 13,
  "method": "tools/call",
  "params": {
    "name": "payments",
    "arguments": {
      "action": "mark_paid",
      "id": "11111111-1111-4111-8111-111111111111"
    }
  }
}

It records money already received. It does not charge a card or move money, and there is no partial payment.

What is due this quarter

Use taxes.

{
  "jsonrpc": "2.0",
  "id": 14,
  "method": "tools/call",
  "params": {
    "name": "taxes",
    "arguments": {
      "action": "calendar"
    }
  }
}

Each entry has the form, its deadline, the last day to pay by direct debit and its status. It also says whether Melso calculates the form or only reminds. A calculated form carries a filing_id that links its return. For the amounts, list the calculated returns:

{
  "jsonrpc": "2.0",
  "id": 15,
  "method": "tools/call",
  "params": {
    "name": "taxes",
    "arguments": {
      "action": "list"
    }
  }
}

A return with is_preview true is an estimate. It has an amount only: no boxes, no approval page and no import file.

Explain a return and hand over its approval

Read the return

{
  "jsonrpc": "2.0",
  "id": 16,
  "method": "tools/call",
  "params": {
    "name": "taxes",
    "arguments": {
      "action": "get",
      "id": "11111111-1111-4111-8111-111111111111"
    }
  }
}

Use the boxes and the review codes to explain each figure.

Get the approval page

{
  "jsonrpc": "2.0",
  "id": 17,
  "method": "tools/call",
  "params": {
    "name": "taxes",
    "arguments": {
      "action": "request_approval",
      "id": "11111111-1111-4111-8111-111111111111"
    }
  }
}

Share approval_url. The owner authorizes the exact version there. For an estimate the answer has approval_required false and no link: say it is an estimate.

Authorization opens a case for Melso’s professionals to review and file. Do not tell the person the return is filed until its status is filed. Do not ask them to file an included return themselves.

Get the AEAT import file

Available for the 303, 130, 111 and 115.

{
  "jsonrpc": "2.0",
  "id": 18,
  "method": "tools/call",
  "params": {
    "name": "taxes",
    "arguments": {
      "action": "aeat_file",
      "id": "11111111-1111-4111-8111-111111111111"
    }
  }
}

The answer has filename, content_type and content_base64. Write the decoded bytes unchanged. The file is preparation: it is not an authorization and not proof of filing.

Fix a record

Read the record first. update needs the expected_version you read, and a stale version is refused.

{
  "jsonrpc": "2.0",
  "id": 19,
  "method": "tools/call",
  "params": {
    "name": "expenses",
    "arguments": {
      "action": "get",
      "id": "11111111-1111-4111-8111-111111111111"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 20,
  "method": "tools/call",
  "params": {
    "name": "expenses",
    "arguments": {
      "action": "update",
      "id": "11111111-1111-4111-8111-111111111111",
      "expected_version": 3,
      "supplier_tax_id": "A00000000",
      "deductible": "yes"
    }
  }
}

Income works the same way. vat_lines replaces every current line.

{
  "jsonrpc": "2.0",
  "id": 21,
  "method": "tools/call",
  "params": {
    "name": "income",
    "arguments": {
      "action": "update",
      "id": "11111111-1111-4111-8111-111111111111",
      "expected_version": 1,
      "customer_name": "Example Studio SL",
      "vat_lines": [
        {
          "rate": "21",
          "base": "1000.00",
          "vat": "210.00"
        }
      ]
    }
  }
}

Updating an expense clears its review codes and resets any earlier review.

Delete a duplicate

Ask the person to confirm first.

{
  "jsonrpc": "2.0",
  "id": 22,
  "method": "tools/call",
  "params": {
    "name": "expenses",
    "arguments": {
      "action": "delete",
      "id": "11111111-1111-4111-8111-111111111111"
    }
  }
}

The file stays in the company’s documents. The call is refused when a tax return that covers the record’s date was already approved or filed. Do not retry it: the person makes that correction in the web app.

Complete the fiscal profile

Use fiscal_profile. It is listed for the company’s owner or an admin, and it is the tool to use while an autónomo’s setup is pending.

See what is missing

{
  "jsonrpc": "2.0",
  "id": 23,
  "method": "tools/call",
  "params": {
    "name": "fiscal_profile",
    "arguments": {
      "action": "get"
    }
  }
}

Save whether they are already registered

{
  "jsonrpc": "2.0",
  "id": 24,
  "method": "tools/call",
  "params": {
    "name": "fiscal_profile",
    "arguments": {
      "action": "set_registration",
      "registered": true
    }
  }
}

Save what the person told you

Send every field from one message in one call.

{
  "jsonrpc": "2.0",
  "id": 25,
  "method": "tools/call",
  "params": {
    "name": "fiscal_profile",
    "arguments": {
      "action": "update",
      "tax_id": "00000000T",
      "legal_name": "Example Person",
      "address": "Calle Mayor 1, 2B",
      "postal_code": "28013",
      "city": "Madrid",
      "activity_type": "profesional",
      "activity_description": "Graphic design for companies",
      "registered_on": "2024-03",
      "client_types": [
        "es_business"
      ]
    }
  }
}

The answer is the whole profile. errors names each refused field, deduced names what the server filled in so you can confirm it, and missing lists what is still required. Valid fields are saved even when another is refused.

An empresa has no guided setup, and the Melso team sets it up. An autónomo can also finish in the web app’s guided setup. See Setup and fiscal profile.

Report a problem or ask for work

Use support_tickets_create.

{
  "jsonrpc": "2.0",
  "id": 26,
  "method": "tools/call",
  "params": {
    "name": "support_tickets_create",
    "arguments": {
      "title": "The 303 draft misses an invoice",
      "type": "bug",
      "severity": "degraded",
      "description": "The third quarter 303 does not count an invoice issued on 28 September."
    }
  }
}

For work that no tool covers, such as a registration, use service_request and put every detail in the description.

{
  "jsonrpc": "2.0",
  "id": 27,
  "method": "tools/call",
  "params": {
    "name": "support_tickets_create",
    "arguments": {
      "title": "Change the activity on my registration",
      "type": "service_request",
      "description": "I added a second activity in September and need it reflected in my registration."
    }
  }
}

Filing the same title again within 24 hours returns the ticket already filed. Never put passwords, certificates or other secrets in a ticket.

Connect

Use

Reference

Tools

Confirm the company

Record a receipt or a supplier invoice

Record an expense from its details

Draft an invoice for a customer

Correct an issued invoice

Record a payment received

What is due this quarter

Explain a return and hand over its approval

Get the AEAT import file

Fix a record

Delete a duplicate

Complete the fiscal profile

Report a problem or ask for work

​Confirm the company

​Record a receipt or a supplier invoice

​Record an expense from its details

​Draft an invoice for a customer

​Correct an issued invoice

​Record a payment received

​What is due this quarter

​Explain a return and hand over its approval

​Get the AEAT import file

​Fix a record

​Delete a duplicate

​Complete the fiscal profile

​Report a problem or ask for work

Confirm the company

Record a receipt or a supplier invoice

Record an expense from its details

Draft an invoice for a customer

Correct an issued invoice

Record a payment received

What is due this quarter

Explain a return and hand over its approval

Get the AEAT import file

Fix a record

Delete a duplicate

Complete the fiscal profile

Report a problem or ask for work