Servidor MCP

Conecte seu assistente de IA (ChatGPT, Claude, Cursor…) à sua conta do Conttrole e emita notas fiscais conversando: “emita uma NFS-e de R$ 500 para o cliente X”. O assistente cria, emite, consulta, cancela e gera CC-e — falando direto com a sua conta via Model Context Protocol .

🔗 Servidor remoto, hospedado: https://mcp.conttrole.io — nada para instalar. Conecte por OAuth (login no navegador, sem manusear chave).

Conectar (OAuth — recomendado)

Ao conectar, o cliente de IA abre o login do Conttrole no navegador, você escolhe a empresa e autoriza as permissões. Pronto — sem chave, sem configuração de arquivo.

ChatGPT

Em Configurações → Conectores (modo desenvolvedor / planos com suporte a MCP), adicione um conector com a URL:


https://mcp.conttrole.io

Claude (claude.ai e Claude Desktop)

Em Configurações → Conectores → Adicionar conector personalizado, informe a URL:


https://mcp.conttrole.io

Cursor

No ~/.cursor/mcp.json (ou Settings → MCP):


{
  "mcpServers": {
    "conttrole": { "url": "https://mcp.conttrole.io" }
  }
}

Claude Code (CLI)


claude mcp add --transport http conttrole https://mcp.conttrole.io

Em todos, na primeira conexão o cliente abre o fluxo de login + autorização.

Autenticação por chave (alternativa)

Prefere não usar OAuth? Os clientes que permitem header customizado podem autenticar com uma chave de API (ck_live_...):


Authorization: Bearer ck_live_xxxxxxxxxxxx

Os escopos da chave valem aqui — uma ferramenta só funciona se a chave (ou a autorização OAuth) tiver o escopo correspondente (ex.: documents:write).

Ferramentas disponíveis

Ferramenta	O que faz
`list_fiscal_documents`	Lista documentos (filtra por status/tipo).
`get_fiscal_document`	Detalha um documento pelo id.
`create_fiscal_document`	Cria um documento; `emit=true` já emite.
`emit_fiscal_document`	Dispara a emissão (assíncrona).
`cancel_fiscal_document`	Cancela um documento autorizado (com justificativa).
`correct_fiscal_document`	Emite uma Carta de Correção (CC-e).
`get_fiscal_document_xml`	Baixa o XML autorizado.
`list_tax_rules`	Lista as regras tributárias.
`list_products` / `get_product`	Lista / detalha produtos, com a tributação própria de cada um.
`create_product` / `update_product`	Cadastra / altera um produto e a tributação dele (exige `products:write`). O `id` vai em `productId` no item da nota.
`list_webhooks` / `create_webhook`	Gerencia webhooks.
`list_finance_titles`	Lista parcelas a receber/pagar (vencidas, a vencer, faixas de atraso).
`get_finance_summary`	Totais em aberto e aging de um lado.
`get_finance_title`	Ficha de um título, com o histórico de baixas.
`create_finance_title`	Lança uma conta a receber ou a pagar.
`settle_finance_installment`	Dá baixa numa parcela.
`list_overdue_receivables`	Contas vencidas, na ordem de cobrança.
`top_delinquent_clients`	Quem mais deve, agrupado por cliente.
`cashflow_projection`	Projeção de caixa por vencimento.

As oito de financeiro exigem o escopo finance:read/finance:write e o módulo Financeiro contratado — ver Escopos. Elas são as mesmas leituras que o assistente dentro do app executa, sobre o mesmo cálculo: o número que o ChatGPT responde é o número que a tela mostra.

O que cabe em `create_fiscal_document`

Além dos itens, ela aceita pagamento (payments), parcelamento (duplicates), transporte e frete (transport), desconto da nota (discountValue), cliente inline (client, cria ou reusa o cliente junto da nota), finalidade e documentos referenciados (fiscalPurpose, references, isDevolution), local de entrega e retirada (places), pedido de compra e, na NFS-e, competência, município da prestação, dedução em valor, obra e substituição. No item entram os acessórios (freightValue, insuranceValue, otherValue, discountValue), os impostos, os parâmetros de ICMS-ST, a desoneração e os lotes.

O total da nota não é o total dos itens. Frete, seguro e outras despesas somam, e o desconto abate. É esse valor que a soma de duplicates precisa fechar exatamente — diferença de um centavo é recusada.

O que não está no schema da ferramenta entra por extra, um objeto que é repassado à API como está: é por ali que vão os grupos raros (ajustes de IBS/CBS, ICMS-ST retido anteriormente, notas de crédito/débito da RTC, comExt da NFS-e e o intermediador). A referência completa dos campos está no OpenAPI .

Exemplo

“Crie uma NFS-e para o cliente cli_123 com um item de consultoria de R$ 500 e já emita.”

O agente chama create_fiscal_document (emit=true), recebe o runId e acompanha o status com get_fiscal_document.

Servidor local (avançado)

Quem usa Claude Desktop, Cursor ou Claude Code e prefere rodar o servidor na própria máquina (stdio) pode usar o pacote @conttrole/mcp:


{
  "mcpServers": {
    "conttrole": {
      "command": "npx",
      "args": ["-y", "@conttrole/mcp"],
      "env": { "CONTTROLE_API_KEY": "ck_live_xxxxxxxx" }
    }
  }
}

Ele expõe as mesmas ferramentas do servidor remoto, com os mesmos campos — inclusive produtos e financeiro. Até set/2026 ele tinha 11 das 23, e nada dizia isso: quem o instalava ficava sem produtos nem financeiro.

Para a maioria dos casos, o servidor remoto acima é mais simples (sem instalar nada, com OAuth) e funciona também na web (ChatGPT, claude.ai).