NotaasDocs
Dashboard →
@notaas/mcp v0.2.0 · 46 Tools · Streamable HTTP & stdio

Notaas MCP Server & Agentic Onboarding

Conecte assistentes de IA (Claude Code, Cursor, Windsurf, VS Code Copilot, Claude Desktop e n8n) diretamente à API v1 da Notaas via Model Context Protocol (MCP). Realize desde o onboarding completo de um novo CNPJ (Zero to First Invoice) até a emissão e diagnóstico de NFS-e, NF-e (55), NFC-e (65), CT-e (57) e MDF-e (58).

Abrir Vitrine Interativa & Gerador de Config (/mcp)

1. Como Conectar (Remote HTTP vs. Local npx)

O @notaas/mcp suporta os dois transportes oficiais da especificação MCP. Se você conectar sem API Key, as 5 tools públicas de inteligência tributária e o pareamento Device Flow RFC 8628 já ficam imediatamente disponíveis.

Opção A — Remote MCP Server (Streamable HTTP · Zero Instalação)

// ~/.cursor/mcp.json ou configuração do Claude Code / Windsurf
{
  "mcpServers": {
    "notaas": {
      "url": "https://platform.notaas.com.br/api/mcp",
      "headers": {
        "x-api-key": "ntaas_sua_project_key_ou_ntaas_org_token"
      }
    }
  }
}

Opção B — Execução Local via npx (stdio · Habilita Referência Local Zero-Trust para PFX)

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

2. Como Funciona o Upload do Certificado Digital A1 (.pfx) via MCP

Durante o onboarding de uma empresa, pedir que o usuário cole o arquivo .pfx e digite a senha diretamente no chat de uma IA comum é uma má prática de segurança (pois grava a chave privada no histórico do provedor de LLM). Ao mesmo tempo, obrigar o desenvolvedor a sair da IDE e fazer login no painel web quebra a experiência.

Para resolver isso, o Notaas MCP v0.2.0 oferece 4 modos seguros e o próprio agente pergunta ao usuário qual opção ele prefere utilizar:

ModoTool MCPPassa pelo LLM?Exige Login Web?Quando usar
1. Referência Local Zero-Trust (stdio)org_upload_project_certificateNão (Nunca)NãoDev usando Cursor / Claude Code via npx local
2. Terminal One-Liner (read -s + curl)org_create_certificate_upload_sessionNão (Nunca)NãoDev em qualquer IDE (Remote HTTP ou Local)
3. Link Dropzone Sem Login (15 min)org_create_certificate_upload_sessionNão (Nunca)Zero LoginQuando o .pfx e a senha estão com o contador/cliente
4. Payload Direto (pfxBase64 + password)org_upload_project_certificateSim (na tool call)NãoAgentes 100% autônomos (n8n, Secret Managers)

Opção 1 — Referência Local Zero-Trust (pfxFilePath + passwordEnvVar / passwordFilePath)

Exclusiva do modo local stdio (npx @notaas/mcp). O LLM envia apenas o caminho do arquivo na sua máquina e o nome da variável de ambiente (ou caminho de um arquivo texto) que contém a senha. Quem lê os bytes do disco e a senha é o processo local Node.js do MCP, enviando via multipart/form-data direto para a API da Notaas. No servidor HTTP remoto, esses parâmetros são bloqueados por fail-closed.

// Chamada da tool org_upload_project_certificate no modo stdio:
{
  "projectId": "6f9b1c20-8a4d-4e3a-9c11-223344556677",
  "pfxFilePath": "~/certs/empresa_a1.pfx",
  "passwordEnvVar": "NOTAAS_CERT_PASS"
}

Opções 2 e 3 — Sessão Descartável One-Time (org_create_certificate_upload_session)

Gera um token de uso único (ntaas_cert_up_<64_hex>, persistido apenas como hash SHA-256 no banco, TTL de 15 minutos, limite de 5 tentativas de senha e revogação automática se o Org Token de origem for revogado). A resposta entrega simultaneamente:

  • Opção 2 (terminalCommand): comando pronto com read -r -s -p para o dev colar no terminal da IDE e digitar a senha de forma oculta.
  • Opção 3 (uploadSessionUrl): link https://platform.notaas.com.br/onboarding/cert#token=... (sem login Clerk e usando hash #token para nunca vazar em headers HTTP Referer), ideal para enviar ao contador do cliente.
// Exemplo do comando gerado na Opção 2 (Terminal da IDE):
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; }

3. Onboarding Passo a Passo por Persona (“Zero to First Invoice”)

O prompt guiado /onboard-new-company adapta o fluxo de ativação de acordo com o perfil de quem está conduzindo a integração. Escolha abaixo a sua persona para ver a sequência exata de etapas e tools:

Persona 01 · Dev Solo / Startup na IDE

Desenvolvedor em Cursor, Claude Code, Windsurf ou VS Code

Você está construindo ou integrando um sistema emissor, tem o arquivo .pfx na sua máquina local e quer ir do zero até a primeira nota fiscal autorizada em homologação sem abrir o painel web.

Transporte: Local stdio (npx -y @notaas/mcp) ou Remote HTTP (https://platform.notaas.com.br/api/mcp)Certificado A1: Opção 1 (Referência Local Zero-Trust: pfxFilePath + passwordEnvVar) ou Opção 2 (One-Liner read -s no terminal)

  1. 1. Conectar sem chave e iniciar o Device Flow

    Adicione o @notaas/mcp na sua IDE sem API Key e invoque o prompt /onboard-new-company (ou peça "quero configurar minha empresa na Notaas"). O agente chama notaas_start_account_onboarding e exibe um código curto (ex: NT-7F4K-9P2M) com o link /onboarding/mcp.

  2. 2. Autorizar em 1 clique e receber o token de bootstrap (24h)

    Ao clicar em Autorizar no navegador, o agente faz polling automático via notaas_claim_account_onboarding e recebe em memória um Organization Token temporário (ntaas_org_*, válido por 24h) cifrado ponta a ponta com AES-256-GCM.

  3. 3. Criar o Projeto Emissor e validar cobertura municipal

    O agente valida a cidade em notaas_check_city_coverage, consulta códigos LC 116 em notaas_lookup_tax_codes e cria o projeto emissor (ambiente=2 Homologação) usando org_create_project.

  4. 4. Enviar o Certificado A1 sem expor a senha ao LLM (Opção 1 ou 2)

    No modo local stdio, você define export NOTAAS_CERT_PASS="sua_senha" no seu terminal e informa ao agente apenas o caminho ~/Downloads/empresa.pfx e o nome da variável NOTAAS_CERT_PASS. O processo local do MCP lê o arquivo e a senha direto da sua máquina e faz o upload via org_upload_project_certificate sem enviar os bytes nem a senha para a OpenAI/Anthropic.

  5. 5. Gerar Project API Key, validar prontidão e emitir a 1ª nota

    O agente gera a chave definitiva (org_create_project_api_key), confere os 5 pré-requisitos em org_check_project_readiness (ready: true), revoga o token temporário (org_revoke_onboarding_token) e, após sua confirmação humana, emite a primeira NFS-e/NF-e.

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

Software House ou BPO Contábil ativando múltiplos clientes

Sua equipe técnica gerencia dezenas ou centenas de CNPJs emissores via Organization Token, mas o arquivo .pfx e a senha do Certificado Digital A1 estão em posse do dono da empresa ou do contador do cliente.

Transporte: Remote HTTP ou Local stdio autenticado com Organization Token duradouro (ntaas_org_*)Certificado A1: Opção 3 (Link Dropzone Descartável Sem Login: /onboarding/cert#token=... enviado ao contador)

  1. 1. Cadastrar o novo CNPJ sub-cliente na organização

    Com seu Organization Token (ntaas_org_*) configurado, peça ao agente para criar o projeto do cliente com org_create_project informando CNPJ, Razão Social, Inscrição Municipal, código IBGE e regime tributário.

  2. 2. Migrar a numeração fiscal do sistema anterior

    O agente consulta org_get_project_numbering e alinha o último número de RPS (NFS-e), NF-e (55) e NFC-e (65) com org_configure_project_numbering usando modo="avancar" para evitar colisão de numeração na prefeitura/SEFAZ.

  3. 3. Gerar o Link Dropzone Descartável (Sem Login) para o Contador (Opção 3)

    O agente chama org_create_certificate_upload_session. A API gera um token one-time (TTL 15 minutos) e retorna a URL https://platform.notaas.com.br/onboarding/cert#token=ntaas_cert_up_.... Você envia esse link no WhatsApp ou e-mail do contador do cliente.

  4. 4. Contador envia o .pfx sem login e o agente detecta no chat

    O contador abre o link (que exibe apenas a Razão Social e o CNPJ da empresa, sem pedir login Clerk), seleciona o .pfx e digita a senha. A plataforma valida se o titular X.509 pertence ao CNPJ do projeto, ativa o certificado no cofre S3 e destrói o link imediatamente. Nem a IA nem o seu time técnico precisam ver a senha do cliente.

  5. 5. Provisionar API Key isolada, logotipo e webhook de produção

    O agente confirma o certificado via org_get_project_certificate_status, sobe o logotipo do cliente para o DANFE/DANFSe (org_upload_project_logo), cria a Project API Key isolada (org_create_project_api_key) e registra o endpoint de webhook do ERP (webhooks_create_endpoint).

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

Pipelines 100% autônomos e Agentes em Nuvem

Você opera workflows automatizados no n8n, LangGraph ou microsserviços internos que buscam os dados e o certificado da empresa em um cofre corporativo (AWS Secrets Manager, HashiCorp Vault, 1Password) e precisam fazer o onboarding sem intervenção manual.

Transporte: Remote Streamable HTTP (https://platform.notaas.com.br/api/mcp)Certificado A1: Opção 4 (Upload Direto via Tool Call: pfxBase64 + password)

  1. 1. Conectar o MCP Client via Streamable HTTP Stateless

    Aponte o nó MCP Client do n8n ou SDK para POST https://platform.notaas.com.br/api/mcp enviando o header x-api-key com seu Organization Token (ntaas_org_*) ou Project API Key (ntaas_*).

  2. 2. Provisionar o projeto e parâmetros IBS/CBS (LC 214/2025)

    O workflow chama org_create_project configurando automaticamente código de serviço nacional (codigoTributacao), defaultCstIbscbs, defaultClassificacaoTributaria e defaultNbs.

  3. 3. Injetar o Certificado A1 diretamente do Secret Manager (Opção 4)

    O workflow lê o binário .pfx em Base64 e a senha do cofre de segredos e chama org_upload_project_certificate({ projectId, pfxBase64, password, fileName: "cert.pfx" }).

  4. 4. Executar o gate determinístico de prontidão (Fail-Closed)

    Antes de liberar o cliente para faturamento, o agente chama org_check_project_readiness. O agregador valida o conteúdo de 5 rotas (cadastro, validade do certificado, séries, chaves ativas e engine municipal ativa) e só retorna ready=true se todas passarem.

  5. 5. Emitir em lote e tratar rejeições com Auto-Triage

    Para faturamento recorrente, o agente chama nfse_emit_batch (até 100 notas por chamada) ou nfe_emit/cte_emit/mdfe_emit. Se alguma nota falhar, chama nfse_diagnose_error para receber a causa raiz estruturada.

Persona 04 · Analista Fiscal / Contabilidade & Suporte N2

Auditoria, Reforma Tributária IBS/CBS e Triagem no Claude Desktop

Você atua na operação fiscal, contabilidade ou suporte técnico N2 e quer usar o Claude Desktop ou Cursor para auditar notas, consultar regras da Reforma Tributária e diagnosticar rejeições de prefeituras/SEFAZ com garantia absoluta de que o agente não emitirá nem cancelará nada por acidente.

Transporte: Remote HTTP com header x-mcp-readonly: true ou Local stdio com NOTAAS_MCP_READ_ONLY=trueCertificado A1: Apenas leitura de vigência e alerta de vencimento via org_get_project_certificate_status

  1. 1. Ativar a trava física de Somente Leitura (Read-Only Guard)

    Configure x-mcp-readonly: true (ou NOTAAS_MCP_READ_ONLY=true). O servidor MCP oculta todas as tools de escrita (emissão, cancelamento, inutilização, upload e até o Device Flow), expondo apenas as 21 ferramentas puras de consulta e diagnóstico.

  2. 2. Consultar cobertura de 5.570 municípios e códigos LC 116

    Pergunte em linguagem natural: "Quais municípios do PR usam a engine Equiplano?" ou "Qual o código de tributação nacional e municipal para desenvolvimento de software em São Paulo?". O agente usa notaas_check_city_coverage e notaas_lookup_tax_codes.

  3. 3. Simular regras e alíquotas da Reforma Tributária (IBS/CBS 2026)

    Use notaas_explain_ibs_cbs_reference para consultar os códigos CST IBS/CBS, cClassTrib (NT 2025.002-RTC / LC 214/2025) e o demonstrativo de cálculo das alíquotas de teste de 2026 (CBS 0,9% + IBS 0,1%).

  4. 4. Diagnosticar rejeições de NFS-e, NF-e, CT-e e MDF-e

    Informe o UUID da invoice rejeitada ou invoque o prompt /diagnose-fiscal-rejection. O agente chama nfse_diagnose_error, analisa o rejection_errors da prefeitura/SEFAZ e explica exatamente qual campo corrigir.

  5. 5. Monitorar vencimento de Certificados A1 e MDF-e abertos

    Use org_check_project_readiness para auditar certificados prestes a vencer (alerta automático <= 30 dias) e mdfe_list_open_alerts para identificar manifestos não encerrados antes que bloqueiem a placa na SEFAZ.

4. Endpoints REST do Onboarding MCP & Certificados

POST/org/projects/{id}/certificate/upload-session🔑 x-api-key

Cria uma sessão efêmera one-time (TTL 15 minutos) para envio do Certificado Digital A1 via terminal (read -s + curl) ou Dropzone Web sem login (/onboarding/cert#token=...). Requer Organization Token com escopo certificates:write.

// Response 201
{
  "sessionId": "8f14e45f-ceea-467f-a8c9-...",
  "projectId": "6f9b1c20-8a4d-4e3a-9c11-...",
  "projectName": "Matriz SP",
  "razaoSocial": "ACME TECNOLOGIA LTDA",
  "cnpj": "12345678000195",
  "uploadToken": "ntaas_cert_up_64_caracteres_hexadecimais...",
  "uploadSessionUrl": "https://platform.notaas.com.br/onboarding/cert#token=ntaas_cert_up_...",
  "terminalCommand": "read -r -s -p \"Senha do Certificado A1: \" NOTAAS_PFX_PASS && echo \"\" && curl -sS -X POST ...",
  "expiresAt": "2026-10-28T10:30:00.000Z",
  "ttlMinutes": 15
}
POST/mcp/certificate-upload🔑 x-api-key

Consome atomicamente o token descartável ntaas_cert_up_* (enviado no header x-cert-upload-token), valida a senha e o CNPJ/CPF do titular X.509 ICP-Brasil contra o projeto e ativa o Certificado A1.

Headers & Body (multipart/form-data)

CampoTipoReq?Descrição
x-cert-upload-tokenheadersimToken descartável ntaas_cert_up_<64_hex> obtido em upload-session.
fileFile (.pfx/.p12)simBinário do Certificado Digital A1 (máx. 50 KB).
passwordstringsimSenha de instalação do certificado.