tools/list).
The live catalog is authoritative: company type, membership, plan, connected apps and execution context can narrow this contract. Understand access.
Input
Autónomo / Company schema
{
"additionalProperties": false,
"properties": {
"action": {
"enum": [
"get",
"update",
"set_registration",
"submit_setup"
],
"type": "string"
},
"activity_description": {
"description": "What they do, in their words.",
"type": "string"
},
"activity_type": {
"description": "Whether the activity is professional or a business.",
"enum": [
"profesional",
"empresarial"
],
"type": "string"
},
"address": {
"description": "Fiscal address: street, number, floor.",
"type": "string"
},
"city": {
"description": "Municipality.",
"type": "string"
},
"clear": {
"description": "Saved fields to empty, by name, only when the person asks to remove one. A null field is ignored; it never clears anything.",
"items": {
"enum": [
"tax_id",
"legal_name",
"trade_name",
"address",
"postal_code",
"city",
"province",
"tax_territory",
"vat_regime",
"activity_type",
"activity_description",
"iae_code",
"registration_status",
"registered_on",
"irpf_method",
"irpf_retention_rate",
"eu_operator",
"invoice_series",
"next_invoice_number",
"iban",
"vat_sii",
"vat_redeme",
"client_types"
],
"type": "string"
},
"type": "array"
},
"client_types": {
"description": "Who they invoice, every kind that applies: es_business (companies or self-employed in Spain: IRPF retention for a professional), es_individual (individuals in Spain), eu_business (businesses in other EU countries: ROI), non_eu_business (clients outside the EU: exported services, no Spanish VAT). Sending it replaces the list. Without eu_business, eu_operator is saved as false.",
"items": {
"enum": [
"es_business",
"es_individual",
"eu_business",
"non_eu_business"
],
"type": "string"
},
"type": "array"
},
"display_name": {
"description": "The person's own name in Melso, the one they want to be called. Not a fiscal field: the company's name follows trade_name, else legal_name.",
"type": "string"
},
"eu_operator": {
"description": "Whether they are registered as an intra-community operator (ROI) to invoice clients in other EU countries.",
"type": "boolean"
},
"iae_code": {
"description": "IAE heading (epígrafe), for example 763 or 843.1.",
"type": "string"
},
"iban": {
"description": "Bank account for collecting invoices. Ask for it with the first invoice, not during onboarding.",
"type": "string"
},
"invoice_series": {
"description": "Invoice series prefix.",
"type": "string"
},
"invoicing": {
"description": "Whether they issue their invoices with Melso. false when they use another invoicing program; Melso then hides invoice issuing. Requires workspace owner.",
"type": "boolean"
},
"irpf_method": {
"description": "Income tax method. Defaults to directa_simplificada.",
"enum": [
"directa_simplificada",
"directa_normal",
"modulos"
],
"type": "string"
},
"irpf_retention_rate": {
"description": "Income tax withheld on invoices, in percent. Defaults to 7 for a professional in the year of registration and the two after, 15 afterwards.",
"maximum": 100,
"minimum": 0,
"type": "number"
},
"legal_name": {
"description": "Fiscal name: the full name on the DNI or NIE, or the company's registered name.",
"type": "string"
},
"next_invoice_number": {
"description": "Number of the next invoice in the series.",
"minimum": 1,
"type": "integer"
},
"postal_code": {
"description": "Five-digit Spanish postal code. Sets the province and the tax territory.",
"type": "string"
},
"province": {
"description": "Province. Normally deduced from the postal code.",
"type": "string"
},
"registered": {
"description": "true when already registered as self-employed, or the company already exists; false when Melso should register them or incorporate the SL.",
"type": "boolean"
},
"registered_on": {
"description": "When they registered as self-employed: YYYY-MM with the month they give (the day is never needed, never ask for it), or YYYY-MM-DD only when they said the day.",
"type": "string"
},
"registration_status": {
"description": "alta when already registered as self-employed, pendiente when not yet.",
"enum": [
"alta",
"pendiente"
],
"type": "string"
},
"setup": {
"additionalProperties": false,
"description": "Only when the turn's setup state or fiscal_profile_get shows a setup: registration and company details that are not fiscal profile fields, for its setup.kind: register_autonomo (alta de autónomo), incorporate_sl (a new SL) or company (an existing company). Send only details of that setup, as the person gives them; an empty value clears one, a null is ignored. Refused details are named under errors as setup.<name>.",
"properties": {
"activity_address": {
"description": "Where the activity happens, only when it is not the fiscal address.",
"type": "string"
},
"administration": {
"description": "Sole director (unico), joint and several (solidarios), joint (mancomunados) or a board (consejo).",
"enum": [
"unico",
"solidarios",
"mancomunados",
"consejo"
],
"type": "string"
},
"administrators": {
"description": "Who the directors are: names and DNI/NIE.",
"type": "string"
},
"birth_date": {
"description": "Birth date, YYYY-MM-DD.",
"type": "string"
},
"clients": {
"description": "Who they expect to invoice: companies or self-employed in Spain, individuals, clients in other EU countries or outside the EU.",
"type": "string"
},
"cnae": {
"description": "CNAE activity code, when they know it; 'no_lo_se' otherwise.",
"type": "string"
},
"company_form": {
"description": "sl or slu (single partner).",
"enum": [
"sl",
"slu"
],
"type": "string"
},
"contribution": {
"description": "How the capital is paid: dineraria (money), no_dineraria (assets) or mixta.",
"enum": [
"dineraria",
"no_dineraria",
"mixta"
],
"type": "string"
},
"corporate_purpose": {
"description": "What the company will do.",
"type": "string"
},
"denominations": {
"description": "Up to 5 proposed company names, in order of preference.",
"items": {
"type": "string"
},
"maxItems": 5,
"type": "array"
},
"email": {
"description": "Contact email.",
"type": "string"
},
"employees": {
"description": "How many employees the company has, 0 when none.",
"type": "string"
},
"invoicing_by": {
"description": "Who issues the company's invoices today and with which program.",
"type": "string"
},
"notary_city": {
"description": "City where they prefer to sign at the notary.",
"type": "string"
},
"nuss": {
"description": "Social Security number (NUSS), 12 digits.",
"type": "string"
},
"partners": {
"description": "Every partner: name, tax_id (DNI, NIE or CIF) and share (percentage of the capital). The shares add up to 100.",
"items": {
"additionalProperties": false,
"properties": {
"name": {
"type": "string"
},
"share": {
"maximum": 100,
"minimum": 0,
"type": "number"
},
"tax_id": {
"type": "string"
}
},
"required": [
"name",
"tax_id",
"share"
],
"type": "object"
},
"type": "array"
},
"phone": {
"description": "Contact phone.",
"type": "string"
},
"registered_address": {
"description": "Registered address of the company, with postal code and city.",
"type": "string"
},
"share_capital": {
"description": "Share capital in euros, for example 3000.",
"type": "string"
},
"starts_on": {
"description": "Planned start date of the activity, YYYY-MM-DD.",
"type": "string"
},
"tarifa_plana": {
"description": "Whether they want the reduced flat-rate quota (tarifa plana) if they qualify: si, no, or no_se when unsure.",
"enum": [
"si",
"no",
"no_se"
],
"type": "string"
},
"timing": {
"description": "When they need the company, for example 'this month' or a date.",
"type": "string"
}
},
"type": "object"
},
"tax_id": {
"description": "NIF: a DNI, a NIE or a CIF, as written by the person. The control character is checked.",
"type": "string"
},
"tax_territory": {
"description": "Tax territory. Normally deduced from the postal code; set it only to correct that.",
"enum": [
"comun",
"alava",
"bizkaia",
"gipuzkoa",
"navarra",
"canarias",
"ceuta",
"melilla"
],
"type": "string"
},
"trade_name": {
"description": "Commercial name, when different from the fiscal name.",
"type": "string"
},
"vat_redeme": {
"description": "Whether they are in the monthly VAT refund register (REDEME), which means filing VAT monthly.",
"type": "boolean"
},
"vat_regime": {
"description": "Indirect tax regime. Defaults to general VAT, IGIC in the Canary Islands and IPSI in Ceuta and Melilla. reagp is the farming, livestock and fishing regime; exento is for activities that are all VAT-exempt (healthcare, education, insurance); igic_simplificado and igic_repep (the small-business franchise) only apply in the Canary Islands.",
"enum": [
"general",
"recargo_equivalencia",
"simplificado",
"reagp",
"exento",
"igic_general",
"igic_simplificado",
"igic_repep",
"ipsi"
],
"type": "string"
},
"vat_sii": {
"description": "Whether they keep their VAT books in the AEAT's SII (Suministro Inmediato de Información), compulsory for large companies and optional otherwise. In the Canary Islands, the SII-IGIC.",
"type": "boolean"
}
},
"required": [
"action"
],
"type": "object"
}
Actions
The family schema combines fields for discovery. Each action accepts only its own fields below; addaction when calling the family.
get
get
Read the company’s fiscal profile: what is saved, which required fields are still missing, and the onboarding state. Requires workspace owner or admin.OAuth-only.
{
"additionalProperties": false,
"properties": {},
"type": "object"
}
set_registration
set_registration
Save the answer to the one registration question setup asks early, once: is the self-employed person already registered (dado de alta), or is the company already incorporated (sociedad constituida)? registered=false asks Melso to do it: setup then collects the alta de autónomo or the SL incorporation details. The turn context and workspace capabilities (registration) say when it is already answered; never ask again then. Requires workspace owner or admin.OAuth-only.
{
"additionalProperties": false,
"properties": {
"registered": {
"description": "true when already registered as self-employed, or the company already exists; false when Melso should register them or incorporate the SL.",
"type": "boolean"
}
},
"required": [
"registered"
],
"type": "object"
}
submit_setup
submit_setup
Send the registration the person asked Melso for (setup.request register_autonomo or incorporate_sl) to Melso’s gestores, once setup.missing is empty and the person confirmed the summary. Files one support ticket with every detail; calling it again answers the one already sent. Melso people then do the registration and write to the person. Requires workspace owner or admin.OAuth-only.
{
"additionalProperties": false,
"properties": {},
"type": "object"
}
update
update
Save fiscal profile fields as the person gives them; send only what you learned, every field from one message together in one call (profile fields, invoicing and setup details). A null field is ignored: to empty a saved field, name it in clear. The answer is the whole profile with what is missing, so never call get after it. Every valid field is saved even when another is refused:
errors names each refused field and why, deduced names what the server filled in from the rest (province, tax territory, VAT regime, income tax method, retention, invoice series) so you can confirm it with the person, and missing is what is still required. Requires workspace owner or admin.OAuth-only.{
"additionalProperties": false,
"properties": {
"activity_description": {
"description": "What they do, in their words.",
"type": "string"
},
"activity_type": {
"description": "Whether the activity is professional or a business.",
"enum": [
"profesional",
"empresarial"
],
"type": "string"
},
"address": {
"description": "Fiscal address: street, number, floor.",
"type": "string"
},
"city": {
"description": "Municipality.",
"type": "string"
},
"clear": {
"description": "Saved fields to empty, by name, only when the person asks to remove one. A null field is ignored; it never clears anything.",
"items": {
"enum": [
"tax_id",
"legal_name",
"trade_name",
"address",
"postal_code",
"city",
"province",
"tax_territory",
"vat_regime",
"activity_type",
"activity_description",
"iae_code",
"registration_status",
"registered_on",
"irpf_method",
"irpf_retention_rate",
"eu_operator",
"invoice_series",
"next_invoice_number",
"iban",
"vat_sii",
"vat_redeme",
"client_types"
],
"type": "string"
},
"type": "array"
},
"client_types": {
"description": "Who they invoice, every kind that applies: es_business (companies or self-employed in Spain: IRPF retention for a professional), es_individual (individuals in Spain), eu_business (businesses in other EU countries: ROI), non_eu_business (clients outside the EU: exported services, no Spanish VAT). Sending it replaces the list. Without eu_business, eu_operator is saved as false.",
"items": {
"enum": [
"es_business",
"es_individual",
"eu_business",
"non_eu_business"
],
"type": "string"
},
"type": "array"
},
"display_name": {
"description": "The person's own name in Melso, the one they want to be called. Not a fiscal field: the company's name follows trade_name, else legal_name.",
"type": "string"
},
"eu_operator": {
"description": "Whether they are registered as an intra-community operator (ROI) to invoice clients in other EU countries.",
"type": "boolean"
},
"iae_code": {
"description": "IAE heading (epígrafe), for example 763 or 843.1.",
"type": "string"
},
"iban": {
"description": "Bank account for collecting invoices. Ask for it with the first invoice, not during onboarding.",
"type": "string"
},
"invoice_series": {
"description": "Invoice series prefix.",
"type": "string"
},
"invoicing": {
"description": "Whether they issue their invoices with Melso. false when they use another invoicing program; Melso then hides invoice issuing. Requires workspace owner.",
"type": "boolean"
},
"irpf_method": {
"description": "Income tax method. Defaults to directa_simplificada.",
"enum": [
"directa_simplificada",
"directa_normal",
"modulos"
],
"type": "string"
},
"irpf_retention_rate": {
"description": "Income tax withheld on invoices, in percent. Defaults to 7 for a professional in the year of registration and the two after, 15 afterwards.",
"maximum": 100,
"minimum": 0,
"type": "number"
},
"legal_name": {
"description": "Fiscal name: the full name on the DNI or NIE, or the company's registered name.",
"type": "string"
},
"next_invoice_number": {
"description": "Number of the next invoice in the series.",
"minimum": 1,
"type": "integer"
},
"postal_code": {
"description": "Five-digit Spanish postal code. Sets the province and the tax territory.",
"type": "string"
},
"province": {
"description": "Province. Normally deduced from the postal code.",
"type": "string"
},
"registered_on": {
"description": "When they registered as self-employed: YYYY-MM with the month they give (the day is never needed, never ask for it), or YYYY-MM-DD only when they said the day.",
"type": "string"
},
"registration_status": {
"description": "alta when already registered as self-employed, pendiente when not yet.",
"enum": [
"alta",
"pendiente"
],
"type": "string"
},
"setup": {
"additionalProperties": false,
"description": "Only when the turn's setup state or fiscal_profile_get shows a setup: registration and company details that are not fiscal profile fields, for its setup.kind: register_autonomo (alta de autónomo), incorporate_sl (a new SL) or company (an existing company). Send only details of that setup, as the person gives them; an empty value clears one, a null is ignored. Refused details are named under errors as setup.<name>.",
"properties": {
"activity_address": {
"description": "Where the activity happens, only when it is not the fiscal address.",
"type": "string"
},
"administration": {
"description": "Sole director (unico), joint and several (solidarios), joint (mancomunados) or a board (consejo).",
"enum": [
"unico",
"solidarios",
"mancomunados",
"consejo"
],
"type": "string"
},
"administrators": {
"description": "Who the directors are: names and DNI/NIE.",
"type": "string"
},
"birth_date": {
"description": "Birth date, YYYY-MM-DD.",
"type": "string"
},
"clients": {
"description": "Who they expect to invoice: companies or self-employed in Spain, individuals, clients in other EU countries or outside the EU.",
"type": "string"
},
"cnae": {
"description": "CNAE activity code, when they know it; 'no_lo_se' otherwise.",
"type": "string"
},
"company_form": {
"description": "sl or slu (single partner).",
"enum": [
"sl",
"slu"
],
"type": "string"
},
"contribution": {
"description": "How the capital is paid: dineraria (money), no_dineraria (assets) or mixta.",
"enum": [
"dineraria",
"no_dineraria",
"mixta"
],
"type": "string"
},
"corporate_purpose": {
"description": "What the company will do.",
"type": "string"
},
"denominations": {
"description": "Up to 5 proposed company names, in order of preference.",
"items": {
"type": "string"
},
"maxItems": 5,
"type": "array"
},
"email": {
"description": "Contact email.",
"type": "string"
},
"employees": {
"description": "How many employees the company has, 0 when none.",
"type": "string"
},
"invoicing_by": {
"description": "Who issues the company's invoices today and with which program.",
"type": "string"
},
"notary_city": {
"description": "City where they prefer to sign at the notary.",
"type": "string"
},
"nuss": {
"description": "Social Security number (NUSS), 12 digits.",
"type": "string"
},
"partners": {
"description": "Every partner: name, tax_id (DNI, NIE or CIF) and share (percentage of the capital). The shares add up to 100.",
"items": {
"additionalProperties": false,
"properties": {
"name": {
"type": "string"
},
"share": {
"maximum": 100,
"minimum": 0,
"type": "number"
},
"tax_id": {
"type": "string"
}
},
"required": [
"name",
"tax_id",
"share"
],
"type": "object"
},
"type": "array"
},
"phone": {
"description": "Contact phone.",
"type": "string"
},
"registered_address": {
"description": "Registered address of the company, with postal code and city.",
"type": "string"
},
"share_capital": {
"description": "Share capital in euros, for example 3000.",
"type": "string"
},
"starts_on": {
"description": "Planned start date of the activity, YYYY-MM-DD.",
"type": "string"
},
"tarifa_plana": {
"description": "Whether they want the reduced flat-rate quota (tarifa plana) if they qualify: si, no, or no_se when unsure.",
"enum": [
"si",
"no",
"no_se"
],
"type": "string"
},
"timing": {
"description": "When they need the company, for example 'this month' or a date.",
"type": "string"
}
},
"type": "object"
},
"tax_id": {
"description": "NIF: a DNI, a NIE or a CIF, as written by the person. The control character is checked.",
"type": "string"
},
"tax_territory": {
"description": "Tax territory. Normally deduced from the postal code; set it only to correct that.",
"enum": [
"comun",
"alava",
"bizkaia",
"gipuzkoa",
"navarra",
"canarias",
"ceuta",
"melilla"
],
"type": "string"
},
"trade_name": {
"description": "Commercial name, when different from the fiscal name.",
"type": "string"
},
"vat_redeme": {
"description": "Whether they are in the monthly VAT refund register (REDEME), which means filing VAT monthly.",
"type": "boolean"
},
"vat_regime": {
"description": "Indirect tax regime. Defaults to general VAT, IGIC in the Canary Islands and IPSI in Ceuta and Melilla. reagp is the farming, livestock and fishing regime; exento is for activities that are all VAT-exempt (healthcare, education, insurance); igic_simplificado and igic_repep (the small-business franchise) only apply in the Canary Islands.",
"enum": [
"general",
"recargo_equivalencia",
"simplificado",
"reagp",
"exento",
"igic_general",
"igic_simplificado",
"igic_repep",
"ipsi"
],
"type": "string"
},
"vat_sii": {
"description": "Whether they keep their VAT books in the AEAT's SII (Suministro Inmediato de Información), compulsory for large companies and optional otherwise. In the Canary Islands, the SII-IGIC.",
"type": "boolean"
}
},
"type": "object"
}
Output
The fiscal profile or the result of saving registration/setup information. The app remains the place for human fiscal approval. The result uses MCPcontent 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.
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.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": "fiscal_profile",
"arguments": {
"action": "get"
}
}
}
JSON