# DF-e — how to use (mcp.ai)

Pulls electronic fiscal documents issued AGAINST your Brazilian company (supplier invoices, events, CT-e) straight from SEFAZ, using your A1 digital certificate. Incremental NSU sync with query-rate control so your tax ID never gets blocked. Also renders the DANFE PDF from the XML, which is the printable document. Does not return invoices your own company issued: SEFAZ does not release those to the issuer.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_dfe?ms=1792030620000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `dfe_consultar_chave`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/dfe`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/dfe/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/dfe/consultar/chave` — Busca um documento pela chave de acesso de 44 dígitos.
  - body: { chave: string, account?: string }
- `POST https://api.mcp.ai/api/dfe/consultar/nsu` — Busca UM documento específico pelo NSU. Serve para recuperar um item que falhou na descompactação durante a sincronização — não para varrer a fila (isso é dfe_sincronizar).
  - body: { nsu: string, account?: string }
- `POST https://api.mcp.ai/api/dfe/gerar/danfe` — Gera o DANFE (o PDF da nota) a partir do XML. A SEFAZ distribui XML, não PDF, então esta é a representação gráfica para imprimir, anexar ou mandar pro cliente.
  - body: { xml?: string, chave?: string, nsu?: string, account?: string }
- `POST https://api.mcp.ai/api/dfe/list/accounts` — Lista os CNPJs conectados neste install (razão social, CNPJ e UF).
  - body: { account?: string }
- `POST https://api.mcp.ai/api/dfe/orcamento` — Quantas consultas ainda cabem nesta hora para este CNPJ, e se ele está bloqueado. Não consome consulta. Chame isto antes de uma carga grande — o limite da SEFAZ é por CNPJ e conta também o que outros 
  - body: { account?: string }
- `POST https://api.mcp.ai/api/dfe/sincronizar` — Puxa os documentos fiscais NOVOS emitidos contra este CNPJ (nota de fornecedor, evento, CT-e) — NFeDistribuicaoDFe.
  - body: { ult_nsu?: string, forcar_nsu?: boolean, account?: string }

## Example prompts
- "Sync new fiscal documents for my company"
- "How many queries do I have left this hour?"

## More
- Page: https://mcp.ai/dfe
- Agent spec (llms.txt): https://mcp.ai/dfe/llms.txt
- Postman collection: https://mcp.ai/dfe/postman.json