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.2. Ele não é apenas um adaptador para consultar notas: é um servidor MCP completo com 46 Tools, Resources dinâmicos (notaas://*), Prompts especializados, suporte a transporte dual (stdio local via CLI e Remote MCP Server via Streamable HTTP), 4 modos seguros para envio do Certificado Digital A1 (.pfx) 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.2 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. Além disso, no modo stdio local, ele habilita a Referência Local Zero-Trust para Certificado A1 (pfxFilePath + passwordEnvVar), permitindo que o processo Node.js local leia o arquivo .pfx direto da sua máquina sem jamais enviar os bytes ou a senha para o provedor de LLM.

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 x-api-key (ou 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_...) 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_sua_chave_de_projeto_ou_ntaas_org_token"
      }
    }
  }
}

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

claude mcp add notaas -e NOTAAS_API_KEY=ntaas_sua_chave -- 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": {
      "url": "https://platform.notaas.com.br/api/mcp",
      "headers": {
        "x-api-key": "ntaas_sua_chave_de_projeto_ou_ntaas_org_token"
      }
    }
  }
}

Modo Somente Leitura (21 Tools): Quer usar o MCP apenas para auditoria fiscal, consulta de regras de IBS/CBS e diagnóstico de rejeições sem risco de emissão ou cancelamento acidental? Basta enviar o header "x-mcp-readonly": "true" (no modo HTTP) ou "NOTAAS_MCP_READ_ONLY": "true" (no modo npx). O servidor registra exclusivamente as 21 tools de consulta e triagem.

As 46 Tools do @notaas/mcp: Das Consultas Públicas ao Onboarding e Multi-CNPJ

Diferente de ferramentas que apenas disparam um JSON genérico, nós dividimos as 46 Tools do @notaas/mcp v0.2.2 em 6 camadas claras para que o planejador do LLM escolha a ferramenta exata sem ambiguidade de parâmetros:

1. Camada 1 — Inteligência Tributária & Cobertura Pública (5 Tools · Sem API Key):
   • notaas_check_city_coverage: Consulta cobertura de 5.571 municípios, engine municipal ativa (snnfse + 26 engines próprias) e adesão ao SNNFSE.
   • notaas_lookup_tax_codes: Busca códigos cTribNac (LC 116) e desdobros municipais (cTribMun) por IBGE.
   • notaas_validate_access_key: Valida Módulo 11 e decodifica chaves de 44 dígitos (SEFAZ) e 50 dígitos (NFS-e ADN) localmente em < 1ms.
   • notaas_validate_cpf_cnpj: Valida dígitos verificadores de CPF e CNPJ (numérico tradicional e alfanumérico 2026).
   • notaas_explain_ibs_cbs_reference: Referência de CST IBS/CBS, cClassTrib, NBS e cálculo da Reforma Tributária (NT 2025.002-RTC).
2. Camada 2 — NFS-e Municipal & Nacional (6 Tools · Project Key ntaas_*):
   • nfse_emit, nfse_emit_batch (lotes de até 100 notas), nfse_get_status, nfse_get_batch_status, nfse_cancel e nfse_diagnose_error (Auto-Triage que analisa a rejeição da prefeitura e aponta o campo exato do JSON a corrigir).
3. Camada 3 — NF-e Modelo 55 & NFC-e Modelo 65 (5 Tools · SEFAZ MOC 7.0):
   • nfe_emit (com suporte a DIFAL, ICMS-ST, IPI, vTotTrib, devolução, exportação e IBS/CBS), nfe_get_status, nfe_cancel, nfe_send_carta_correcao (CC-e 110110) e nfe_inutilizar_numeracao.
4. Camada 4 — CT-e 4.00 (57) & MDF-e 3.00b (58) — Transporte e Logística (9 Tools):
   • cte_emit, cte_get_status, cte_cancel, cte_averbar (averbação de seguro de carga AT&M), mdfe_emit, mdfe_get_status, mdfe_encerrar, mdfe_cancel e mdfe_list_open_alerts (previne bloqueio de placa na SEFAZ por manifesto não encerrado).
5. Camada 5 — White-Label Multi-CNPJ & Webhooks (10 Tools · Org Token ntaas_org_*):
   • org_list_projects, org_get_project, org_create_project, org_update_project, org_get_settings, org_list_project_api_keys, org_create_project_api_key, webhooks_list_endpoints, webhooks_list_deliveries e webhooks_test_endpoint (conheça a fundo nossa Org API para múltiplos CNPJs).
6. Camada 6 — Agentic Onboarding v0.2.2 & Prontidão Fiscal (11 Tools):
   • Pareamento Device Flow: notaas_start_account_onboarding e notaas_claim_account_onboarding (emissão one-time do token temporário de 24h cifrado com AES-256-GCM) + org_revoke_onboarding_token.
   • Certificado Digital A1 em 4 Modos Seguros: org_get_project_certificate_status, org_create_certificate_upload_session (sessão one-time de 15 min com comando read -s no terminal ou link Dropzone sem login /onboarding/cert#token=...) e org_upload_project_certificate (referência local Zero-Trust no stdio via pfxFilePath + passwordEnvVar ou Base64 direto).
   • Numeração, Identidade Visual, Webhooks e Gate Fail-Closed: org_get_project_numbering, org_configure_project_numbering, org_upload_project_logo, webhooks_create_endpoint e org_check_project_readiness.

Além das 46 tools, o servidor expõe MCP Resources (notaas://coverage/summary e notaas://api/quickstart) e MCP Prompts guiados (/onboard-new-company, /integrate-notaas-api e /diagnose-fiscal-rejection).

"Zero to First Invoice": Como funciona a engenharia do Agentic Onboarding (RFC 8628) e os 4 Modos de Certificado A1

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 na janela de contexto do LLM e sem obrigar o cliente ou contador a ter login no painel?

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, 4 modos seguros de upload de Certificado Digital A1 e sincronização automática com o checklist de onboarding da organização (onboarding_objectives).

Veja o fluxo arquitetural passo a passo:

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

• 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) 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 e Promoção do Projeto Placeholder (org_create_project + org_configure_project_numbering): O agente cadastra o CNPJ emitente, preenche endereço/inscrição municipal e configura a série e numeração inicial das notas. Ao configurar um projeto fiscal real, a plataforma sincroniza automaticamente as etapas company_data, fiscal_config e nfe_config no checklist da organização e substitui/promove automaticamente o projeto placeholder inicial ("Projeto Padrão" / CNPJ 00.000.000/0000-00), sem afetar nenhum projeto real existente.
• 5. Upload do Certificado A1 em 4 Modos Seguros (org_upload_project_certificate / org_create_certificate_upload_session): O agente adapta o envio do .pfx ao seu cenário — via referência local Zero-Trust no stdio, one-liner silencioso read -s no terminal da IDE, link Dropzone descartável sem login (/onboarding/cert#token=...) para o contador ou Base64 para automações.
• 6. Validação, Emissão e Auto-Revogação (org_check_project_readiness ➔ nfse_emit ➔ org_revoke_onboarding_token): O agente verifica que os 5 pré-requisitos estão verdes (ready: true), gera a API Key definitiva do projeto, emite a primeira nota fiscal com aprovação humana e revoga o token temporário de bootstrap.

Os 4 Modos Seguros de Upload do Certificado Digital A1 (.pfx) no @notaas/mcp v0.2.2

Colar o arquivo .pfx e digitar a senha diretamente no chat de uma IA comum grava sua chave privada ICP-Brasil no histórico do provedor de LLM. Ao mesmo tempo, obrigar o desenvolvedor ou o contador do cliente a criar login no painel web quebra a experiência de onboarding.

Por isso, no @notaas/mcp v0.2.2, entregamos 4 modos seguros que cobrem desde o desenvolvedor solo na IDE até a Software House que precisa coletar o certificado com o contador do cliente:

Veja como funcionam os dois fluxos mais utilizados na prática:

// Opção 1 (Modo stdio Zero-Trust): o LLM envia apenas o caminho local e o nome da env var.
// Quem lê o arquivo .pfx e a senha do disco é o processo Node.js local na sua máquina!
{
  "tool": "org_upload_project_certificate",
  "arguments": {
    "projectId": "80fa29d9-edc3-400c-8300-68e9390948ab",
    "pfxFilePath": "~/Downloads/certificado_empresa_a1.pfx",
    "passwordEnvVar": "NOTAAS_CERT_PASS"
  }
}

E quando o certificado está com o contador do cliente ou você está usando o Remote MCP Server (https://platform.notaas.com.br/api/mcp), o agente chama org_create_certificate_upload_session, que cria um token efêmero de uso único (ntaas_cert_up_<64_hex>, salvo apenas como hash SHA-256 no banco, TTL de 15 minutos e trava de segurança após 5 tentativas de senha):

{
  "sessionId": "0d19b1a6-512c-437b-95bb-2ca1f55a098f",
  "projectId": "80fa29d9-edc3-400c-8300-68e9390948ab",
  "uploadSessionUrl": "https://platform.notaas.com.br/onboarding/cert#token=ntaas_cert_up_9f8e7d...",
  "terminalCommand": "read -r -s -p 'Senha do Certificado A1: ' NOTAAS_PFX_PASS && echo '' && { curl -sS -X POST 'https://platform.notaas.com.br/api/v1/mcp/certificate-upload' -H 'x-cert-upload-token: ntaas_cert_up_9f8e7d...' -F 'file=@/caminho/para/certificado.pfx' --form-string \"password=$NOTAAS_PFX_PASS\"; unset NOTAAS_PFX_PASS; }",
  "expiresAt": "2026-10-31T15:15:00.000Z",
  "ttlMinutes": 15
}

Note um detalhe importante de segurança na Opção 3 (uploadSessionUrl): o token viaja no fragmento de URL (#token=...), o que garante que ele nunca seja enviado em cabeçalhos HTTP Referer nem fique gravado em logs de proxies intermediários. O contador abre o link no celular ou computador sem precisar de login Clerk, arrasta o .pfx, digita a senha, a plataforma valida se o titular X.509 ICP-Brasil pertence ao CNPJ do projeto, ativa o certificado no cofre S3 e marca automaticamente o objetivo certificate no funil de onboarding!

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, enviar meu certificado A1 e emitir uma nota de teste de R$ 150,00 em homologação."

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 (promovendo automaticamente o projeto placeholder inicial e marcando company_data e fiscal_config no onboarding).
4. Chama org_configure_project_numbering definindo a série 1 e número inicial 1 para homologação.
5. Envia o Certificado A1 via org_upload_project_certificate (Opção 1 pfxFilePath + passwordEnvVar) ou gera a sessão one-time com org_create_certificate_upload_session (Opções 2 e 3).
6. Chama org_create_project_api_key para gerar a chave definitiva ntaas_..., valida todos os 5 pré-requisitos em org_check_project_readiness (ready: true), dispara nfse_emit em homologação com sua aprovação humana e finaliza 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.2, seu agente de IA no Cursor, Windsurf ou Claude Code passa a enxergar toda a infraestrutura fiscal brasileira — de NFS-e nos 5.571 municípios (SNNFSE + 26 engines próprias) 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 46 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 do MCP: Veja todos os detalhes dos 4 modos de Certificado A1, roteiros por persona e contratos REST em docs.notaas.com.br/mcp.