@notaas/mcp v0.2.0 · 46 tools em produção

Operação fiscal completa
para quem vive no terminal.

Pare de caçar códigos de prefeitura em PDFs ou decifrar rejeições de XML no braço. Conecte o Claude, Cursor ou VS Code à Notaas em 30 segundos. Um comando no chat, nota autorizada.

Streamable HTTP & npxDevice Flow RFC 8628Certificado A1 blindado

NFS-e (23+ Engines)NF-e 55NFC-e 65CT-e 57MDF-e 58IBS/CBS 2026

Conectar em 30 segundos Criar conta grátis →

5 tools abertas sem API Key · Modo somente leitura nativo · Sem falar com vendas

POST /api/mcp HTTP/1.1
Host: platform.notaas.com.br
x-api-key: ntaas_live_9f8a7b6c5d4e
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "nfse_diagnose_error",
    "arguments": {
      "invoiceId": "b7e21c90-4f1a-4b8e-9d12-8a3f90c1e442"
    }
  }
}

platform.notaas.com.br/api/mcptools/call · nfse_diagnose_error

Claude / Cursor / VS Code↓→platform.notaas.com.br/api/mcp↓→SEFAZ / 5.570 Prefeituras↓→Webhook → sua aplicação

46 tools

Catálogo fiscal completo

5.570

Municípios mapeados

< 1ms

Validação local de chaves

5 modelos

NFS-e, NF-e, NFC-e, CT-e e MDF-e

Zero install via HTTP

Aponte sua IDE para platform.notaas.com.br/api/mcp e comece a usar na hora. Sem instalar SDKs ou dependências.

Diagnóstico que resolve

Recebeu erro E0039, E183 ou cStat 539? O MCP analisa a rejeição da prefeitura ou SEFAZ e aponta qual campo do JSON corrigir.

Escala Multi-CNPJ nativa

Software houses gerenciam dezenas ou centenas de clientes em uma única sessão usando Organization Tokens (ntaas_org_*).

// developer experience

Projetado para quem resolve no código
antes de abrir chamado.

Contratos previsíveis, isolamento por escopo e rate limits transparentes. Seu assistente opera com as mesmas travas da API de produção.

Streamable HTTP & npx

Conecte direto na nuvem por HTTP stateless ou execute localmente via npx -y @notaas/mcp. Você escolhe o transporte.

Contrato 1:1 com a API v1

Sem gambiarras nem regras duplicadas. Cada tool valida o payload com Zod e consome a rota oficial da plataforma.

Certificado A1 em 4 modos

Referência local Zero-Trust (stdio), comando read -s no terminal, link Dropzone sem login para o contador ou Base64 para automações.

Device Flow RFC 8628

Sem chave em mãos? O agente gera um código curto, você autoriza no navegador e o token temporário expira em 24h.

Modo Somente Leitura

Ative x-mcp-readonly: true para liberar apenas as 21 tools de consulta e triagem. Zero risco de emissão acidental.

Reforma Tributária nativa

Consulte CST IBS/CBS, cClassTrib e NBS (LC 214/2025) sem sair do editor enquanto constrói sua integração.

// zero to first invoice · v0.2.0

Do editor vazio à `nota autorizada`

Sem preencher formulários intermináveis. O prompt /onboard-new-company conduz o setup ponta a ponta.

ETAPA 01

Pareie sua conta

Sem copiar chaves manualmente. O agente gera um código curto, você autoriza no navegador em 1 clique.

→ notaas_start_account_onboarding

ETAPA 02

Cadastre o CNPJ e Certificado A1

O assistente cria o projeto, alinha a numeração inicial e oferece 4 modos seguros para enviar o Certificado A1 sem vazar a senha no chat.

org_create_certificate_upload_session / org_upload_project_certificate

ETAPA 03

Valide a prontidão

Um checklist automático confere cadastro, validade do certificado, séries, chave definitiva e cobertura municipal.

org_check_project_readiness → ready: true

ETAPA 04

Emita e receba webhooks

Com sua aprovação humana, a nota é transmitida e os eventos assinados (HMAC) chegam no seu endpoint.

POST /api/v1/emitir → 202 Accepted

// certificado digital a1 · 4 modos à sua escolha

Como o Certificado A1 (.pfx) é enviado via MCP?

O agente pergunta como você prefere enviar o certificado e se adapta ao seu cenário — seja sem sair da IDE, pelo terminal ou enviando um link sem login para o contador do cliente.

OPÇÃO 1 · ZERO-PROMPT LEAK (STDIO)Cursor, Claude Code e Windsurf via npx @notaas/mcp

Referência Local Zero-Trust

Você informa apenas o caminho do arquivo (pfxFilePath) e o nome da variável de ambiente (passwordEnvVar) ou arquivo de senha. O processo local do MCP lê direto da sua máquina — o binário e a senha jamais entram no contexto do LLM.

org_upload_project_certificate({ projectId, pfxFilePath: "~/cert.pfx", passwordEnvVar: "NOTAAS_CERT_PASS" })

OPÇÃO 2 · TERMINAL DA IDE (READ -S)Remote HTTP ou Local MCP sem abrir o navegador

One-Liner Silencioso no Terminal

A tool org_create_certificate_upload_session gera um token descartável (TTL 15 min, uso único) e entrega um comando curl com read -s. Você cola no terminal da IDE e digita a senha invisível, fora do histórico da IA.

read -r -s -p 'Senha: ' NOTAAS_PFX_PASS && { curl -H 'x-cert-upload-token: ntaas_cert_up_...' -F '[email protected]' --form-string "password=$NOTAAS_PFX_PASS" ...; unset NOTAAS_PFX_PASS; }

OPÇÃO 3 · DROPZONE SEM LOGINSoftware Houses quando o .pfx está com o cliente ou contador

Link Descartável para Dev ou Contador

A mesma sessão one-time gera o link /onboarding/cert#token=... (o hash #token nunca vai para logs de proxy/Referer). Não exige login Clerk: o contador arrasta o .pfx no celular ou PC e o agente detecta a ativação no chat.

https://platform.notaas.com.br/onboarding/cert#token=ntaas_cert_up_...

OPÇÃO 4 · AUTOMAÇÃO 100% (N8N / API)Workflows autônomos (n8n, LangGraph, cofres corporativos)

Payload Direto Base64 + Senha

Para agentes de backend que buscam o certificado em um Secret Manager (AWS Secrets Manager, Vault) e fazem o provisionamento 100% autônomo via chamada de tool.

org_upload_project_certificate({ projectId, pfxBase64: "MII...", password: "..." })

// onboarding step-by-step por persona

Roteiro passo a passo para o seu perfil de operação

Veja exatamente quais tools o agente aciona em cada etapa dependendo de quem está conduzindo a integração.

Persona 01 · Desenvolvedor Solo / Startup na IDE

Cursor · Claude Code · Windsurf (npx @notaas/mcp)

Sair do zero até a primeira NFS-e/NF-e em homologação sem abrir o painel web.

01Conecte o MCP sem API Key e execute o prompt /onboard-new-company.
02Autorize o código NT-XXXX-XXXX do Device Flow (notaas_start_account_onboarding → notaas_claim_account_onboarding) para receber o token temporário de 24h.
03O agente cria o projeto com org_create_project e verifica a cobertura da cidade com notaas_check_city_coverage.
04Envie o Certificado A1 usando a Opção 1 (pfxFilePath + passwordEnvVar no stdio) ou a Opção 2 (comando read -s no terminal da IDE).
05Gere a Project API Key definitiva (org_create_project_api_key), rode org_check_project_readiness, revogue o token de bootstrap (org_revoke_onboarding_token) e emita a nota de teste.

Persona 02 · Software House / ERP Multi-CNPJ + Contador

Organization Token (ntaas_org_*) · Dezenas ou centenas de clientes

Fazer onboarding de um novo cliente do ERP quando o Certificado A1 está em posse do contador.

01Com seu Organization Token (ntaas_org_*) configurado, peça ao agente para cadastrar a nova filial/cliente via org_create_project.
02Alinhe a série e o último número de RPS/NF-e do sistema legado usando org_configure_project_numbering (modo="avancar").
03Peça ao agente para gerar um link descartável com org_create_certificate_upload_session (Opção 3) e envie o uploadSessionUrl no WhatsApp do contador do cliente.
04O contador abre o link sem precisar de login, arrasta o .pfx e digita a senha; o agente confirma via org_get_project_certificate_status.
05O agente provisiona a Project API Key isolada do cliente e registra o webhook do ERP com webhooks_create_endpoint.

Persona 03 · Engenheiro de Automação (n8n / LangGraph / Backends)

Remote MCP (https://platform.notaas.com.br/api/mcp) · Execução Headless

Provisionar novos emissores e emitir lotes automaticamente em pipelines de IA.

01Conecte o nó MCP Client do n8n ou agente LangGraph ao endpoint stateless https://platform.notaas.com.br/api/mcp enviando x-api-key.
02Crie o projeto via org_create_project informando regime tributário e parâmetros da Reforma Tributária (defaultCstIbscbs, defaultClassificacaoTributaria, defaultNbs).
03Busque o .pfx no cofre de segredos da sua infraestrutura e envie via Opção 4 (org_upload_project_certificate com pfxBase64 + password).
04Valide todos os 5 pré-requisitos de forma determinística (fail-closed) com org_check_project_readiness.
05Dispare emissões unitárias (nfse_emit, nfe_emit, cte_emit, mdfe_emit) ou em lote (nfse_emit_batch) e acompanhe via webhook.

Persona 04 · Analista Fiscal / Contabilidade & Suporte N2

Claude Desktop · ChatGPT · Modo Read-Only (x-mcp-readonly: true)

Auditar notas, consultar regras de IBS/CBS e diagnosticar rejeições sem risco de emitir ou cancelar.

01Conecte o MCP com a flag NOTAAS_MCP_READ_ONLY=true (ou header x-mcp-readonly: true). Todas as tools de escrita e de criação de sessão ficam bloqueadas.
02Valide chaves de 44 dígitos (SEFAZ) e 50 dígitos (NFS-e ADN) e documentos CPF/CNPJ alfanuméricos localmente em < 1ms.
03Consulte códigos LC 116 e desdobros municipais (notaas_lookup_tax_codes) e alíquotas de transição IBS/CBS 2026 (notaas_explain_ibs_cbs_reference).
04Diante de uma nota rejeitada, execute nfse_diagnose_error ou o prompt /diagnose-fiscal-rejection para obter a causa raiz e o campo exato a corrigir.
05Verifique a prontidão cadastral e o vencimento do Certificado A1 de qualquer cliente com org_check_project_readiness.

// integrations

Sua IDE. Seu assistente.
Nossa infraestrutura.

Escolha seu editor, copie o snippet e conecte. Sem chave configurada, as 5 tools públicas e o pareamento via navegador já ficam ativos.

Gerador de configuração 1-clique

Escolha o transporte, selecione sua IDE e copie o snippet pronto para uso.

Streamable HTTP · stdio

01. Modo de transporte

02. Cliente / Editor

03. Chave de API (ntaas_*) ou Org Token (ntaas_org_*) — opcional

// adicione ao seu mcp.json ou claude_desktop_config.json

{
  "mcpServers": {
    "notaas": {
      "url": "https://platform.notaas.com.br/api/mcp",
      "headers": {
        "x-api-key": "ntaas_sua_chave_aqui"
      }
    }
  }
}

Compatível com:Claude CodeCursorWindsurfVS Code CopilotClaude Desktopn8n

// 46 tools + resources + prompts

Catálogo completo de ferramentas.
Não apenas um wrapper de prefeitura.

Da validação local de CPF/CNPJ Alfanumérico ao encerramento de MDF-e na SEFAZ. Selecione a camada abaixo para inspecionar rotas e escopos.

//01

Inteligência Tributária & Cobertura

Consultas abertas de municípios, códigos LC 116, chaves SEFAZ/ADN, CPF/CNPJ e IBS/CBS.

Sem API Key · 20 req/min

#01notaas_check_city_coverage

Read-Only

Consulta cobertura de 5.570 municípios, engine municipal ativa e adesão ao SNNFSE.

GET /api/v1/cobertura/cidadesPública

#02notaas_lookup_tax_codes

Read-Only

Busca códigos cTribNac (LC 116) e desdobros municipais (cTribMun) por IBGE.

GET /api/v1/codigosPública

#03notaas_validate_access_key

Read-Only

Valida Módulo 11 e decodifica chaves de 44 dígitos (SEFAZ) e 50 dígitos (NFS-e ADN).

Local CPU (<1ms)Pública

#04notaas_validate_cpf_cnpj

Read-Only

Valida dígitos verificadores de CPF e CNPJ (numérico e alfanumérico).

Local CPU (<1ms)Pública

#05notaas_explain_ibs_cbs_reference

Read-Only

Referência de CST IBS/CBS, cClassTrib, NBS e cálculo da Reforma Tributária.

Catálogo NT 2025.002-RTCPública

MCP Resources (notaas://*)

notaas://coverage/summaryInventário das 23+ engines NFS-e, SEFAZ e IBS/CBS

notaas://api/quickstartPayloads canônicos, headers e fluxo HTTP 202 + Webhooks

MCP Prompts Guiados

/onboard-new-companySetup completo do Device Flow à primeira nota

/integrate-notaas-apiGera cliente TypeScript, Python, PHP ou cURL

/diagnose-fiscal-rejectionTriagem guiada de rejeições municipais e SEFAZ

// features

Comparativo técnico

A diferença entre um conector básico de consulta e uma infraestrutura fiscal completa para agentes.

Capacidade	Conectores Básicos	Notaas MCP (v0.2.0)
Documentos fiscais suportados	Apenas NFS-e básica e consulta de chave	NFS-e (ADN + 23 engines) + NF-e (55) + NFC-e (65) + CT-e (57) + MDF-e (58)
Ciclo de vida completo	Emitir e consultar status	Emitir, Batch, Cancelar, CC-e, Inutilizar, Encerrar MDF-e e Averbar CT-e
Onboarding sem sair da IDE	Exige copiar chaves manualmente no painel	Device Flow RFC 8628 nativo + checklist Zero-to-First-Invoice
Reforma Tributária (LC 214/2025)	Ausente ou cálculo genérico	Referência determinística de CST IBS/CBS, cClassTrib e NBS
Diagnóstico de rejeições	Retorna o erro bruto da prefeitura	Auto-Triage (nfse_diagnose_error) com causa raiz e campo a corrigir
Gestão Multi-CNPJ (Software Houses)	Preso a 1 único CNPJ estático	Organization Token (ntaas_org_*) para operar centenas de CNPJs

Documentos fiscais suportados

Conectores básicosApenas NFS-e básica e consulta de chave

Notaas MCP (v0.2.0)NFS-e (ADN + 23 engines) + NF-e (55) + NFC-e (65) + CT-e (57) + MDF-e (58)

Ciclo de vida completo

Conectores básicosEmitir e consultar status

Notaas MCP (v0.2.0)Emitir, Batch, Cancelar, CC-e, Inutilizar, Encerrar MDF-e e Averbar CT-e

Onboarding sem sair da IDE

Conectores básicosExige copiar chaves manualmente no painel

Notaas MCP (v0.2.0)Device Flow RFC 8628 nativo + checklist Zero-to-First-Invoice

Reforma Tributária (LC 214/2025)

Conectores básicosAusente ou cálculo genérico

Notaas MCP (v0.2.0)Referência determinística de CST IBS/CBS, cClassTrib e NBS

Diagnóstico de rejeições

Conectores básicosRetorna o erro bruto da prefeitura

Notaas MCP (v0.2.0)Auto-Triage (nfse_diagnose_error) com causa raiz e campo a corrigir

Gestão Multi-CNPJ (Software Houses)

Conectores básicosPreso a 1 único CNPJ estático

Notaas MCP (v0.2.0)Organization Token (ntaas_org_*) para operar centenas de CNPJs

// faq

Perguntas frequentes

O essencial sobre segurança do Certificado A1, autenticação, modo somente leitura e limites.

Preciso criar conta ou ter API Key antes de testar?

Não. Sem API Key você já acessa as 5 tools públicas de inteligência tributária (cobertura de 5.570 cidades, códigos LC 116, validador de chave SEFAZ/ADN, CPF/CNPJ alfanumérico e tabela IBS/CBS) e pode iniciar o pareamento Device Flow pelo próprio chat.

Como é feito o upload do Certificado Digital A1 (.pfx) via MCP?

Você escolhe entre 4 modos seguros: (1) Referência Local Zero-Trust no modo stdio (pfxFilePath + passwordEnvVar, onde o processo local lê o arquivo sem enviar bytes nem senha ao LLM); (2) Comando silencioso read -s + curl no terminal da IDE; (3) Link Dropzone descartável sem login (/onboarding/cert#token=...) para você ou para enviar ao contador do cliente; ou (4) Upload direto via pfxBase64 + password para fluxos autônomos no n8n.

Como impedir que o agente emita ou cancele notas por engano?

Basta ativar o modo somente leitura enviando o header x-mcp-readonly: true (no modo HTTP) ou a variável NOTAAS_MCP_READ_ONLY=true (no modo npx). Nesse modo, o servidor registra apenas as 21 tools de consulta e diagnóstico.

Qual a diferença entre Project API Key (ntaas_) e Org Token (ntaas_org_)?

A Project API Key (ntaas_*) é isolada em um único CNPJ emissor para emitir e consultar notas. O Organization Token (ntaas_org_*) permite a software houses e contabilidades criar projetos, ajustar numeração e gerir múltiplos CNPJs.

Como funciona o token gerado no pareamento Device Flow?

Ao autorizar o código NT-XXXX-XXXX em /onboarding/mcp, a plataforma emite um Organization Token de bootstrap cifrado com AES-256-GCM, entregue uma única vez ao agente e com expiração automática em 24 horas (podendo ser revogado imediatamente via org_revoke_onboarding_token).

Quais documentos fiscais posso operar pelo MCP?

Todos os 5 modelos suportados pela Notaas: NFS-e (Padrão Nacional SNNFSE + 23 engines municipais próprias), NF-e (modelo 55), NFC-e (modelo 65), CT-e 4.00 (modelo 57 com averbação AT&M) e MDF-e 3.00b (modelo 58 com encerramento e alertas de placa).

// ship faster

Pare de lutar com XML. Comece a emitir pelo terminal.

Crie sua conta, conecte o MCP em 1 comando e emita a primeira nota em homologação em minutos.

Criar conta grátis Já tenho conta — Entrar

Operação fiscal completapara quem vive no terminal.

Zero install via HTTP

Diagnóstico que resolve

Escala Multi-CNPJ nativa

Projetado para quem resolve no códigoantes de abrir chamado.

Streamable HTTP & npx

Contrato 1:1 com a API v1

Certificado A1 em 4 modos

Device Flow RFC 8628

Modo Somente Leitura

Reforma Tributária nativa

Do editor vazio à nota autorizada

Pareie sua conta

Cadastre o CNPJ e Certificado A1

Valide a prontidão

Emita e receba webhooks

Como o Certificado A1 (.pfx) é enviado via MCP?

Referência Local Zero-Trust

One-Liner Silencioso no Terminal

Link Descartável para Dev ou Contador

Payload Direto Base64 + Senha

Roteiro passo a passo para o seu perfil de operação

Sua IDE. Seu assistente.Nossa infraestrutura.

Catálogo completo de ferramentas.Não apenas um wrapper de prefeitura.

Inteligência Tributária & Cobertura

MCP Resources (notaas://*)

MCP Prompts Guiados

Comparativo técnico

Documentos fiscais suportados

Ciclo de vida completo

Onboarding sem sair da IDE

Reforma Tributária (LC 214/2025)

Diagnóstico de rejeições

Gestão Multi-CNPJ (Software Houses)

Perguntas frequentes

Preciso criar conta ou ter API Key antes de testar?

Como é feito o upload do Certificado Digital A1 (.pfx) via MCP?

Como impedir que o agente emita ou cancele notas por engano?

Qual a diferença entre Project API Key (ntaas_*) e Org Token (ntaas_org_*)?

Como funciona o token gerado no pareamento Device Flow?

Quais documentos fiscais posso operar pelo MCP?

Pare de lutar com XML. Comece a emitir pelo terminal.

Operação fiscal completa
para quem vive no terminal.

Projetado para quem resolve no código
antes de abrir chamado.

Do editor vazio à `nota autorizada`

Sua IDE. Seu assistente.
Nossa infraestrutura.

Catálogo completo de ferramentas.
Não apenas um wrapper de prefeitura.

Qual a diferença entre Project API Key (ntaas_) e Org Token (ntaas_org_)?