Beta · Spec MCP 2025-06-18

Sua IA agora emite nota fiscal

Primeiro servidor MCP fiscal do Brasil. Conecte Claude, ChatGPT, Cursor, Copilot ou Windsurf e emita NF-e, NFC-e, NFS-e, CT-e, MDF-e e DC-e por linguagem natural. 24 tools, 5 prompts prontos, autenticação por token de empresa.

Streamable HTTP Bearer token Auditoria por chamada Rate-limit por empresa

Documentação MCP

// claude_desktop_config.json
{
  "mcpServers": {
    "brasilnfe": {
      "url": "https://api.brasilnfe.com.br/services/Mcp",
      "headers": {
        "Authorization": "Bearer SEU_TOKEN"
      }
    }
  }
}
                            

// .cursor/mcp.json
{
  "mcpServers": {
    "brasilnfe": {
      "url": "https://api.brasilnfe.com.br/services/Mcp",
      "headers": {
        "Authorization": "Bearer SEU_TOKEN"
      }
    }
  }
}
                            

# Listar tools disponíveis
curl -X POST "https://api.brasilnfe.com.br/services/Mcp" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'
                            

Era dos agentes de IA

O que é MCP (Model Context Protocol) e por que importa para a sua operação fiscal

O Model Context Protocol (MCP) é o protocolo aberto criado pela Anthropic em novembro de 2024 que padroniza a forma como agentes de IA descobrem e usam ferramentas externas. Em poucos meses, virou o “USB-C dos agentes”: foi adotado por OpenAI, Google, Microsoft Copilot, Cursor, Windsurf, Zed, JetBrains, GitHub Copilot e Continue.dev. Hoje, qualquer modelo (Claude, ChatGPT, Gemini, Copilot) consegue conversar com qualquer servidor MCP — sem integração custom, sem SDK proprietário, sem lock-in.

A operação fiscal brasileira é especialmente difícil para uma IA improvisar: 5.500+ municípios com regras próprias para NFS-e, 543 códigos de rejeição da SEFAZ, ICMS/IPI/PIS/COFINS/ST/DIFAL/FCP, CFOP por operação, CST por regime, prazos legais de cancelamento, certificado digital A1, contingência. Sem uma camada que entenda esse contexto, qualquer agente erra. O MCP Server da Brasil NFe é essa camada: expõe 24 tools fiscais, 5 prompts prontos e 5 resources com snapshot da empresa, regime tributário e estado de contingência.

Com MCP plugado, o desenvolvedor descreve em português: “emita uma NF-e de R$ 1.500 para o CNPJ 12.345.678/0001-00 com um notebook”. O agente lê brasilnfe://empresa/atual para confirmar emitente, chama sefaz_status para conferir SEFAZ, e dispara nfe_emitir com os dados certos. Em 3 segundos, retorna chave de acesso, protocolo e DANFE em PDF. Brasil NFe é a primeira API fiscal nacional com servidor MCP nativo.

Para times de produto e engenharia, isso muda o game: chatbots internos de NF-e sem integração custom, copilotos contábeis que cancelam e corrigem nota direto do Cursor, automações no Claude Desktop para o financeiro emitir relatório do período, scripts no ChatGPT que fazem diagnóstico de emissão antes do fechamento. Tudo isso plugando um único servidor MCP no cliente de IA que sua equipe já usa.

Como funciona

Conecte sua IA à SEFAZ em três passos

Sem SDK, sem servidor intermediário, sem proxy. O cliente MCP fala direto com a Brasil NFe.

Pegue seu token

Crie uma conta no painel Brasil NFe (grátis em homologação) e copie o token de empresa. Esse mesmo token autentica chamadas MCP e REST.

Configure o cliente MCP

Adicione o servidor https://api.brasilnfe.com.br/services/Mcp ao Claude Desktop, Cursor, Windsurf ou Copilot, com Authorization: Bearer SEU_TOKEN. Reinicie o cliente.

Converse com sua IA

O agente descobre as 24 tools automaticamente. Peça em português: “emite uma NF-e”, “cancela essa nota”, “faz um relatório do mês”. A SEFAZ responde em segundos.

Catálogo de tools

24 tools fiscais prontas para chamadas de IA

Cada tool tem inputSchema/outputSchema gerados a partir dos contratos C# da API e anotações readOnly, destructive, idempotent que o cliente MCP usa para pedir confirmação ao usuário em operações sensíveis.

NF-e / NFC-e

nfe_emitir

Emite NF-e (modelo 55) ou NFC-e (modelo 65). Retorna chave, protocolo, XML e DANFE em base64.

nfe_emitir_loteLong

Emite até 50 NF-e/NFC-e em lote único. Notifica progresso a cada 5s.

nfe_emitir_complementar

NF-e complementar (finalidade=2) referenciando uma nota original já autorizada.

nfe_previsualizarRead

Pré-visualização do DANFE em PDF, sem enviar para a SEFAZ.

NFS-e

nfse_emitir

Emite NFS-e via Portal Nacional ou prefeitura específica conforme cadastro.

nfse_consultarRead

Consulta status e dados de uma NFS-e por número, série e ambiente.

CT-e · MDF-e · DC-e · NF-EnerCom

cte_emitir

Emite CT-e (Conhecimento de Transporte Eletrônico).

cte_desacordo

Registra desacordo do tomador (evento tipo 4 do CT-e). Prazo: 45 dias.

mdfe_emitir

Emite MDF-e agrupando vários CT-e/NF-e no mesmo transporte.

mdfe_encerrar

Encerra MDF-e autorizado (evento tipo 3). Obrigatório ao fim do transporte.

dce_emitir

Emite DC-e (Declaração de Conteúdo) para PF/MEI.

nfenercom_emitir

Emite NF-EnerCom (Nota Fiscal de Energia Comercializada).

Eventos fiscais

evento_cancelarDestructive

Cancela NF-e, NFC-e, NFS-e, CT-e, MDF-e ou DC-e. Prazo: 24h após autorização (algumas UFs mais).

evento_carta_correcao

CC-e em NF-e ou CT-e (evento tipo 2). Limite: 20 CC-e por nota.

evento_manifestar

Manifestação do destinatário (ciência, confirmação, desconhecimento, não realizada).

evento_inutilizarDestructive

Inutiliza faixa de numeração não utilizada. Não pode ser desfeito.

Consultas SEFAZ

sefaz_statusRead

Status do serviço de autorização da SEFAZ por UF e ambiente.

cadastro_consultarRead

Consulta dados cadastrais de contribuinte por CPF/CNPJ/IE e UF.

nota_listarRead

Lista NF-e/NFC-e/NFS-e emitidas ou recebidas em um período.

imposto_calcularRead

Simula cálculo de ICMS, PIS, COFINS, IPI, ST sem emitir nota.

Arquivos · Downloads

arquivo_baixarRead

XML ou PDF/DANFE de uma nota por chave de acesso. Retorna em base64.

arquivo_baixar_eventoRead

Arquivo de evento (CC-e, cancelamento, manifestação) por chave + sequencial.

arquivo_baixar_periodoReadLong

Exporta XMLs/PDFs de um período em um único ZIP base64.

fci_gerar

Gera FCI (Ficha de Conteúdo de Importação) para operações interestaduais.

nfenercom_gerar_arquivo

Gera arquivo NF-EnerCom como pré-requisito para emissão.

healthRead

Health-check da API: status, timestamp e versão.

Resources MCP

5 resources via URI `brasilnfe://`

Resources são leituras estáveis que o agente consome para tomar decisões antes de emitir.

brasilnfe://empresa/atual

Snapshot da empresa do token: razão social, CNPJ, IE, regime tributário, estado de contingência. O agente lê antes de emitir para confirmar emitente.

brasilnfe://nfe/{chave}/xml

XML autorizado pela SEFAZ de uma NF-e/NFC-e emitida pela empresa. Substitua {chave} pela chave de 44 dígitos.

brasilnfe://nfe/{chave}/danfe

DANFE em PDF para impressão ou envio ao cliente.

brasilnfe://nfe-entrada/{chave}/xml

XML de NF-e recebida (entrada). Disponível quando a empresa baixa notas dos fornecedores.

brasilnfe://evento/{chave}/{tipoArquivo}

XML (1) ou PDF (2) de evento fiscal: CC-e, cancelamento, manifestação, encerramento.

Prompts prontos

5 fluxos guiados que sua IA já sabe executar

Prompts MCP descrevem para o agente como usar as tools no contexto fiscal correto. O cliente MCP os exibe como ações de um clique no usuário final.

emitir_nfe_simples

Emitir NF-e simples

Guia o agente para emitir uma NF-e modelo 55 com um produto, calculando impostos pelo grupo tributário.

cnpjCliente* descricaoProduto* valor* ambiente naturezaOperacao

cancelar_nota

Cancelar nota fiscal

Cancela NF-e, NFC-e, CT-e, MDF-e, DC-e ou NFS-e. Valida prazo legal e tamanho da justificativa.

chave numeroNFSe justificativa*

diagnostico_emissao

Diagnóstico de emissão

Verifica se a empresa está apta a emitir agora: SEFAZ, certificado, contingência. Conclui com PRONTO ou ATENÇÃO.

relatorio_periodo

Relatório do período

Gera relatório de NF-e/NFC-e do período com totais, status e top 5 destinatários por valor.

dataInicio* dataFim* modeloDocumento

carta_correcao

Carta de Correção (CC-e)

Envia CC-e em NF-e ou CT-e autorizada. Valida o que pode e não pode ser corrigido.

chave* correcao*

Compatibilidade

Funciona com todos os clientes MCP do mercado

Transport Streamable HTTP padrão (spec 2025-06-18). Qualquer cliente que fale MCP, conecta.

Claude Desktop Anthropic

ChatGPT Apps OpenAI · MCP

Cursor Cursor AI

Windsurf Codeium

GitHub Copilot VS Code

Zed Zed Industries

JetBrains AI Junie · IDE

Continue · Cline Open source

Segurança

Sua IA emite com as mesmas garantias da API REST

O servidor MCP herda a stack de produção da Brasil NFe: token isolado por empresa, rate-limit, auditoria por chamada e hints que pedem confirmação ao usuário em operações destrutivas.

Bearer token por empresa

Cada empresa tem token isolado. Authorization: Bearer ou header Token:. Sessões usam Mcp-Session-Id.

Rate-limit configurável

Default 60 req/min por empresa, ajustável via Mcp:RateLimit:RequestsPerMinute. Headers X-RateLimit-* em toda resposta.

Auditoria por chamada

Cada tools/call, resources/read e prompts/get registra empresa, sessão, tool, latência, sucesso e código de erro.

Hints de operações destrutivas

Tools como evento_cancelar e evento_inutilizar têm destructiveHint: true. Clientes MCP pedem confirmação obrigatória.

Homologação por padrão

Use tipoAmbiente: 2 para testes. Os prompts prontos defaultam para homologação até que o usuário troque para produção.

CORS e isolamento

CORS configurado por origem, sessões com cleanup automático, suporte a DELETE /services/Mcp para encerrar explicitamente.

FAQ

Perguntas frequentes sobre MCP fiscal

Tudo que times técnicos e contábeis querem saber antes de plugar a IA na SEFAZ.

MCP é o protocolo aberto criado pela Anthropic em novembro de 2024 e adotado pela OpenAI, Google, Microsoft Copilot, Cursor, Windsurf, JetBrains e Zed em 2025. Funciona como o “USB-C dos agentes de IA”: padroniza como um modelo (Claude, ChatGPT, Gemini, Copilot) descobre e usa ferramentas externas (tools), recursos (resources) e prompts. O servidor MCP da Brasil NFe expõe 24 tools fiscais e 5 prompts prontos, permitindo que qualquer cliente compatível com MCP emita NF-e, NFC-e, NFS-e, CT-e, MDF-e e DC-e por linguagem natural.

O endpoint principal é https://api.brasilnfe.com.br/services/Mcp (transport Streamable HTTP, spec 2025-06-18). Discovery: GET /services/Mcp/info retorna nome, versão, lista de tools e sessões ativas; GET /.well-known/mcp retorna o manifesto padrão MCP. Versões de protocolo suportadas: 2025-06-18 (default), 2025-03-26 e 2024-11-05 (negociadas no initialize).

Qualquer cliente que implemente a spec MCP funciona: Claude Desktop e Claude.ai (Anthropic), ChatGPT Apps via MCP (OpenAI), Cursor, Windsurf, Zed, JetBrains AI Assistant, GitHub Copilot (VS Code), Continue.dev, Cline, e SDKs MCP em Python, TypeScript, C#, Rust e Java. Como o transport é Streamable HTTP padrão, basta apontar o cliente para o endpoint e enviar o token de autenticação.

A autenticação é feita pelo token de empresa gerado no painel Brasil NFe, enviado em um destes dois cabeçalhos: Authorization: Bearer SEU_TOKEN ou Token: SEU_TOKEN. O token identifica a empresa emitente: o servidor automaticamente resolve CNPJ, regime tributário, certificado digital e contingência da empresa em cada chamada. Cada token é isolado e tem rate-limit próprio (60 requisições/minuto por padrão).

Sim, com as proteções certas. O servidor MCP da Brasil NFe inclui: (1) tools marcadas com destructiveHint (ex: cancelamento, inutilização) que clientes MCP exibem com confirmação obrigatória ao usuário; (2) recurso brasilnfe://empresa/atual que o agente lê antes de emitir para confirmar emitente e regime; (3) prompt diagnostico_emissao que valida SEFAZ e contingência antes de operações em massa; (4) auditoria por chamada (timestamp, request id, sessão, tool, latência, erro); (5) rate limit por empresa; (6) suporte a tipoAmbiente=2 (homologação) para testes. Para produção, recomendamos sempre revisão humana em emissões de alto valor e cancelamentos.

NF-e/NFC-e: nfe_emitir, nfe_emitir_lote, nfe_emitir_complementar, nfe_previsualizar. NF-EnerCom: nfenercom_gerar_arquivo, nfenercom_emitir. NFS-e: nfse_emitir, nfse_consultar. CT-e: cte_emitir, cte_desacordo. MDF-e: mdfe_emitir, mdfe_encerrar. DC-e: dce_emitir. Eventos: evento_cancelar, evento_carta_correcao, evento_manifestar, evento_inutilizar. Consultas SEFAZ: sefaz_status, cadastro_consultar, nota_listar, imposto_calcular. Arquivos: arquivo_baixar, arquivo_baixar_evento, arquivo_baixar_periodo. Auxiliares: fci_gerar, health.

Sim. O servidor MCP é a mesma camada da API REST da Brasil NFe (mesma autenticação, mesma SEFAZ, mesmos contratos). Em produção, recomendamos: usar tipoAmbiente: 2 (homologação) para todos os testes; configurar rate-limit conforme volume; ler brasilnfe://empresa/atual antes de emitir; usar o prompt diagnostico_emissao antes de operações em massa; manter o log de auditoria do MCP integrado ao seu SIEM. O claim OpenWorldHint=true nas tools que tocam SEFAZ avisa o cliente MCP que o resultado depende de sistemas externos.

O servidor MCP é gratuito e está incluído em qualquer plano ativo da API Brasil NFe (NF-e/NFC-e a partir de R$ 49,90/mês, NFS-e, CT-e, MDF-e, DC-e). Não há cobrança por chamada MCP, por sessão ou por tool. O que conta é a contratação do serviço fiscal correspondente. Em homologação (testes), o uso é totalmente gratuito e ilimitado, sem cartão de crédito.

Era da IA fiscal

Pronto para sua IA emitir a primeira NF-e?

Crie sua conta, copie o token, plugue no Claude, Cursor ou ChatGPT. Em 30 segundos sua IA fala com a SEFAZ.

Ver documentação Falar com a equipe