Automação

Como Conectar Agentes de IA (n8n, LangGraph e Vercel AI SDK) à Emissão de Notas Fiscais via MCP

Guia de arquitetura para orquestrar agentes autônomos no n8n, LangGraph e Vercel AI SDK emitindo NF-e, NFS-e e NFC-e via Streamable HTTP MCP (@notaas/mcp) com segurança, idempotência e modo somente leitura.

Fábio Magalhães CostaAtualizado em 22/11/2026
Orquestração de agentes autônomos em n8n, LangGraph e Vercel AI SDK conectados ao MCP Server fiscal

Orquestração de agentes autônomos em n8n, LangGraph e Vercel AI SDK conectados ao MCP Server fiscal

Enquanto no nosso guia principal sobre MCP Server para Nota Fiscal no Claude Code e Cursor focamos no uso dentro da IDE durante o desenvolvimento, em produção a demanda que mais cresce é outra: colocar agentes autônomos rodando em backend (n8n, LangGraph, CrewAI ou Vercel AI SDK) para faturar pedidos, consultar status na SEFAZ e responder clientes no WhatsApp/Slack sem intervenção humana.

O problema de ligar um LLM direto em uma API fiscal sem camada de protocolo é clássico: o modelo inventa campos de payload, esquece o externalId (duplicando nota em retry) ou pede a senha do certificado A1 no prompt. É exatamente isso que o endpoint Streamable HTTP MCP da Notaas (https://platform.notaas.com.br/api/mcp) resolve.


Arquitetura segura: Agente Autônomo → Streamable HTTP MCP → SEFAZ / SNNFSE

Em vez de escrever dezenas de function calls manuais no seu orquestrador, você conecta o cliente MCP diretamente ao servidor remoto da Notaas, que expõe 46 tools tipadas (sendo 21 read-only):

⚡ Fluxo de Execução Segura para Agentes em Produção:

  • 1. Gatilho de Negócio: Um webhook (Stripe, Asaas, CRM ou WhatsApp) aciona seu agente no n8n, LangGraph ou Vercel AI SDK.
  • 2. Descoberta Tipada (MCP): O agente carrega apenas os schemas exatos das tools necessárias (ex.: emit_nfse, get_invoice_status, check_city_coverage).
  • 3. Isolamento do Certificado A1: O .pfx e a senha ficam no cofre criptografado da Notaas — o LLM nunca vê o certificado nem a senha.
  • 4. Guardrail por Ambiente e Header: Para agentes de atendimento/consulta, envie o header x-mcp-readonly: true, bloqueando qualquer escrita ou emissão no nível do servidor.

Exemplo 1: Conectando no Vercel AI SDK (TypeScript)

Com o transporte Streamable HTTP nativo do MCP, seu backend em Next.js ou Node.js se conecta à Notaas sem precisar subir nenhum processo local via stdio:

import { experimental_createMCPClient as createMCPClient } from "ai";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

export async function createNotaasMcpClient(options?: { readOnly?: boolean }) {
  const headers: Record<string, string> = {
    "X-API-Key": process.env.NOTAAS_API_KEY!,
  };

  if (options?.readOnly) {
    headers["x-mcp-readonly"] = "true";
  }

  const transport = new StreamableHTTPClientTransport(
    new URL("https://platform.notaas.com.br/api/mcp"),
    { requestInit: { headers } }
  );

  return createMCPClient({ transport });
}

Exemplo 2: Configuração no n8n (MCP Client Tool Node)

No n8n, basta adicionar o nó MCP Client Tool ligado ao seu AI Agent:

  1. Transport: HTTP Streamable
  2. Endpoint URL: https://platform.notaas.com.br/api/mcp
  3. Authentication / Headers: X-API-Key: ntaas_live_... (e x-mcp-readonly: true para agentes de suporte/consulta).
  4. Tool Selection: Libere apenas o subconjunto necessário para aquele fluxo (ex.: consulta de cobertura municipal + emissão de NFS-e + consulta de status).

3 boas práticas obrigatórias antes de colocar agentes fiscais em produção

  1. Separe agente leitor de agente emissor: Um bot de atendimento no WhatsApp que só consulta se a nota foi autorizada e envia o PDF do DANFSe deve sempre usar x-mcp-readonly: true. Assim, mesmo diante de prompt injection, o agente fica fisicamente impedido de emitir ou cancelar qualquer documento.
  2. Exija externalId determinístico no prompt de sistema: Instrua o agente a sempre passar o ID do pedido/fatura (ex.: pedido_88412) como externalId. Como a Notaas aplica lock transacional de idempotência, mesmo que o agente tente chamar a tool duas vezes, apenas uma nota fiscal é gerada.
  3. Teste primeiro no Sandbox Multi-CNPJ: No Plano Free da Notaas, você pode conectar seus agentes em até 5 CNPJs gratuitos em homologação (além de 20 notas/mês em produção real para 1 CNPJ) antes de ativar clientes reais.

Conecte seu primeiro agente agora

Notaas — Infraestrutura Fiscal Multi-Tenant para SaaS, ERPs e BPOs

Escale a emissão de NFS-e, NF-e, NFC-e, CT-e e MDF-e para dezenas de CNPJs

Integre a API de Nota Fiscal da Notaas no seu software: provisione clientes via Org API Multi-CNPJ, isole certificados A1 em nuvem, receba webhooks assinados com HMAC e gere DANFSe v2.0 local. Sandbox ilimitado e planos sob medida para operações em escala.

Artigos Relacionados em Automação

Guias Pilares de Integração Fiscal