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

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.

Notas recebidas e o modo contador

As ferramentas de notas recebidas exigem o escopo received-documents:read (e received-documents:write para manifestar), que não vêm na “chave sem escopos”. Manifestar não tem desfazer — a descrição da ferramenta pede ao agente que confirme com você antes de recusar uma nota.

Escritórios de contabilidade usam a chave do escritório (ok_live_..., criada no Painel do Contador → Configurações) no lugar da chave da empresa. Com ela funcionam as ferramentas marcadas como modo contador e as de notas recebidas com companyId — a empresa da carteira. Sem companyId, as de notas recebidas usam a empresa da chave, e por isso só funcionam com a chave de uma empresa. O servidor remoto por OAuth autoriza uma empresa por vez; para o modo contador, configure a chave do escritório no header Authorization.

Exemplo: “Quais clientes da carteira têm nota para manifestar?” — o agente chama list_portfolio_companies e, para cada empresa, list_received_documents com companyId e pending: true.

Exemplo: “Me manda as notas recebidas de agosto de todos os clientes” — o agente chama get_received_documents_export_link com portfolio: true e devolve o link do ZIP (uma pasta por empresa). O link vale 15 minutos e deixa de funcionar na hora se a chave for revogada ou a empresa sair da carteira.

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, financeiro, notas recebidas e o modo contador (com a chave do escritório, ok_live_..., em CONTTROLE_API_KEY). 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).