API REST ou MCP da Conta Azul: qual usar em cada caso

1 Conecte os dois com o mesmo token

O token vem do fluxo OAuth 2.0 da Conta Azul: você autoriza em https://login.contaazul.com/#/oauth/authorize, troca o código em https://api-v2.contaazul.com/oauth/token e recebe um access_token que vale 1 hora (expires_in: 3600) e um refresh_token.

Quando o access_token vence, renove:

curl 'https://api-v2.contaazul.com/oauth/token' \
  -H 'Authorization: Basic BASE64(SEU_CLIENT_ID:SEU_CLIENT_SECRET)' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode 'refresh_token=SEU_REFRESH_TOKEN'

Conforme a documentação oficial; não executado aqui.

Com o token na mão, conecte o MCP no Claude Code:

claude mcp add --transport http contaazul https://api-v2.contaazul.com/mcp \
  --header "Authorization: Bearer SEU_ACCESS_TOKEN"

Rode /mcp dentro do Claude Code: o servidor contaazul deve aparecer conectado. No Cursor, o mesmo vai no mcp.json:

{
  "mcpServers": {
    "contaazul": {
      "url": "https://api-v2.contaazul.com/mcp",
      "headers": { "Authorization": "Bearer SEU_ACCESS_TOKEN" }
    }
  }
}

Comandos conforme as documentações do Claude Code e do Cursor; não executados contra a Conta Azul neste artigo.

O header fica fixo na configuração. Como o token vence em 1 hora, você tem dois caminhos: rodar claude mcp remove contaazul e adicionar de novo, ou usar um headersHelper, um comando que imprime os cabeçalhos em JSON a cada conexão (veja na Dica bônus).

O que o cliente de IA faz por baixo

Você não precisa escrever isso, mas ajuda entender. O MCP usa Streamable HTTP: toda mensagem é um POST em /mcp, com Content-Type: application/json e Accept: application/json, text/event-stream. A sequência é:

1. initialize: o cliente se apresenta e informa a versão do protocolo
2. notifications/initialized: confirma o início da sessão
3. tools/list: devolve as ferramentas
4. tools/call: executa uma ferramenta pelo nome, com os argumentos em JSON

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"teste","version":"1.0.0"}}}

Depois do initialize, o cliente envia também o header MCP-Protocol-Version: 2025-06-18 em todas as requisições, e o servidor pode devolver um Mcp-Session-Id que volta nas mensagens seguintes. Tudo isso está na especificação do MCP.

2 Pergunta simples: "Quanto tenho a receber esta semana?"

Uma pergunta, uma consulta.

Pela REST, quem programa calcula as datas (de 26/10 a 01/11/2026) e chama a busca de contas a receber:

curl 'https://api-v2.contaazul.com/v1/financeiro/eventos-financeiros/contas-a-receber/buscar?pagina=1&tamanho_pagina=50&data_vencimento_de=2026-10-26&data_vencimento_ate=2026-11-01' \
  -H 'Authorization: Bearer SEU_ACCESS_TOKEN'

Conforme a especificação OpenAPI do Financeiro; não executado aqui.

A resposta traz itens_totais, itens (as parcelas, cada uma com total, status e cliente.nome) e totais. Cuidado com esse último: ele conta parcelas ativas e inativas (ativo, inativo, todos), não soma dinheiro. Para saber quanto vai entrar, você soma o total de cada parcela e, se itens_totais passar de 50, pede a página 2.

Pelo MCP, o usuário escreve no cliente de IA:

Quanto tenho a receber esta semana, e de quais clientes?

O agente calcula as datas sozinho e chama buscarParcelasAReceberPorFiltro com os mesmos filtros da REST:

{"data_vencimento_de": "2026-10-26", "data_vencimento_ate": "2026-11-01", "pagina": 1, "tamanho_pagina": 50}

Depois responde em texto. Exemplo com valores fictícios:

Você tem R$ 12.400,00 a receber esta semana, em 5 parcelas. Os maiores valores são da Conectai (R$ 6.000,00) e da Loja Exemplo (R$ 3.200,00).

A diferença: na REST, as datas, a paginação e a soma estão no seu código. No MCP, o agente cuida disso e entrega a resposta pronta para ler.

3 Pergunta encadeada: "Qual o saldo de cada conta?"

Aqui uma resposta depende de outra: primeiro é preciso saber quais contas existem.

Pela REST, você escreve as duas etapas:

curl 'https://api-v2.contaazul.com/v1/conta-financeira?pagina=1&tamanho_pagina=50' \
  -H 'Authorization: Bearer SEU_ACCESS_TOKEN'

curl 'https://api-v2.contaazul.com/v1/conta-financeira/ID_DA_CONTA/saldo-atual' \
  -H 'Authorization: Bearer SEU_ACCESS_TOKEN'

Conforme a especificação OpenAPI do Financeiro; não executado aqui.

A primeira lista as contas (id, nome, tipo, banco). A segunda devolve { "saldo_atual": 18250.00 } para cada id. Com 3 contas, são 4 requisições, e o laço que as encadeia está no seu código.

Pelo MCP:

Qual o saldo atual de cada conta?

O agente decide a ordem sozinho: chama listarContasFinanceiras, lê os ids e chama obterSaldoDaContaFinanceira uma vez por conta. Saída de exemplo, com valores fictícios:

Conta corrente: R$ 18.250,00. Poupança: R$ 4.130,00. Caixa: R$ 600,00.

A diferença: as 4 chamadas acontecem dos dois jeitos. Na REST, você planeja o encadeamento. No MCP, o agente descobre que precisa dele.

4 Gravar no ERP: "Lance uma receita de R$ 500 da Conectai para 10/11"

Agora o pedido altera dados.

Pela REST, o sistema monta o corpo com os campos obrigatórios e envia um POST:

curl -X POST 'https://api-v2.contaazul.com/v1/financeiro/contas-a-receber' \
  -H 'Authorization: Bearer SEU_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"descricao":"Serviço de consultoria","data_competencia":"2026-11-10","valor":500,"id_cliente":"ID_DO_CLIENTE","conta_financeira":"ID_DA_CONTA","rateio":[{"id_categoria":"ID_DA_CATEGORIA","valor":500}],"condicao_pagamento":{"parcelas":[{"descricao":"Parcela 1","data_vencimento":"2026-11-10","conta_financeira":"ID_DA_CONTA","detalhe_valor":{"valor_bruto":500}}]}}'

Corpo conferido contra a especificação OpenAPI do Financeiro; não executado aqui.

Os três ids (cliente, conta e categoria) vêm de consultas anteriores ou do cadastro do seu sistema. É o caso típico de integração: a cada pedido pago no e-commerce, o sistema lança a receita sem ninguém olhar.

Pelo MCP:

Lance uma receita de R$ 500 da Conectai, com vencimento em 10/11, na conta corrente.

O agente precisa descobrir os mesmos ids:

1. Busca o cliente com buscarPessoasPorFiltro
2. Busca a conta com listarContasFinanceiras
3. Busca a categoria com buscarCategoriasPorFiltro
4. Chama criarEventoFinanceiroAReceber com um corpo igual ao da REST

Se faltar informação, como a categoria, um bom agente pergunta antes. Se não perguntar, ele pode escolher sozinho.

O cuidado: essa chamada grava de verdade no ERP. No Claude Code, mantenha a aprovação manual: ele mostra a ferramenta e os argumentos e só executa depois do seu sim. Confira valor, data, cliente e categoria antes de aprovar.

Das 58 ferramentas, as 14 que gravam são: criarEventoFinanceiroAReceber, criarEventoFinanceiroAPagar, criarBaixa, criarCobranca, criarCentroDeCusto, criarProduto, criarServico, criarVenda, criarOrcamento, criarPessoa, ativarPessoasEmLote, criarContrato, encerrarContrato e vincularNotaFiscalAoMdfe. Pelos nomes, nenhuma exclui registros nem edita os dados de um cadastro, mas quatro mudam algo que já existe: criarBaixa, encerrarContrato, ativarPessoasEmLote e vincularNotaFiscalAoMdfe. Para corrigir ou excluir, só a REST (por exemplo, PUT /v1/venda/{id}).

5 Faturamento do mês: onde o agente pode mudar o número

Aqui, faturamento é o valor das vendas aprovadas no mês, pela data de emissão. Testamos as duas chamadas em 26/10/2026 com uma conta real, e elas devolveram a mesma estrutura. Os valores abaixo são fictícios.

Pela REST:

curl 'https://api-v2.contaazul.com/v1/venda/busca?data_inicio=2026-10-01&data_fim=2026-10-31&pagina=1&tamanho_pagina=10' \
  -H 'Authorization: Bearer SEU_ACCESS_TOKEN'

Parâmetros conforme a especificação OpenAPI de Vendas.

A resposta traz o bloco totais já somado para o período inteiro, então você não precisa percorrer as páginas de vendas:

{
  "totais": { "total": 58300.00, "aprovado": 52100.00, "cancelado": 1900.00, "esperando_aprovacao": 4300.00 },
  "quantidades": { "total": 47, "aprovado": 42, "cancelado": 2, "esperando_aprovacao": 3 },
  "total_itens": 47,
  "itens": [ "..." ]
}

O faturamento é totais.aprovado: R$ 52.100,00 em 42 vendas. As canceladas ficam de fora, e as que esperam aprovação podem entrar como previsão.

Pelo MCP:

Qual o faturamento deste mês até agora? Compare com o mês passado.

O agente monta o período de outubro, chama buscarVendasPorFiltro (que devolve o mesmo JSON da REST), chama de novo para setembro e responde em texto:

O faturamento de outubro até hoje é de R$ 52.100,00, em 42 vendas aprovadas. Em setembro inteiro foram R$ 61.800,00. Há ainda R$ 4.300,00 em 3 vendas esperando aprovação.

A diferença: a consulta por trás é a mesma. Na REST, você decide uma vez que faturamento é totais.aprovado. No MCP, o agente interpreta a pergunta a cada vez: se ele usar total em vez de aprovado, as vendas canceladas entram no número. Por isso, diga no pedido o que conta, por exemplo "só vendas aprovadas".

Se para vocês faturamento for nota fiscal emitida, o caminho é outro: buscarNotasFiscaisProdutoPorFiltro e buscarNotasFiscaisServicoPorFiltro no MCP.

6 Qual usar em cada situação

Regra de bolso: REST para o que roda sozinho, MCP para perguntas feitas por pessoas.

Por que volume não vai pelo MCP: tudo o que o MCP devolve passa pelo modelo de IA, que lê e cobra por tokens de IA (pedaços de texto). Uma carga de milhares de registros fica lenta, cara e arrisca o modelo pular linhas. A REST entrega o mesmo volume direto ao código, com contagem exata.

Os dois funcionam bem juntos: a REST faz a carga, e o MCP confere por amostragem. Rodar a REST não exige servidor próprio. Para uma carga pontual, basta um script no computador ou um fluxo no n8n.