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

# customers

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

Read and save this company's invoice customers. Updating a customer never changes an issued invoice's frozen snapshot. Each action accepts only its own fields (\* required): list; upsert(name\*, kind\*, address, country, email, id, tax\_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",
        "upsert"
      ],
      "type": "string"
    },
    "address": {
      "description": "Postal address.",
      "type": "string"
    },
    "country": {
      "description": "ISO country code, defaults to ES.",
      "type": "string"
    },
    "email": {
      "description": "Recipient email.",
      "type": "string"
    },
    "id": {
      "description": "Existing customer UUID to update; omit to create.",
      "type": "string"
    },
    "kind": {
      "enum": [
        "company",
        "professional",
        "individual"
      ],
      "type": "string"
    },
    "name": {
      "description": "Name or legal name.",
      "type": "string"
    },
    "tax_id": {
      "description": "Customer NIF or VAT ID.",
      "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="list">
    Find existing customers in the workspace before preparing an invoice.

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

  <Accordion title="upsert">
    Create or update a customer in this workspace. Pass id to update; never changes an issued invoice's stored customer snapshot.

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "address": {
          "description": "Postal address.",
          "type": "string"
        },
        "country": {
          "description": "ISO country code, defaults to ES.",
          "type": "string"
        },
        "email": {
          "description": "Recipient email.",
          "type": "string"
        },
        "id": {
          "description": "Existing customer UUID to update; omit to create.",
          "type": "string"
        },
        "kind": {
          "enum": [
            "company",
            "professional",
            "individual"
          ],
          "type": "string"
        },
        "name": {
          "description": "Name or legal name.",
          "type": "string"
        },
        "tax_id": {
          "description": "Customer NIF or VAT ID.",
          "type": "string"
        }
      },
      "required": [
        "name",
        "kind"
      ],
      "type": "object"
    }
    ```
  </Accordion>
</AccordionGroup>

## Output

For `list`, the company’s customers; for `upsert`, the saved customer record and its identifier for invoice preparation.

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


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