Servidor MCP (IA): Visão Geral e Arquitetura
Conecte Claude Desktop, Cursor e agentes autônomos 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.
O Potencial do Servidor MCP: Muito Além de Integrar Código
Diferente de um simples gerador de código, o conector oficial da NFER transforma qualquer assistente de IA em um verdadeiro operador fiscal autônomo com acesso direto a 25 ferramentas ativas:
Emita NF-e de produto ou NFS-e de serviço apenas descrevendo a venda ou a comissão em linguagem natural.
Anexe a nota fiscal de um fornecedor ou imobiliária para o assistente extrair valores e emitir a respectiva nota no ADN.
Consulte Inscrição Estadual, situação cadastral e endereço oficial no webservice da SEFAZ antes de faturar.
Cancele notas dentro do prazo legal ou emita Carta de Correção Eletrônica respeitando as vedações do Ajuste SINIEF.
O assistente analisa códigos de erro SEFAZ (ex: 539, 206, 732), explica a causa raiz e corrige o payload na hora.
Classifica produtos e serviços segundo a LC 214/2025, sugerindo códigos cClassTrib, CST e alíquotas do IVA Dual.
Busca em toda a documentação da API, guias de código por linguagem (TypeScript, Kotlin, Swift, Python, PHP, Go), 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, cadastros automáticos e ferramentas do Monitor Fiscal (consulta e manifestação de notas recebidas nos Planos Corporate e Enterprise).
O conector MCP não serve apenas para escrever código: ele permite emitir notas em linguagem natural, ler PDFs anexados, auditar cadastros no CCC da SEFAZ e diagnosticar erros ao vivo. Acesse a demonstração completa na página oficial em nfer.me/mcp.
1. Endpoints e Tecnologias de Transporte
O servidor MCP da NFER suporta Dual-Transport com streaming de eventos e mensagens JSON-RPC:
| Transporte | Método e Rota | Descrição e Compatibilidade |
|---|---|---|
| Server-Sent Events (SSE) | GET /v1/mcp/sse | Transporte Server-Sent Events (SSE) para conexões contínuas e clientes como Claude Desktop e Cursor. |
| Canal de Mensagens SSE | POST /v1/mcp/messages | Canal de postagem de mensagens JSON-RPC vinculado à sessão SSE ativa. |
| Streamable HTTP | POST /v1/mcp | Transporte 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.
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, tipoItem (SPED 0200) e Perfil Fiscal para cálculo automático de CFOP e impostos. | codigo: string, descricao: string, ncm: string, tipoItem?: string (padrão "00"), cest?: string, cfop?: string (exceção opcional), unidade: string, valorUnitario: number |
| consultar_saldo_emissao | Verificação de consumo mensal, franquia do plano e saldo de notas restantes. | Nenhum |
consultar_notas_recebidasPlano Corporate / Enterprise | Busca e consulta notas fiscais de compras (NF-e Modelo 55) capturadas pelo Monitor Fiscal SEFAZ com filtros por fornecedor, chave de 44 dígitos ou status de manifestação. | busca?: string, statusManifestacao?: "SEM_MANIFESTO" | "CIENCIA" | "CONFIRMADA" | "DESCONHECIDA" | "RECUSADA", limite?: number |
manifestar_nfe_recebidaPlano Corporate / Enterprise | Registra Manifestação do Destinatário (MD-e) oficial na SEFAZ Nacional: Ciência (210210), Confirmação (210200), Desconhecimento (210220) ou Recusa de Carga (210240). | idOuChave: string, evento: "CIENCIA" | "CONFIRMACAO" | "DESCONHECIMENTO" | "RECUSA", justificativa?: string |
consultar_status_monitor_fiscalPlano Corporate / Enterprise | Verifica o status da sincronização periódica (1h) com a SEFAZ, cursor ultNSU, maxNSU, data da última busca e tempo de cooldown. | 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.