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

# Consultar clientes y proveedores — contacts_read MCP

> MCP contacts_read: list customers and suppliers for this company. Live in the app and MCP.

Read-only actions. The company's contacts: its customers and suppliers, one per counterparty, with the fiscal details the person, you or a document gave once (tax ID, address, email, phone, a supplier's IBAN). Look one up before asking for its details, and save what the person tells you. Reading an invoice or receipt with expenses from\_document saves its supplier or customer too, never over what a contact already holds. Changing a contact never changes an issued invoice's frozen customer. Each action accepts only its own fields (\* required): list(limit, q, role); get(id\*).

**Availability:** Autónomo / Empresa.

**Access:** Live in the Melso app and over MCP for a signed-in person. Where the partner REST API covers the same area, that path is private beta until Melso enables your account. See [Access and pricing](https://docs.melso.ai/api/access.md).

The live tool list is authoritative: the company's plan and your role can narrow this contract. [Understand access](https://docs.melso.ai/mcp/permissions.md).

## When to use

Use `contacts_read` for `get`, `list`. Use [`contacts`](https://docs.melso.ai/mcp/tools/contacts) for the companion actions. The live tool list determines availability.

## Input

```json theme={null}
{
  "additionalProperties": false,
  "oneOf": [
    {
      "additionalProperties": false,
      "properties": {
        "action": {
          "const": "list"
        },
        "limit": {
          "description": "At most this many, 50 by default; truncated says there are more.",
          "maximum": 200,
          "minimum": 1,
          "type": "integer"
        },
        "q": {
          "description": "Words of the name, email or city, or the tax ID.",
          "type": "string"
        },
        "role": {
          "description": "Only customers or only suppliers; omit for both.",
          "enum": [
            "customer",
            "supplier"
          ],
          "type": "string"
        }
      },
      "required": [
        "action"
      ],
      "type": "object"
    },
    {
      "additionalProperties": false,
      "properties": {
        "action": {
          "const": "get"
        },
        "id": {
          "description": "The contact's id, from list.",
          "type": "string"
        }
      },
      "required": [
        "action",
        "id"
      ],
      "type": "object"
    }
  ],
  "properties": {
    "action": {
      "enum": [
        "list",
        "get"
      ],
      "type": "string"
    },
    "id": {
      "description": "The contact's id, from list.",
      "type": "string"
    },
    "limit": {
      "description": "At most this many, 50 by default; truncated says there are more.",
      "maximum": 200,
      "minimum": 1,
      "type": "integer"
    },
    "q": {
      "description": "Words of the name, email or city, or the tax ID.",
      "type": "string"
    },
    "role": {
      "description": "Only customers or only suppliers; omit for both.",
      "enum": [
        "customer",
        "supplier"
      ],
      "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.

> [accordion] get
>
> Read one contact with the company's invoices, income and expenses that name it, the latest hundred of each.
>
> ```json theme={null}
> {
>   "additionalProperties": false,
>   "properties": {
>     "id": {
>       "description": "The contact's id, from list.",
>       "type": "string"
>     }
>   },
>   "required": [
>     "id"
>   ],
>   "type": "object"
> }
> ```

> [accordion] list
>
> List the company's contacts by name, its customers and suppliers, each with its tax ID, address, email, phone and IBAN. Look a customer or supplier up here before asking the person for its details.
>
> ```json theme={null}
> {
>   "additionalProperties": false,
>   "properties": {
>     "limit": {
>       "description": "At most this many, 50 by default; truncated says there are more.",
>       "maximum": 200,
>       "minimum": 1,
>       "type": "integer"
>     },
>     "q": {
>       "description": "Words of the name, email or city, or the tax ID.",
>       "type": "string"
>     },
>     "role": {
>       "description": "Only customers or only suppliers; omit for both.",
>       "enum": [
>         "customer",
>         "supplier"
>       ],
>       "type": "string"
>     }
>   },
>   "type": "object"
> }
> ```

## Output

`list` returns matching customers and suppliers and whether the list was truncated. `get` returns the contact and its latest invoices, income and expenses.

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. When the server declares an `outputSchema`, it is reproduced below. Check the action result and its declared fields before reporting success.

### Declared output schema

```json theme={null}
{
  "anyOf": [
    {
      "properties": {
        "contacts": {
          "items": {
            "properties": {
              "address": {
                "type": "string"
              },
              "city": {
                "type": "string"
              },
              "country": {
                "type": "string"
              },
              "email": {
                "type": "string"
              },
              "iban": {
                "type": "string"
              },
              "id": {
                "type": "string"
              },
              "is_customer": {
                "type": "boolean"
              },
              "is_supplier": {
                "type": "boolean"
              },
              "kind": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "notes": {
                "type": "string"
              },
              "phone": {
                "type": "string"
              },
              "postal_code": {
                "type": "string"
              },
              "province": {
                "type": "string"
              },
              "tax_id": {
                "type": "string"
              }
            },
            "required": [
              "id",
              "name",
              "is_customer",
              "is_supplier"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "truncated": {
          "type": "boolean"
        }
      },
      "required": [
        "contacts",
        "truncated"
      ],
      "type": "object"
    },
    {
      "properties": {
        "contact": {
          "properties": {
            "address": {
              "type": "string"
            },
            "city": {
              "type": "string"
            },
            "country": {
              "type": "string"
            },
            "email": {
              "type": "string"
            },
            "iban": {
              "type": "string"
            },
            "id": {
              "type": "string"
            },
            "is_customer": {
              "type": "boolean"
            },
            "is_supplier": {
              "type": "boolean"
            },
            "kind": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "notes": {
              "type": "string"
            },
            "phone": {
              "type": "string"
            },
            "postal_code": {
              "type": "string"
            },
            "province": {
              "type": "string"
            },
            "tax_id": {
              "type": "string"
            }
          },
          "required": [
            "id",
            "name",
            "is_customer",
            "is_supplier"
          ],
          "type": "object"
        },
        "merged": {
          "type": "boolean"
        },
        "repeated": {
          "type": "boolean"
        }
      },
      "required": [
        "contact"
      ],
      "type": "object"
    }
  ],
  "type": "object"
}
```

## Example

Use the actions of this tool in the order shown; its companion tool covers the other actions. These are the `arguments` of each call, in order.

**1. Look for the customer**

```json theme={null}
{
  "action": "list"
}
```

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.

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


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