Servidor MCP (IA)
Conecte Claude Desktop, Cursor e Claude Code ao motor fiscal NFeR.
O Model Context Protocol (MCP) é um protocolo aberto padronizado que permite a assistentes de Inteligência Artificial — como Claude Desktop, Cursor IDE, Claude Code, Windsurf e agentes autônomos — interagirem diretamente com o motor fiscal da NFeR em linguagem natural.
Busca em toda a documentação da API, guias de código por linguagem (TypeScript, Python, PHP, C#, cURL), validações de CPF/CNPJ, cálculo de DIFAL, status das 27 SEFAZs em tempo real, diagnóstico de rejeições cStat, IBGE, CNAE, adesão NFS-e Nacional e índices BACEN.
Consulta de Inscrição Estadual direta na SEFAZ (CCC), simulação e preflight de NF-e, emissão em homologação e produção protegida, download de DANFE/XML e cadastros automáticos.
1. Endpoints e Tecnologias de Transporte
O servidor MCP da NFeR suporta Dual-Transport com streaming de eventos e mensagens JSON-RPC:
/v1/mcp/sseTransporte Server-Sent Events (SSE) para conexões contínuas e clientes como Claude Desktop e Cursor.
/v1/mcp/messagesCanal de postagem de mensagens JSON-RPC vinculado à sessão SSE ativa.
/v1/mcpTransporte Streamable HTTP para clientes CLI modernos como Claude Code e agentes autônomos.
2. Autenticação com Company API Key
Para utilizar as ferramentas operacionais de emissão, consulta de Inscrição Estadual (SEFAZ CCC) e cadastros, o assistente deve enviar sua Company API Key em um dos seguintes formatos:
Authorization: Bearer <SUA_COMPANY_API_KEY>(Padrão universal de clientes MCP)X-API-Key: <SUA_COMPANY_API_KEY>(Padrão REST NFeR)
Você pode copiar sua chave em Painel → Configurações → Chaves de API.
Conexão sem chave (Modo Público)
3. Como Conectar seus Assistentes de IA
Claude Desktop
Abra as configurações do Claude Desktop (claude_desktop_config.json) e adicione o bloco abaixo usando mcp-remote:
Cursor IDE
Adicione ao seu arquivo .cursor/mcp.json na raiz do seu projeto ou em Configurações Globais do Cursor:
Claude Code (Terminal CLI)
Adicione o servidor MCP da NFeR diretamente pelo terminal com transporte HTTP streamable:
4. Catálogo de Ferramentas Fiscais Disponíveis
Ferramentas Gratuitas (Sem necessidade de plano ou chave)
| Ferramenta | Descrição | Parâmetros |
|---|---|---|
| consultar_termos_e_privacidade | Consulta oficial aos Termos de Uso, Política de Privacidade e conformidade LGPD da NFER (bases legais de CPF/CNPJ na Receita e SINTEGRA, Lei Felca, Zero Data Retention e guarda de XMLs). | topico: string, documento?: "todos" | "termos" | "privacidade" |
| consultar_documentacao | Busca semântica e por tópicos em toda a documentação técnica oficial da NFeR (endpoints da API REST, modelos de payload JSON de NF-e/NFC-e/NFS-e/CT-e/DC-e, guias de integração, webhooks, cabeçalhos de autenticação e tratamento de erros). | busca: string, limite?: number |
| obter_guia_integracao | Retorna o passo a passo direto para integrar com a API NFeR na linguagem desejada (TypeScript, Node.js, Python, PHP, C#/.NET ou cURL) com exemplos de código prontos para execução. | linguagem?: "typescript" | "nodejs" | "python" | "php" | "csharp" | "curl", topico?: "nfe" | "nfce" | "nfse" | "cte" | "dce" | "webhooks" | "preflight" |
| validar_documento | Validação de CPF, CNPJ (com dígitos verificadores e formato alfanumérico da Receita), chave de 44 dígitos da NF-e e cálculo interestadual de DIFAL. | tipo: "cpf" | "cnpj" | "chave_nfe" | "difal", documento?, difalParams? |
| consultar_status_sefaz | Telemetria ao vivo dos servidores autorizadores das 27 UFs do Brasil e status de contingência SVC-AN e SVC-RS. | uf? (ex: "SP", "RS") |
| diagnosticar_rejeicao_sefaz | Explicação detalhada e diagnóstico de correção para rejeições cStat da SEFAZ (539, 206, 732, 806, 590, 591, 865) e NFS-e (E0037, E0038). | codigoErro: string (ex: "539") |
| consultar_ibge_cidades | Busca de municípios por código IBGE de 7 dígitos ou nome para preenchimento de endereços fiscais e NFS-e. | busca: string, uf?: string |
| consultar_cnae | Consulta da tabela oficial de Classificação Nacional de Atividades Econômicas (CNAE). | termo: string (número ou palavra-chave) |
| consultar_adesao_nfse | Verificação de convênio municipal e adesão oficial ao Sistema Nacional de NFS-e (SEFIN / Receita Federal). | municipioOuIbge: string, uf?: string |
| consultar_indicadores_bacen | Consulta em tempo real da Taxa Selic anual, IPCA acumulado de 12 meses e Câmbio PTAX comercial via Banco Central do Brasil. | Nenhum (automático) |
| classificar_reforma_tributaria | Pré-classificação de mercadorias e serviços segundo as novas regras de IBS e CBS da Reforma Tributária (LC 214/2025). | cClassTrib?, cst?, ano? |
| consultar_cfop | Consulta a tabela oficial do Convênio SINIEF v2.10 (Informe Técnico 2023.002). Busca por código ou operação (ex: "locação", "transporte") e verifica se é autorizado sem Inscrição Estadual (indExcIBSCBS). | termo: string, apenasNfe?: boolean, apenasTransporte?: boolean, apenasExclusivoIbsCbs?: boolean |
| validar_cfop | Validação pré-SEFAZ de CFOP: compatibilidade de UF (interno vs interestadual), validade temporal e autorização para contribuintes sem Inscrição Estadual (Regra I08-191). | cfop: string, isInterestadual?: boolean, emitenteTemIE?: boolean, isCte?: boolean, isNfce?: boolean |
| gerar_danfe_pdf | Converte XML de NF-e (55) ou NFC-e (65) em PDF formatado do DANFE com código de barras pronto para impressão. | xml: string |
Ferramentas Corporativas (Exigem Company API Key)
| Ferramenta | Descrição | Parâmetros |
|---|---|---|
| consultar_cadastro_sefaz_ccc | Consulta oficial de Inscrição Estadual (IE) e situação no Cadastro Centralizado de Contribuintes (CCC / CadConsultaCadastro4) via webservice SEFAZ. | uf: string, cnpj?, cpf?, ie? |
| consultar_cpf | Consulta dados cadastrais de pessoa física na Receita Federal por CPF (Nome completo, Gênero e Data de Nascimento) com redundância e cache. | cpf: string |
| consultar_empresa_emissora | Retorna os dados cadastrais da empresa conectada, CRT, regime tributário, ambiente e endereço fiscal. | Nenhum |
| simular_preflight_nfe | Auditoria e simulação fiscal pré-transmissão: validação de impostos, totalizadores e regras interestaduais sem gerar nota. | nfePayload: object |
| emitir_nfe_homologacao | Emissão real de NF-e no ambiente de testes da SEFAZ (sem valor fiscal), gerando XML assinado e protocolo para homologação. | nfeData: object |
| emitir_nfe_producao | Emissão oficial de NF-e com validade jurídica na SEFAZ. Exige confirmação explícita de segurança contra alucinações de IA. | nfeData: object, confirmar_emissao_real: true |
| consultar_nota_fiscal | Busca status, protocolo, chave e links de download do PDF (DANFE) e XML de notas emitidas pela empresa. | tipoDocumento?: "nfe" | "nfse" | "nfce" | "cte", idOuChave: string |
| consultar_clientes | Busca clientes e destinatários cadastrados por nome, CPF, CNPJ ou e-mail. | busca?: string, limite?: number |
| cadastrar_cliente | Cadastro automático de destinatário/tomador com validação de documento e endereço. | nome: string, cpfCnpj: string, ie?, email?, telefone?, endereco? |
| consultar_produtos | Busca produtos no catálogo da empresa por descrição, SKU ou NCM. | busca?: string, limite?: number |
| cadastrar_produto | Cadastro de produto com SKU, NCM, CEST, CFOP e alíquotas fiscais. | codigo: string, descricao: string, ncm: string, cest?, cfop: string, unidade: string, valorUnitario: number |
| consultar_saldo_emissao | Verificação de consumo mensal, franquia do plano e saldo de notas restantes. | Nenhum |
5. Governança e Trava de Segurança em Produção
Para garantir total segurança jurídica e operacional ao utilizar agentes autônomos e LLMs externos, a NFeR implementa a política Guarded Production:
- Homologação Livre: A ferramenta
emitir_nfe_homologacaopode ser executada livremente pelo assistente para testar fluxos e regras fiscais sem gerar impostos. - Confirmação Deliberada em Produção: A ferramenta
emitir_nfe_producaorejeita qualquer execução a menos que o parâmetroconfirmar_emissao_real: trueseja explicitamente enviado após confirmação do usuário humano.