# Conta Azul — how to use (mcp.ai)

ERP financeiro brasileiro Conta Azul (API v2). Gerencie pessoas (clientes/fornecedores), produtos, serviços, vendas, contratos, contas a receber/pagar, parcelas, NF-e e quitações via OAuth 2.0. Plataforma fornece a aplicação OAuth, você só clica em Autorizar e loga com sua conta Conta Azul.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/contaazul?ms=1781045400000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `contaazul_list_accounts`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/contaazul`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/contaazul/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/contaazul/accounts/list` — Listar empresas Conta Azul vinculadas
- `POST https://api.mcp.ai/api/contaazul/companies/get` — Dados da empresa ativa (CNPJ, razão social, regime tributário)
- `POST https://api.mcp.ai/api/contaazul/people/list` — Listar pessoas (clientes, fornecedores, vendedores, transportadores)
  - body: { tamanho_pagina?: number, pagina?: number, busca?: string, tipo?: string, ativo?: boolean }
- `POST https://api.mcp.ai/api/contaazul/people/get` — Detalhe de pessoa por id
  - body: { id: string }
- `POST https://api.mcp.ai/api/contaazul/people/create` — Criar pessoa
  - body: { data: string }
- `POST https://api.mcp.ai/api/contaazul/people/update` — Atualizar pessoa por id
  - body: { id: string, data: string }
- `POST https://api.mcp.ai/api/contaazul/people/delete` — Remover pessoa por id (destrutivo)
  - body: { id: string }
- `POST https://api.mcp.ai/api/contaazul/products/list` — Listar produtos cadastrados
  - body: { tamanho_pagina?: number, pagina?: number, busca?: string, ativo?: boolean }
- `POST https://api.mcp.ai/api/contaazul/products/create` — Criar produto
  - body: { data: string }
- `POST https://api.mcp.ai/api/contaazul/services/list` — Listar serviços
  - body: { tamanho_pagina?: number, pagina?: number, busca?: string }
- `POST https://api.mcp.ai/api/contaazul/services/write` — Criar serviço
  - body: { data: string }
- `POST https://api.mcp.ai/api/contaazul/sales/list` — Listar vendas
  - body: { tamanho_pagina?: number, pagina?: number, data_inicio?: string, data_fim?: string, cliente_id?: string, status_venda?: string }
- `POST https://api.mcp.ai/api/contaazul/sales/get` — Detalhe de venda por id
  - body: { id: string }
- `POST https://api.mcp.ai/api/contaazul/sales/create` — Criar venda
  - body: { data: string }
- `POST https://api.mcp.ai/api/contaazul/sales/update` — Atualizar venda por id
  - body: { id: string, data: string }
- `POST https://api.mcp.ai/api/contaazul/sales/cancel` — Cancelar venda (destrutivo)
  - body: { id: string }
- `POST https://api.mcp.ai/api/contaazul/contracts/list` — Listar contratos (intervalo de data de início)
  - body: { data_inicio?: string, data_fim?: string, tamanho_pagina?: number, pagina?: number, cliente_id?: string, busca_textual?: string }
- `POST https://api.mcp.ai/api/contaazul/contracts/write` — Criar contrato
  - body: { data: string }
- `POST https://api.mcp.ai/api/contaazul/receivables/list` — Listar contas a receber
  - body: { tamanho_pagina?: number, pagina?: number, data_vencimento_de?: string, data_vencimento_ate?: string, status?: string, ids_clientes?: string }
- `POST https://api.mcp.ai/api/contaazul/receivables/create` — Criar conta a receber
  - body: { data: string }
- `POST https://api.mcp.ai/api/contaazul/payables/list` — Listar contas a pagar
  - body: { tamanho_pagina?: number, pagina?: number, data_vencimento_de?: string, data_vencimento_ate?: string, status?: string }
- `POST https://api.mcp.ai/api/contaazul/payables/create` — Criar conta a pagar
  - body: { data: string }
- `POST https://api.mcp.ai/api/contaazul/installments/list` — Listar parcelas (eventos financeiros)
  - body: { tamanho_pagina?: number, pagina?: number, data_vencimento_inicio?: string, data_vencimento_fim?: string, tipo?: string, status?: string }
- `POST https://api.mcp.ai/api/contaazul/installments/get` — Detalhe de parcela por id
  - body: { id: string }
- `POST https://api.mcp.ai/api/contaazul/installments/update` — Atualizar campos de uma parcela (versao automática)
  - body: { id: string, data: string }
- `POST https://api.mcp.ai/api/contaazul/financial-accounts/list` — Listar contas financeiras (banco, caixa, cartão)
  - body: { tamanho_pagina?: number, pagina?: number }
- `POST https://api.mcp.ai/api/contaazul/financial-accounts/balance` — Saldo atual de uma conta financeira
  - body: { id: string }
- `POST https://api.mcp.ai/api/contaazul/categories/list` — Listar categorias financeiras (DRE)
  - body: { tamanho_pagina?: number, pagina?: number, tipo?: string }
- `POST https://api.mcp.ai/api/contaazul/cost-centers/list` — Listar centros de custo
  - body: { tamanho_pagina?: number, pagina?: number }
- `POST https://api.mcp.ai/api/contaazul/invoices-nfe/list` — Listar NF-e emitidas
  - body: { tamanho_pagina?: number, pagina?: number, data_emissao_inicio?: string, data_emissao_fim?: string, status?: string }
- `POST https://api.mcp.ai/api/contaazul/invoices-nfe/get` — Detalhe de NF-e por id
  - body: { id: string }

## Example prompts
- "Liste as 20 últimas vendas e o total faturado nos últimos 30 dias"
- "Quais contas a receber estão vencidas hoje?"
- "Cadastre o cliente João Silva (CPF 123.456.789-00, email joao@ex.com)"

## More
- Page: https://mcp.ai/contaazul
- Agent spec (llms.txt): https://mcp.ai/contaazul/llms.txt
- Postman collection: https://mcp.ai/contaazul/postman.json