MCP Server de Nota Fiscal Eletrônica: Como Emitir NFS-e, NF-e e NFC-e via Claude, Cursor e IA (@notaas/mcp)

Quando começamos a desenhar a camada de integração para agentes de IA aqui na Notaas, eu tinha uma irritação muito clara com a forma como o mercado de documentos fiscais tratava o Model Context Protocol (MCP). A maioria dos wrappers que surgiram nos últimos meses resume-se a scripts apressados de uma centena de linhas que expõem três ou quatro chamadas GET em cima de um stdio local, exigindo que o desenvolvedor já tenha criado conta no painel web, copiado chaves de API manualmente no .env, configurado inscrição municipal na mão e subido o certificado digital antes mesmo de digitar o primeiro prompt no Cursor ou no Claude Code.

Isso quebra o fluxo de quem está construindo software com agentes. Se você está no meio de uma sessão de Vibe Coding fiscal com Cursor, Lovable, v0 e Next.js, ter que interromper o raciocínio do agente para abrir cinco abas do navegador, procurar onde fica o menu de numeração de RPS e descobrir qual código de serviço municipal usar derrota toda a proposta de produtividade da engenharia assistida por IA.

Foi para resolver esse abismo entre "um wrapper de leitura" e uma plataforma fiscal verdadeiramente agent-native que lançamos o @notaas/mcp v0.2.1. Ele não é apenas um adaptador para consultar notas: é um servidor MCP completo com 44 Tools, Resources dinâmicos (notaas://*), Prompts especializados, suporte a transporte dual (stdio local via CLI e Remote MCP Server via Streamable HTTP) e o primeiro fluxo de Agentic Onboarding (RFC 8628 adaptado) do ecossistema fiscal brasileiro — permitindo sair do zero absoluto até a primeira nota fiscal autorizada sem sair do terminal.

O problema dos servidores MCP fiscais de primeira geração

Antes de abrir o código e a topologia da nossa infraestrutura, vale entender por que um servidor MCP para documentos fiscais eletrônicos exige muito mais do que mapear um Swagger para JSON Schema.

No Brasil, uma operação fiscal real raramente é isolada. Uma software house ou um SaaS B2B começa emitindo NFS-e Nacional e municipal via API, logo precisa emitir NF-e Modelo 55 para venda de equipamentos ou NFC-e Modelo 65 no ponto de venda, e em pouco tempo passa a gerenciar dezenas de clientes PJ em uma arquitetura multi-tenant.

Quando analisamos conectores básicos do mercado — como o MCP da NFE.io —, esbarramos em limitações arquiteturais severas para quem opera em produção:

Um agente de IA só é tão capaz quanto a superfície de ferramentas e garantias de segurança que o servidor MCP entrega a ele.

Se o servidor MCP não conhece as regras da Reforma Tributária (IBS e CBS) e a correlação do Anexo VIII, o LLM vai alucinar códigos de serviço e você vai descobrir o erro apenas quando a prefeitura rejeitar o lote. No @notaas/mcp, o próprio agente consulta os parâmetros reais do município IBGE e a matriz de tributação antes de escrever uma única linha de código ou disparar a requisição.

Arquitetura de Transporte Dual: stdio Local e Remote Streamable HTTP

Quando projetamos o @notaas/mcp, sabíamos que os desenvolvedores utilizam agentes em dois cenários distintos: em máquinas locais de desenvolvimento (Cursor, Claude Desktop, Windsurf, Claude Code CLI) e em ambientes de nuvem ou pipelines de agentes autônomos onde rodar subprocessos Node.js via stdio é inviável ou lento.

Por isso, o @notaas/mcp v0.2.1 opera sob uma arquitetura de transporte dual:

1. Transporte Local via stdio (npx -y @notaas/mcp)

Para quem está na IDE local, o pacote publicado no npm inicializa instantaneamente via StdioServerTransport do SDK oficial @modelcontextprotocol/sdk. Ele lê as credenciais das variáveis de ambiente (NOTAAS_API_KEY para escopo de projeto único ou NOTAAS_ORG_TOKEN para escopo multi-tenant da Org API) ou inicia em modo unauthenticated bootstrap caso você queira que o próprio agente crie sua conta usando o Device Flow.

2. Remote MCP Server (https://platform.notaas.com.br/api/mcp)

Para clientes modernos que suportam o padrão Streamable HTTP do protocolo MCP, disponibilizamos um endpoint remoto gerenciado de alta disponibilidade em https://platform.notaas.com.br/api/mcp.

Na nossa infraestrutura de produção, esse servidor não roda misturado com o monólito web. Nós o isolamos em uma stack dedicada (notaas-mcp) no nosso cluster Docker Swarm, operando com WebStandardStreamableHTTPServerTransport em modo estritamente stateless.

+-------------------------------------------------------------------------+
| Cliente MCP (Claude Code, Cursor, Windsurf, Custom AI Agent)            |
+------------------------------------+------------------------------------+
                                     |
             +-----------------------+-----------------------+
             |                                               |
             v (Modo Local: stdio)                           v (Modo Remoto: HTTPS)
+----------------------------+             +------------------------------+
| npx -y @notaas/mcp         |             | Cloudflare Edge Proxy        |
| Processo local Node.js     |             | Validação de IP + WAF        |
+-------------+--------------+             +--------------+---------------+
              |                                           |
              |                            +--------------v---------------+
              |                            | Stack Docker Swarm:          |
              |                            | notaas-mcp (Stateless HTTP)  |
              |                            | Rate Limit: Bounded LRU      |
              +--------------+-------------+--------------+---------------+
                             |                            |
                             v                            v
              +-----------------------------------------------------------+
              | Notaas Core API & Fiscal Workers (mTLS SEFAZ / SNNFSE)    |
              +-----------------------------------------------------------+

Revisando a camada de borda na semana passada, implementamos três proteções críticas nesse servidor remoto:

• Validação Estrita de Proxy Cloudflare: O container do notaas-mcp valida a origem de rede e só confia no header CF-Connecting-IP quando a conexão provém comprovadamente das faixas CIDR oficiais da Cloudflare, prevenindo IP spoofing.
• Rate Limiting com Bounded LRU Cache: Cada IP e token de autorização passa por um limitador de taxa em memória com estrutura Bounded Least Recently Used (LRU), impedindo que um loop infinito de um agente mal configurado esgote a memória do worker (OOM) ou cause negação de serviço.
• Isolamento Stateless por Requisição: Nenhuma chave de API ou estado de sessão de cliente fica retido na memória entre requisições HTTP no servidor remoto. O cabeçalho Authorization: Bearer <token> é injetado no contexto de execução efêmero daquela chamada e descartado imediatamente após o término do stream.

Você pode explorar todas as ferramentas, testar payloads e copiar os blocos de configuração diretamente no nosso catálogo interativo em platform.notaas.com.br/mcp.

Como configurar o @notaas/mcp no Claude Code, Cursor e Windsurf

A configuração leva menos de um minuto. Se você já possui uma chave de API de projeto (ntaas_live_... ou ntaas_test_...) ou um token de organização (ntaas_org_...), basta adicionar o bloco mcpServers no arquivo de configuração do seu editor. E se você ainda não tem conta na Notaas, pode omitir as variáveis de ambiente e pedir para o agente iniciar o onboarding automático (que explicarei na próxima seção).

Opção A: Configuração via npx (stdio local — Recomendado para Cursor e Claude Desktop)

Adicione no seu ~/.cursor/mcp.json, ~/.codeium/windsurf/mcp_config.json ou claude_desktop_config.json:

{
  "mcpServers": {
    "notaas": {
      "command": "npx",
      "args": ["-y", "@notaas/mcp"],
      "env": {
        "NOTAAS_API_KEY": "ntaas_test_sua_chave_de_projeto_aqui",
        "NOTAAS_ORG_TOKEN": "ntaas_org_seu_token_multi_cnpj_opcional"
      }
    }
  }
}

No Claude Code CLI, você também pode adicionar com um único comando no terminal:

claude mcp add notaas -- npx -y @notaas/mcp

Opção B: Configuração via Remote MCP Server (Streamable HTTP — Zero Instalação Local)

Se você prefere não executar processos locais via npx e quer conectar diretamente ao nosso cluster remoto via HTTPS:

{
  "mcpServers": {
    "notaas-remote": {
      "url": "https://platform.notaas.com.br/api/mcp",
      "headers": {
        "Authorization": "Bearer ntaas_test_sua_chave_de_projeto_aqui"
      }
    }
  }
}

As 44 Tools do @notaas/mcp: Do Emitente Único à Org API Multi-Tenant

Diferente de ferramentas que apenas disparam um JSON genérico, nós dividimos as 44 Tools do @notaas/mcp v0.2.1 em domínios claros para que o planejador do LLM (como o Claude 3.7 Sonnet ou Claude 4 Opus) escolha a ferramenta exata sem ambiguidade de parâmetros:

1. Agentic Onboarding & Bootstrap (3 Tools):
   • notaas_start_account_onboarding: Inicia o fluxo RFC 8628 gerando o user_code (NT-XXXX-XXXX) e a URL de ativação.
   • notaas_claim_account_onboarding: Faz o claim criptografado do token temporário de organização após autorização do usuário no navegador.
   • org_revoke_onboarding_token: Revoga o token de bootstrap assim que o setup do projeto e da API Key definitiva é concluído.
2. Org API & Provisionamento Multi-CNPJ (9 Tools):
   • org_list_projects, org_create_project, org_get_project, org_update_project: Gestão programática completa de múltiplos CNPJs emitentes (conheça a fundo nossa Org API para múltiplos CNPJs).
   • org_configure_project_numbering: Parametriza séries e numeração inicial de RPS, DPS, NF-e, NFC-e, CT-e e MDF-e por ambiente (homologação e produção).
   • org_get_project_certificate_status: Verifica validade, titularidade ICP-Brasil e expiração do Certificado A1 e gera o link seguro de upload (uploadUrl).
   • org_check_project_readiness: Executa um health check completo do CNPJ (dados cadastrais, inscrição municipal, regime tributário, certificado digital e séries) antes da primeira emissão.
   • org_create_project_api_key, org_list_project_api_keys: Gera chaves de API isoladas por cliente/CNPJ.
3. NFS-e Nacional e Municipal — 4.782 Cidades (8 Tools):
   • nfse_emitir, nfse_consultar, nfse_listar, nfse_cancelar, nfse_baixar_xml, nfse_baixar_pdf (com geração local instantânea do DANFSe v2.0 NT-008), nfse_consultar_municipio e nfse_validar_ibs_cbs.
4. NF-e Modelo 55 e NFC-e Modelo 65 (12 Tools):
   • Emissão síncrona/assíncrona (nfe_emitir, nfce_emitir), consulta por chave de 44 dígitos, carta de correção eletrônica (nfe_carta_correcao), inutilização de faixa numérica (nfe_inutilizar), cancelamento por evento, download de DANFE/DANFE-NFC-e e cálculo prévio de impostos (ICMS, PIS, COFINS, IPI e vTotTrib da Lei da Transparência).
5. CT-e Modelo 57 e MDF-e Modelo 58 — Transporte e Logística (8 Tools):
   • Emissão de Conhecimento de Transporte Eletrônico (cte_emitir), Manifesto Eletrônico de Documentos Fiscais (mdfe_emitir), encerramento de MDF-e (mdfe_encerrar), inclusão de condutor e consulta de status na SEFAZ.
6. Webhooks, Eventos & Diagnóstico (4 Tools):
   • Configuração de endpoints de webhook com segredo HMAC SHA-256 (webhook_configure), listagem de entregas falhas, reenvio manual (replay) de eventos e consulta de status dos autorizadores estaduais/federais.

Além das tools, o servidor expõe MCP Resources nativos (como notaas://schemas/nfse-emitir, notaas://schemas/nfe-emitir e notaas://docs/erros-comuns) que permitem ao agente ler a especificação exata de cada campo sem gastar chamadas HTTP extras.

"Zero to First Invoice": Como funciona a engenharia do Agentic Onboarding (RFC 8628)

Esse é o ponto da arquitetura do @notaas/mcp do qual mais me orgulho como engenheiro. Nós nos fizemos a seguinte pergunta: como permitir que um desenvolvedor abra o Claude Code sem ter conta na Notaas, peça ao agente para configurar o faturamento da empresa dele e emita uma nota fiscal real em 3 minutos, sem jamais expor senhas ou arquivos de certificado digital .pfx na janela de contexto do LLM?

A resposta foi desenhar um protocolo de Agentic Onboarding inspirado no OAuth 2.0 Device Authorization Grant (RFC 8628), combinado com criptografia autenticada AES-256-GCM e secure browser hand-off para ativos sensíveis.

Veja o fluxo arquitetural passo a passo:

⚡ Fluxo Arquitetural: Agentic Onboarding & Emissão Zero-Touch (@notaas/mcp):

• 1. Início do Device Flow (notaas_start_account_onboarding): O agente chama a tool pública sem precisar de API Key. O backend da Notaas gera um device_code de alta entropia, um user_code curto no formato NT-XXXX-XXXX e retorna a URL https://platform.notaas.com.br/onboarding/mcp?code=NT-XXXX-XXXX.
• 2. Autorização Humana e Criptografia no Banco: O desenvolvedor clica no link exibido no chat da IDE, faz login (ou cria a conta gratuitamente em 1 clique com GitHub/Google) e confirma o código NT-XXXX-XXXX. Nesse instante, a plataforma gera um Organization Token temporário (TTL estrito de 24 horas) e o armazena criptografado no banco com AES-256-GCM, usando chave derivada via HKDF-SHA256 a partir do device_code + segredo do servidor e AAD (Additional Authenticated Data) vinculado à sessão.
• 3. Resgate pelo Agente (notaas_claim_account_onboarding): O agente no Cursor/Claude faz o claim enviando o device_code. O servidor descriptografa o token em memória, entrega o ntaas_org_... para a sessão do MCP e limpa o ciphertext do banco (consumo único one-time read).
• 4. Provisionamento do CNPJ (org_create_project + org_configure_project_numbering): Com o token de organização em mãos, o agente cadastra o CNPJ emitente, preenche endereço/inscrição municipal e configura a série e numeração inicial das notas.
• 5. Hand-off Seguro do Certificado A1 (org_get_project_certificate_status): Para evitar que o arquivo .pfx/.p12 ou a senha do certificado passem pelo prompt da IA (enviados para servidores da Anthropic/OpenAI), a tool retorna uploadUrl: "https://platform.notaas.com.br/certificates?projectId=...". O usuário faz o upload direto no cofre da Notaas pelo navegador.
• 6. Validação, Emissão e Auto-Revogação (org_check_project_readiness ➔ nfse_emitir ➔ org_revoke_onboarding_token): O agente verifica que o certificado está ativo e válido, gera a API Key definitiva do projeto, emite a primeira nota fiscal e revoga o token temporário de bootstrap.

Por que o Hand-off do Certificado A1 fora do contexto do LLM é inegociável?

Eu já vi desenvolvedores tentando converter arquivos .pfx em Base64 e colando junto com a senha dentro do chat do Cursor para pedir que um script subisse o certificado em uma API fiscal. Nunca faça isso.

Quando você cola um certificado ICP-Brasil A1 e sua senha em uma janela de chat de IA, esse segredo — que tem poder jurídico de assinatura em nome da sua empresa perante a Receita Federal — fica registrado nos logs de conversação do provedor de IA, em arquivos de histórico locais no disco e potencialmente em telemetria de contexto.

No @notaas/mcp, nós bloqueamos deliberadamente qualquer tentativa de enviar bytes de certificado via MCP Tool. Quando o agente chama org_get_project_certificate_status, ele recebe apenas os metadados seguros:

{
  "projectId": "proj_01j8x9k2m4n5p6q7r8s9t0",
  "hasCertificate": false,
  "status": "MISSING",
  "uploadUrl": "https://platform.notaas.com.br/certificates?projectId=proj_01j8x9k2m4n5p6q7r8s9t0",
  "instructionsForAgent": "Ask the user to open uploadUrl in their browser to securely upload the .pfx/.p12 certificate and password directly to Notaas Vault. Never ask the user to paste the certificate password in the chat."
}

Assim que você arrasta o arquivo .pfx na tela aberta pelo link uploadUrl, o agente chama org_check_project_readiness, detecta que "hasCertificate": true e "certificateSubjectCnpj" bate com o projeto, e prossegue imediatamente para a emissão da nota.

Exemplo Prático: Do Prompt à Primeira Nota Emitida e Código Gerado

Para mostrar como essa experiência funciona na prática dentro do Claude Code ou do Cursor, veja o que acontece quando você inicia um projeto novo e digita:

"Quero configurar a emissão de NFS-e para o meu SaaS (CNPJ 12.345.678/0001-95, São Paulo/SP) na Notaas, emitir uma nota de teste de R$ 150,00 em homologação e depois criar o service em TypeScript no meu repositório Next.js."

Sem que você precise abrir a documentação, o agente executa a seguinte sequência determinística de chamadas MCP:

1. Chama notaas_start_account_onboarding e exibe: Para autorizar este agente na sua conta Notaas, acesse https://platform.notaas.com.br/onboarding/mcp?code=NT-8492-KLPX e confirme o código NT-8492-KLPX.
2. Após o seu clique no navegador, chama notaas_claim_account_onboarding e assume o token temporário.
3. Chama org_create_project passando o CNPJ 12345678000195, código IBGE 3550308 e regime tributário.
4. Chama org_configure_project_numbering definindo a série 1 e número inicial 1 para homologação.
5. Verifica o status com org_check_project_readiness, dispara nfse_emitir em homologação e já devolve no seu terminal o link do DANFSe v2.0 em PDF gerado localmente e a chave de acesso de 50 dígitos.
6. Por fim, chama org_create_project_api_key para gerar a chave restrita daquele projeto, escreve o arquivo .env.local e gera o cliente HTTP tipado na sua codebase, finalizando com org_revoke_onboarding_token.

Tudo isso aproveitando o plano gratuito da Notaas: 20 notas fiscais gratuitas por mês em produção real (para 1 CNPJ) e até 5 projetos simultâneos grátis em homologação via Org API, sem exigir cartão de crédito. Quando sua operação escalar para múltiplos clientes PJ em produção, o Plano Dev (R$ 99/mês) inclui até 3 CNPJs e o Plano SaaS Pro (R$ 249/mês) libera CNPJs ilimitados via Org API.

Próximos Passos: Conecte seu Agente Agora

A era em que integrar documentos fiscais no Brasil custava duas semanas de leitura de manuais XSD da SEFAZ e testes cegos em SOAP acabou. Com o @notaas/mcp v0.2.1, seu agente de IA no Cursor, Windsurf ou Claude Code passa a enxergar toda a infraestrutura fiscal brasileira — de NFS-e em mais de 4.780 municípios até NF-e, NFC-e, CT-e e MDF-e — como ferramentas nativas, tipadas e seguras.

• Explore o Catálogo Interativo de Tools MCP: Acesse platform.notaas.com.br/mcp para inspecionar as 44 tools e copiar o snippet para a sua IDE.
• Crie sua Conta Gratuita (ou faça via Agentic Onboarding): Comece com 20 notas grátis/mês em produção real e até 5 CNPJs em homologação em platform.notaas.com.br/sign-up.
• Consulte a Documentação Oficial: Veja todos os detalhes de contratos REST, Webhooks HMAC SHA-256 e guias do MCP em docs.notaas.com.br.