> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Conta Azul as an MCP

> Let your AI agents use Conta Azul in real time through the Nekt MCP Gateway.

Conta Azul is a Brazilian ERP and cloud accounting platform. With this MCP, your agents can read and write financial records, manage sales, and organize customers or suppliers directly in your Conta Azul account.

| | Available |
| :- | :- |
| **Nekt Express** | Yes |
| **GCP** | Yes |
| **AWS** | Yes |

## Adding Conta Azul as an MCP

Before you start, make sure the [MCP Server](/mcp-server/setup) is set up. See [MCPs](/mcps/overview) for how MCPs work.

1. Go to **Activate → [MCPs](https://app.nekt.ai/mcps)**, click **New MCP** and choose **Conta Azul**.
2. **Name your MCP** and describe what it is used for. The agent reads the description to choose between MCPs of the same provider.
3. **Setup access**. Click the sign-in button and authorize with an account that can see the data you want the agent to use. Actions run with that account's permissions.
   * **Sign in with Conta Azul**: Connect your Conta Azul account via OAuth.
4. **Select tools**. Pick the tools your agents can use. See [Available tools](#available-tools) below.
5. Click **Save**. On Growth and Custom plans, choose who can use it; see [Access levels](/mcps/overview#access-levels).

## Example prompts

* "List all our approved sales from last month."
* "Create a new customer profile for Acme Corp with the CNPJ 12.345.678/0001-90."
* "What are our total accounts payable for next week, and how many of them are already paid?"
* "Register a payment settlement for the pending installment of 500 BRL using our primary financial account."

## Available tools

Choose which of these tools your agents can use in **Select tools**.

<Note>
  **What changed in v1.10.** Added: `criar_pessoa`, `excluir_venda`.
</Note>

### Read tools

| Tool | Description | Parameters |
| :- | :- | :- |
| `consultar_proximo_numero_venda` | Get the next sequential sale number available in Conta Azul ERP. Useful before creating a new sale to ensure a valid next sequence number is used. Args: creds: Injected authentication credentials. Returns: Next available sale number (integer or dict response from API). | — |
| `consultar_venda` | Retrieve full details of a specific sale in Conta Azul by ID. Args: creds: Injected authentication credentials. venda\_id: UUID or legacy ID of the sale to retrieve. Returns: Dict containing full sale details. Top-level keys, as measured against the live API by the production tap… | `venda_id` (string, required) |
| `listar_categorias` | List financial categories from Conta Azul. Args: creds: Injected authentication credentials. pagina: Page number for pagination (default: 1). tamanho\_pagina: Number of items per page (default: 50). Returns: Dict with keys: - `itens_totais` (int): Total count of categories. - \`it… | `pagina` (integer), `tamanho_pagina` (integer) |
| `listar_contas_a_pagar` | List accounts payable (expenses) from Conta Azul. Args: creds: Injected authentication credentials. data\_vencimento\_de: Required start due date filter in YYYY-MM-DD format. data\_vencimento\_ate: Required end due date filter in YYYY-MM-DD format. pagina: Page number for pagination… | `data_vencimento_de` (string, required), `data_vencimento_ate` (string, required), `pagina` (integer), `status` (array), `descricao` (string), `ids_categorias` (array), `tamanho_pagina` (integer), `data_pagamento_de` (string), `data_pagamento_ate` (string), `ids_contas_financeiras` (array) |
| `listar_contas_a_receber` | List accounts receivable (incomes) from Conta Azul. Args: creds: Injected authentication credentials. data\_vencimento\_de: Required start due date filter in YYYY-MM-DD format. data\_vencimento\_ate: Required end due date filter in YYYY-MM-DD format. pagina: Page number for paginati… | `data_vencimento_de` (string, required), `data_vencimento_ate` (string, required), `pagina` (integer), `status` (array), `descricao` (string), `ids_clientes` (array), `ids_categorias` (array), `tamanho_pagina` (integer), `data_pagamento_de` (string), `data_pagamento_ate` (string), `ids_contas_financeiras` (array) |
| `listar_contas_financeiras` | List financial accounts (bank accounts, cash drawers) from Conta Azul. Args: creds: Injected authentication credentials. pagina: Page number for pagination (default: 1). tamanho\_pagina: Number of items per page (default: 50). Returns: Dict with keys: - `itens_totais` (int): Tota… | `pagina` (integer), `tamanho_pagina` (integer) |
| `listar_pessoas` | List persons/contacts (customers, suppliers) from Conta Azul. Args: creds: Injected authentication credentials. pagina: Page number for pagination (default: 1). tamanho\_pagina: Number of items per page (must be one of: 10, 20, 50, 100, 200, 500, 1000; default: 50). Returns: Dict… | `pagina` (integer), `tamanho_pagina` (integer) |
| `listar_vendas` | List sales from Conta Azul with filtering options. Args: creds: Injected authentication credentials. pagina: Page number for pagination (default: 1). tamanho\_pagina: Number of items per page (default: 20). data\_inicio: Start date of sale issuance in YYYY-MM-DD format. data\_fim:… | `tipos` (array), `pagina` (integer), `data_fim` (string), `situacoes` (array), `data_inicio` (string), `termo_busca` (string), `ids_clientes` (array), `ids_vendedores` (array), `tamanho_pagina` (integer), `data_criacao_de` (string), `data_criacao_ate` (string), `data_alteracao_de` (string), `data_alteracao_ate` (string) |

### Write tools

| Tool | Description | Parameters |
| :- | :- | :- |
| `atualizar_venda` | Update an existing sale in Conta Azul by ID. Note: Sale update is synchronous (HTTP 200 OK) and requires `versao` for concurrency control. Args: creds: Injected authentication credentials. venda\_id: Required UUID of the sale to update. id\_cliente: Required UUID of the customer.… | `itens` (array, required), `numero` (integer, required), `versao` (integer, required), `situacao` (string, required), `venda_id` (string, required), `data_venda` (string, required), `id_cliente` (string, required), `condicao_pagamento` (object, required), `id_vendedor` (string), `observacoes` (string), `composicao_de_valor` (object), `id_natureza_operacao` (string), `observacoes_pagamento` (string) |
| `baixar_parcela` | Register settlement (payment/receipt) for an installment in Conta Azul. Note: Registering settlement is synchronous (HTTP 200 OK) and immediately returns the created settlement record, confirming that the installment status has been updated. Unlike creation endpoints (which retu… | `valor` (number, required), `parcela_id` (string, required), `data_pagamento` (string, required), `conta_financeira` (string, required), `observacao` (string), `metodo_pagamento` (string) |
| `criar_conta_a_pagar` | Create a new account payable (expense) in Conta Azul. Note: Creation is asynchronous (HTTP 202 Accepted) and returns a creation protocol with status (PENDING, SUCCESS, ERROR). The HTTP 202 response indicates that the request was accepted for asynchronous processing, NOT that the… | `valor` (number, required), `contato` (string, required), `descricao` (string, required), `id_categoria` (string, required), `data_vencimento` (string, required), `conta_financeira` (string, required), `data_competencia` (string, required), `observacao` (string), `metodo_pagamento` (string) |
| `criar_conta_a_receber` | Create a new account receivable (income) in Conta Azul. Note: Creation is asynchronous (HTTP 202 Accepted) and returns a creation protocol with status (PENDING, SUCCESS, ERROR). The HTTP 202 response indicates that the request was accepted for asynchronous processing, NOT that t… | `valor` (number, required), `contato` (string, required), `descricao` (string, required), `id_categoria` (string, required), `data_vencimento` (string, required), `conta_financeira` (string, required), `data_competencia` (string, required), `observacao` (string), `metodo_pagamento` (string) |
| `criar_pessoa` | Create a new person/contact (customer, supplier, carrier) in Conta Azul. OpenAPI documentation: [https://developers.contaazul.com/open-api-docs/open-api-person/v1/criarpessoa](https://developers.contaazul.com/open-api-docs/open-api-person/v1/criarpessoa) Note: Creation is synchronous (HTTP 201 Created) and returns the created person record. Args: creds: Inje… | `nome` (string, required), `tipo_pessoa` (string, required), `rg` (string), `cpf` (string), `cnpj` (string), `ativo` (boolean), `email` (string), `codigo` (string), `perfis` (array), `enderecos` (array), `inscricoes` (array), `observacao` (string), `nome_fantasia` (string), `agencia_publica` (boolean), `data_nascimento` (string), `optante_simples` (boolean), `outros_contatos` (array), `telefone_celular` (string), `telefone_comercial` (string), `contato_cobranca_faturamento` (object) |
| `criar_venda` | Create a new sale in Conta Azul. Note: Sale creation is synchronous (HTTP 200 OK) and immediately returns the created sale object. Args: creds: Injected authentication credentials. id\_cliente: Required UUID of the customer (from listar\_pessoas). numero: Required sequential sale… | `itens` (array, required), `numero` (integer, required), `situacao` (string, required), `data_venda` (string, required), `id_cliente` (string, required), `condicao_pagamento` (object, required), `id_vendedor` (string), `observacoes` (string), `id_categoria` (string), `id_centro_custo` (string), `composicao_de_valor` (object), `observacoes_pagamento` (string) |
| `excluir_venda` | Delete one or more sales in Conta Azul (batch or single deletion). Note: Batch deletion is synchronous (HTTP 200/204) and deletes the specified sales. Args: creds: Injected authentication credentials. venda\_id: Optional UUID or identifier of a single sale to delete. ids\_vendas:… | `venda_id` (string), `ids_vendas` (array) |

## Troubleshooting

If the agent loses access to Conta Azul (usually because the authorization expired or was revoked), the MCP will show that it needs to reconnect. You can resolve this by going to the MCP's page and signing in again.

## Need help?

Contact our support team if you have trouble connecting Conta Azul.