Servidor MCP

O MCP Server da Brasil NFe expõe a API fiscal como ferramentas (tools), recursos (resources) e prompts via Model Context Protocol. Qualquer cliente MCP — Claude Desktop, ChatGPT Apps, Cursor, Windsurf, Copilot, Zed, JetBrains AI, Continue.dev — passa a emitir NF-e, NFC-e, NFS-e, CT-e, MDF-e e DC-e por linguagem natural, com a mesma autenticação e os mesmos contratos da REST API.

Esta página é a referência técnica para desenvolvedores. Para a visão geral e configuração visual, veja /ai/.

Endpoint e discovery

Recurso	URL
MCP (JSON-RPC)	`POST https://api.brasilnfe.com.br/services/Mcp`
MCP (SSE stream)	`GET https://api.brasilnfe.com.br/services/Mcp`
Encerrar sessão	`DELETE https://api.brasilnfe.com.br/services/Mcp`
Manifesto MCP	`GET https://api.brasilnfe.com.br/.well-known/mcp`
Info / status	`GET https://api.brasilnfe.com.br/services/Mcp/info`

Transport: Streamable HTTP. Spec: 2025-06-18 (com fallback negociado para 2025-03-26 e 2024-11-05).

Autenticação

O servidor usa o mesmo token de empresa da API REST. Envie em um destes dois cabeçalhos:

Code
 
Authorization: Bearer SEU_TOKEN
# ou
Token: SEU_TOKEN

O token identifica a empresa: o servidor resolve automaticamente CNPJ, regime tributário, certificado digital e estado de contingência em cada chamada. Cada token tem rate-limit isolado (default 60 req/min).

Cabeçalhos de sessão e protocolo

Cabeçalho	Direção	Uso
`Mcp-Session-Id`	resp / req	Devolvido no `initialize`, deve ser reenviado em chamadas subsequentes
`MCP-Protocol-Version`	resp	Versão negociada da spec
`X-Request-Id`	resp	ID único de cada chamada (auditoria)
`X-RateLimit-Limit` / `Remaining` / `Reset`	resp	Telemetria do rate-limit
`Retry-After`	resp (429)	Segundos para retry quando excede rate-limit

Configuração nos clientes MCP

Edite claude_desktop_config.json (no macOS: ~/Library/Application Support/Claude/, no Windows: %APPDATA%\Claude\).


Code
 
{
  "mcpServers": {
    "brasilnfe": {
      "url": "https://api.brasilnfe.com.br/services/Mcp",
      "headers": {
        "Authorization": "Bearer SEU_TOKEN"
      }
    }
  }
}

Reinicie o Claude Desktop. As 24 tools aparecem no menu de ferramentas.

Catálogo de tools

São 24 tools organizadas em 7 categorias. Cada uma tem inputSchema/outputSchema JSON (gerados a partir dos contratos C# da API) e anotações que orientam o cliente MCP.

Anotações de comportamento

Hint	Significado
`readOnlyHint`	A tool não muda estado. Cliente pode chamar sem confirmação.
`destructiveHint`	Operação irreversível (cancelamento, inutilização). Cliente deve pedir confirmação obrigatória.
`idempotentHint`	Múltiplas chamadas com mesmo input produzem mesmo resultado.
`openWorldHint`	Resultado depende de sistemas externos (SEFAZ).

NF-e / NFC-e

Tool	Descrição
`nfe_emitir`	Emite NF-e (modelo 55) ou NFC-e (modelo 65).
`nfe_emitir_lote`	Emite até 50 notas em lote único (long-running, com progress).
`nfe_emitir_complementar`	NF-e complementar (finalidade=2) referenciando nota original.
`nfe_previsualizar`	Pré-visualização do DANFE em PDF, sem enviar à SEFAZ.

NFS-e

Tool	Descrição
`nfse_emitir`	Emite NFS-e via Portal Nacional ou prefeitura específica.
`nfse_consultar`	Consulta status e dados de NFS-e por número, série e ambiente.

CT-e · MDF-e · DC-e · NF-EnerCom

Tool	Descrição
`cte_emitir`	Emite Conhecimento de Transporte Eletrônico.
`cte_desacordo`	Registra desacordo do tomador (evento tipo 4). Prazo: 45 dias.
`mdfe_emitir`	Emite MDF-e agrupando vários CT-e/NF-e.
`mdfe_encerrar`	Encerra MDF-e autorizado (evento tipo 3).
`dce_emitir`	Emite DC-e (Declaração de Conteúdo) para PF/MEI.
`nfenercom_gerar_arquivo`	Gera arquivo NF-EnerCom (pré-requisito).
`nfenercom_emitir`	Emite NF-EnerCom (Energia Comercializada).

Eventos fiscais

Tool	Descrição
`evento_cancelar`	Cancela NF-e, NFC-e, NFS-e, CT-e, MDF-e ou DC-e. Destructive.
`evento_carta_correcao`	CC-e em NF-e ou CT-e (evento tipo 2). Limite: 20 por nota.
`evento_manifestar`	Manifestação do destinatário (ciência, confirmação, desconhecimento, não realizada).
`evento_inutilizar`	Inutiliza faixa de numeração não utilizada. Destructive, irreversível.

Consultas SEFAZ

Tool	Descrição
`sefaz_status`	Status do serviço de autorização da SEFAZ por UF e ambiente.
`cadastro_consultar`	Consulta dados cadastrais por CPF/CNPJ/IE e UF.
`nota_listar`	Lista NF-e/NFC-e/NFS-e emitidas ou recebidas em um intervalo.
`imposto_calcular`	Simula ICMS, PIS, COFINS, IPI, ST sem emitir nota.

Arquivos · Downloads

Tool	Descrição
`arquivo_baixar`	XML ou PDF/DANFE de uma nota por chave. Retorna em base64.
`arquivo_baixar_evento`	Arquivo de evento por chave + sequencial.
`arquivo_baixar_periodo`	Exporta XMLs/PDFs de um período em ZIP base64 (long-running).

Auxiliares

Tool	Descrição
`fci_gerar`	Gera FCI (Ficha de Conteúdo de Importação).
`health`	Health-check da API.

Resources

Resources são leituras estáveis identificadas por URI no esquema brasilnfe://. O agente lê resources antes de tomar decisões (ex: confirmar emitente antes de emitir).

URI	Conteúdo
`brasilnfe://empresa/atual`	Snapshot da empresa do token (razão social, CNPJ, IE, regime, contingência).
`brasilnfe://nfe/{chave}/xml`	XML autorizado de uma NF-e/NFC-e emitida.
`brasilnfe://nfe/{chave}/danfe`	DANFE em PDF.
`brasilnfe://nfe-entrada/{chave}/xml`	XML de NF-e recebida (entrada).
`brasilnfe://nfe-entrada/{chave}/danfe`	DANFE de NF-e recebida.
`brasilnfe://evento/{chave}/{tipoArquivo}`	XML (1) ou PDF (2) de evento (CC-e, cancelamento, manifestação).

Os resources com placeholders ({chave}, {tipoArquivo}) são listados em resources/templates/list.

Prompts prontos

São 5 fluxos guiados (templates de mensagem) que o cliente MCP exibe como ações de um clique. Cada um valida regras fiscais antes de chamar a tool correspondente.

Prompt	Argumentos	O que faz
`emitir_nfe_simples`	`cnpjCliente`, `descricaoProduto`, `valor*`, `ambiente`, `naturezaOperacao`	Guia o agente a emitir NF-e modelo 55, lendo `empresa/atual` e validando SEFAZ antes.
`cancelar_nota`	`chave`, `numeroNFSe`, `justificativa*`	Valida prazo legal e tamanho da justificativa antes de chamar `evento_cancelar`.
`diagnostico_emissao`	`uf`	Verifica empresa, SEFAZ e contingência. Conclui com PRONTO ou ATENÇÃO.
`relatorio_periodo`	`dataInicio`, `dataFim`, `modeloDocumento`	Lista notas, agrupa por status, identifica top 5 destinatários.
`carta_correcao`	`chave`, `correcao`	Valida o que pode ser corrigido (não permite valores, datas, partes, série).

Exemplo end-to-end

1. Initialize

Code
 
curl -X POST "https://api.brasilnfe.com.br/services/Mcp" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": { "name": "meu-app", "version": "1.0" }
    }
  }'

A resposta inclui serverInfo, capabilities e instructions. Anote o Mcp-Session-Id dos response headers — ele é obrigatório nas próximas chamadas.

2. Listar tools

Code
 
curl -X POST "https://api.brasilnfe.com.br/services/Mcp" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Mcp-Session-Id: SESSAO_DEVOLVIDA" \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }'

3. Chamar tool

Code
 
curl -X POST "https://api.brasilnfe.com.br/services/Mcp" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Mcp-Session-Id: SESSAO_DEVOLVIDA" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "sefaz_status",
      "arguments": { "Uf": "SP", "TipoAmbiente": 2 }
    }
  }'

4. Ler resource

Code
 
curl -X POST "https://api.brasilnfe.com.br/services/Mcp" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Mcp-Session-Id: SESSAO_DEVOLVIDA" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "resources/read",
    "params": { "uri": "brasilnfe://empresa/atual" }
  }'

Códigos de erro JSON-RPC

Código	Significado
`-32700`	Parse error (JSON inválido)
`-32600`	Invalid Request (formato JSON-RPC inválido)
`-32601`	Method not found
`-32602`	Invalid params (parâmetro obrigatório ausente, URI mal formada, etc.)
`-32603`	Internal error
`-32000`	Auth required (token ausente ou inválido)
`-32001`	Rate limited (com `data.retryAfterSeconds`)

Operações longas e progress

Tools marcadas como LongRunning (ex: nfe_emitir_lote, arquivo_baixar_periodo) emitem notificações notifications/progress a cada 5 segundos via SSE quando o cliente envia _meta.progressToken no tools/call. Para receber essas notificações, mantenha aberto um GET /services/Mcp com o mesmo Mcp-Session-Id.

Auditoria

Cada tools/call, resources/read e prompts/get registra: timestamp UTC, request id, sessão, empresa, método, tool/resource/prompt, latência em ms, sucesso/erro. Os logs ficam acessíveis pelo painel da Brasil NFe.

Boas práticas para produção

Sempre leia brasilnfe://empresa/atual antes da primeira emissão da sessão para confirmar emitente e regime.
Use o prompt diagnostico_emissao antes de operações em massa — ele valida SEFAZ e contingência.
Default para tipoAmbiente: 2 (homologação) em qualquer integração nova; promova para produção (1) deliberadamente.
Ajuste o rate-limit no app.config (Mcp:RateLimit:RequestsPerMinute) conforme volume.
Mantenha o log de auditoria do MCP integrado ao seu SIEM — todo tools/call é rastreável por requestId + sessionId.
Encerre sessões ociosas com DELETE /services/Mcp + Mcp-Session-Id para liberar recursos.

Last modified on April 28, 2026

Arquivos