> ## 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. # gestiones > When to use the gestiones MCP tool, its input, actions, output and a worked example. Open and follow this company's cases with Melso's professionals: tax forms (modelo); for an autónomo, self-employed registration (alta) and annual income tax (renta); incorporating an S.L.; and any other kind that kinds lists with its details schema and price. Save drafts, send covered cases, exchange messages and documents, answer information requests and request changes. get includes the conversation, versions, request and documents, and for a case sold once what Melso paid on the customer's behalf and its invoice. Approving a version and paying a case sold once stay with the owner in the web app; no action files a return or pays. Monetary amounts are EUR decimal strings unless named in cents. Each action accepts only its own fields (\* required): list; get(id\*); kinds; create(kind\*, details\*, attachment\_ids, note, submit); submit(id\*); message(id\*, idempotency\_key\*, attachment\_ids, changes, content); answer(id\*, request\_id\*, answers\*); request\_approval(id\*); cancel(id\*); upload(filename\*, content\_type\*, size\_bytes\*); upload\_complete(upload\_id\*); document\_get(id\*, attachment\_id\*). **Availability:** Autónomo / Empresa. The live tool list is authoritative: the company's plan and your role can narrow this contract. [Understand access](/mcp/permissions). ## When to use Use it when the person needs Melso's professionals to do something: prepare and file a form (`modelo`), register as an autónomo (`alta`), the annual income tax return (`renta`) or incorporating an S.L. (`constitucion_sl`). Read `kinds` first: it says what this company can ask for, the `details` each kind needs and how it is paid. Then follow the case with `get`, answer what the professionals ask with `answer`, and give the owner the approval page with `request_approval`. A calculated return already has its own approval in `taxes`. ## Input ```json theme={null} { "additionalProperties": false, "properties": { "action": { "enum": [ "list", "get", "kinds", "create", "submit", "message", "answer", "request_approval", "cancel", "upload", "upload_complete", "document_get" ], "type": "string" }, "answers": { "items": { "additionalProperties": false, "properties": { "answer": { "description": "Answer to a question, at most 2000 characters.", "type": "string" }, "attachment_id": { "description": "Document item's attachment UUID from upload_complete, uploaded by this person.", "type": "string" }, "item_id": { "description": "Item ID in the open request from get.", "type": "string" } }, "required": [ "item_id" ], "type": "object" }, "maxItems": 20, "minItems": 1, "type": "array" }, "attachment_id": { "description": "Attachment UUID in the case's documents or versions from get.", "type": "string" }, "attachment_ids": { "description": "Attachment IDs from upload_complete or the web upload.", "items": { "description": "An attachment UUID uploaded by this person to this company, not yet filed in a case.", "type": "string" }, "maxItems": 20, "type": "array", "uniqueItems": true }, "changes": { "description": "Request changes to the current version awaiting approval; defaults to false.", "type": "boolean" }, "content": { "description": "Message, at most 20000 characters; may be empty when sending documents.", "type": "string" }, "content_type": { "enum": [ "application/pdf", "image/jpeg", "image/png", "image/webp", "image/gif" ], "type": "string" }, "details": { "description": "The kind's details, exactly as details_schema in kinds describes them.", "type": "object" }, "filename": { "description": "Plain file name, such as datos-fiscales.pdf.", "type": "string" }, "id": { "description": "Case UUID from list or get, belonging to this company.", "type": "string" }, "idempotency_key": { "description": "Unique message key, at most 200 characters. Reuse for a retry of this same message.", "type": "string" }, "kind": { "description": "A kind from kinds.", "enum": [ "modelo", "alta", "renta", "constitucion_sl" ], "type": "string" }, "note": { "description": "Initial note, at most 4000 characters.", "type": "string" }, "request_id": { "description": "Open information request UUID from get.", "type": "string" }, "size_bytes": { "description": "The file's exact size in bytes.", "maximum": 15728640, "minimum": 1, "type": "integer" }, "submit": { "description": "Send to Melso when covered, only when the person asked; defaults to false.", "type": "boolean" }, "upload_id": { "description": "Upload UUID from upload, after putting the file bytes.", "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. Read a document linked to this case, including a professional draft or receipt, as content\_base64 with filename and content\_type. Decode the bytes unchanged. At most 15 MB; larger documents are read in the authenticated web app. ```json theme={null} { "additionalProperties": false, "properties": { "attachment_id": { "description": "Attachment UUID in the case's documents or versions from get.", "type": "string" }, "id": { "description": "Case UUID from list or get, belonging to this company.", "type": "string" } }, "required": [ "id", "attachment_id" ], "type": "object" } ``` Read one case with its conversation, versions, pending information request and documents, including drafts and filing receipts. ```json theme={null} { "additionalProperties": false, "properties": { "id": { "description": "Case UUID from list or get, belonging to this company.", "type": "string" } }, "required": [ "id" ], "type": "object" } ``` List the kinds of case this company can open: what each is, its details\_schema (JSON Schema for create), whether the owner approves a draft, and how it is paid: payment.mode plan (included when payment.covered) or service (a one-off price, payment.amount\_cents in EUR cents, paid by the owner in the web app before it is sent). ```json theme={null} { "additionalProperties": false, "properties": {}, "type": "object" } ``` List the company's cases, newest first, with status, kind, deadlines, current and approved versions, filing reference and tax-service coverage. ```json theme={null} { "additionalProperties": false, "properties": {}, "type": "object" } ``` ### Case actions These actions save, send or withdraw a case, or exchange messages and documents with Melso's professionals. A draft needs no plan; sending a case needs a plan that covers it or, for a kind sold once, the owner's payment in the web app. None approves a version, files or pays. Answer every item in the case's open information request and send it back to review. Read get first for request\_id and item IDs; document items need an attachment and questions need an answer. ```json theme={null} { "additionalProperties": false, "properties": { "answers": { "items": { "additionalProperties": false, "properties": { "answer": { "description": "Answer to a question, at most 2000 characters.", "type": "string" }, "attachment_id": { "description": "Document item's attachment UUID from upload_complete, uploaded by this person.", "type": "string" }, "item_id": { "description": "Item ID in the open request from get.", "type": "string" } }, "required": [ "item_id" ], "type": "object" }, "maxItems": 20, "minItems": 1, "type": "array" }, "id": { "description": "Case UUID from list or get, belonging to this company.", "type": "string" }, "request_id": { "description": "Open information request UUID from get.", "type": "string" } }, "required": [ "id", "request_id", "answers" ], "type": "object" } ``` Withdraw a submitted case that Melso has not filed, after the person confirms. Preserves its conversation and documents. A linked authorized tax return goes back to draft and needs web authorization again. ```json theme={null} { "additionalProperties": false, "properties": { "id": { "description": "Case UUID from list or get, belonging to this company.", "type": "string" } }, "required": [ "id" ], "type": "object" } ``` Save a case draft of a kind from kinds, with details that match its details\_schema; a refused field is named in the error. submit=true sends a plan kind when the tax service covers it; otherwise it stays a draft. A service kind is sent once the owner pays in the web app: submit then returns payment\_url. Incorporating an S.L. (constitucion\_sl) asked from a company that is not in incorporation opens the S.L.'s own company and saves the draft there, returning that company and its payment\_url. This never accepts or approves a calculated return: use taxes request\_approval for its web authorization. After an uncertain response, read list before creating again. ```json theme={null} { "additionalProperties": false, "properties": { "attachment_ids": { "description": "Attachment IDs from upload_complete or the web upload.", "items": { "description": "An attachment UUID uploaded by this person to this company, not yet filed in a case.", "type": "string" }, "maxItems": 20, "type": "array", "uniqueItems": true }, "details": { "description": "The kind's details, exactly as details_schema in kinds describes them.", "type": "object" }, "kind": { "description": "A kind from kinds.", "enum": [ "modelo", "alta", "renta", "constitucion_sl" ], "type": "string" }, "note": { "description": "Initial note, at most 4000 characters.", "type": "string" }, "submit": { "description": "Send to Melso when covered, only when the person asked; defaults to false.", "type": "boolean" } }, "required": [ "kind", "details" ], "type": "object" } ``` Send the person's message or documents to a submitted case. Reuse idempotency\_key only for retries. changes=true requests changes to a version awaiting approval and returns the case to review. ```json theme={null} { "additionalProperties": false, "properties": { "attachment_ids": { "description": "Attachment IDs from upload_complete or the web upload.", "items": { "description": "An attachment UUID uploaded by this person to this company, not yet filed in a case.", "type": "string" }, "maxItems": 20, "type": "array", "uniqueItems": true }, "changes": { "description": "Request changes to the current version awaiting approval; defaults to false.", "type": "boolean" }, "content": { "description": "Message, at most 20000 characters; may be empty when sending documents.", "type": "string" }, "id": { "description": "Case UUID from list or get, belonging to this company.", "type": "string" }, "idempotency_key": { "description": "Unique message key, at most 200 characters. Reuse for a retry of this same message.", "type": "string" } }, "required": [ "id", "idempotency_key" ], "type": "object" } ``` Return the current case version and authenticated web page where the owner reviews and approves it. Share approval\_url. No MCP action approves, files or pays a return. ```json theme={null} { "additionalProperties": false, "properties": { "id": { "description": "Case UUID from list or get, belonging to this company.", "type": "string" } }, "required": [ "id" ], "type": "object" } ``` Send a saved draft to Melso when the person asked. A plan kind requires a plan covering the tax service. A service kind is not sent here: it returns payment\_required with the payment\_url where the owner pays in the web app, after which Melso receives it. Never approves a tax version or pays. ```json theme={null} { "additionalProperties": false, "properties": { "id": { "description": "Case UUID from list or get, belonging to this company.", "type": "string" } }, "required": [ "id" ], "type": "object" } ``` Reserve a local PDF or image of at most 15 MB: PUT its exact bytes to upload\_url with the returned headers, then call upload\_complete. Without file upload capability, share web\_upload\_url so the person provides it in Gestiones. ```json theme={null} { "additionalProperties": false, "properties": { "content_type": { "enum": [ "application/pdf", "image/jpeg", "image/png", "image/webp", "image/gif" ], "type": "string" }, "filename": { "description": "Plain file name, such as datos-fiscales.pdf.", "type": "string" }, "size_bytes": { "description": "The file's exact size in bytes.", "maximum": 15728640, "minimum": 1, "type": "integer" } }, "required": [ "filename", "content_type", "size_bytes" ], "type": "object" } ``` Finalize a file PUT through upload and return its attachment ID for create, message or answer. Checks the exact size, uploader and current company membership; does not send it to a case yet. ```json theme={null} { "additionalProperties": false, "properties": { "upload_id": { "description": "Upload UUID from upload, after putting the file bytes.", "type": "string" } }, "required": [ "upload_id" ], "type": "object" } ``` ## Output `list` returns the company's cases with their status, deadlines, versions and filing reference. `get` returns one case with its conversation, versions, open information request and documents, including drafts and filing receipts. `kinds` returns what the company can ask for, each with its `details_schema` and how it is paid. `create` and `submit` return the saved or sent case, or the `payment_url` where the owner pays a kind sold once. `request_approval` returns the current version and the `approval_url` where the owner approves it. `upload` returns an `upload_url` to PUT the file to and a `web_upload_url`; `upload_complete` returns the attachment ID. `document_get` returns a document as `content_base64` with its `filename` and `content_type`. No action approves a version, files a return or pays. 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 declare an `outputSchema`, so rely on the fields named here and in the live result. ## Example Ask Melso's professionals for the 2025 income tax return of an autónomo, then follow the case. These are the `arguments` of each call, in order. ```json theme={null} { "action": "kinds" } ``` ```json theme={null} { "action": "create", "kind": "renta", "details": { "year": 2025 }, "note": "Tengo un piso alquilado desde marzo.", "submit": true } ``` ```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. Write actions change data. ```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": "gestiones", "arguments": { "action": "kinds" } } } JSON ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.