AI and MCP

MCP server: Sudrel in your AI assistant

MCP (Model Context Protocol) is the open standard that lets an AI assistant query external systems. With the Sudrel MCP server, you ask in plain language and the assistant answers with your real data:

• "How much did we receive in invoices this month?"
• "Has any supplier stopped invoicing us?"
• "Show me the invoices above R$ 5.000 from August"
• "How much of the plan allowance have I used?"

Status: the @sudrel/mcp-server package is published on npm. It runs on your computer (stdio transport), so it works in clients that run a local MCP server, such as Claude Desktop. Assistants that accept only remote servers (ChatGPT, Claude on the web) are not supported yet.

Installation

Add it to your MCP client's configuration file. In Claude Desktop, it is claude_desktop_config.json:

{
  "mcpServers": {
    "sudrel": {
      "command": "npx",
      "args": ["-y", "@sudrel/mcp-server"],
      "env": { "SUDREL_API_KEY": "sdr_live_..." }
    }
  }
}

Use a production key (sdr_live_): the test key does not read received documents. Open source, MIT license. SUDREL_API_URL (optional) changes the API address; the default is https://api.sudrel.com.br/api/v1.

What the agent can and cannot do

Tool	What it does	Reads	Writes
consultar_conta	Name, status and environment of the account tied to the key	Yes	No
consultar_consumo	Allowance used in the cycle, balance and overage	Yes	No
listar_empresas	The account's CNPJs and the state of each one	Yes	No
detalhar_empresa	Details of a CNPJ, including the certificate	Yes	No
listar_documentos	Captured NFS-e, NF-e and CT-e, filtered by period, supplier, amount, type and role	Yes	No
detalhar_documento	Full document, with service provider, service recipient (tomador), amounts and taxes	Yes	No
listar_notas_emitidas	NFS-e issued by the account (API, spreadsheet or dashboard), filtered by status	Yes	No
detalhar_nota_emitida	Full issued invoice: timeline, adjustments made by Sudrel and, if rejected, the explanation with the fix	Yes	No
listar_lotes	Issuance batches, with counts by status	Yes	No
detalhar_lote	Status of a batch and how many invoices are in each status	Yes	No
listar_itens_lote	Rows of a batch and the result of each one	Yes	No
consultar_prontidao_emissao	Whether the company can issue now, item by item, with what to do about each block	Yes	No
listar_eventos_recentes	The account's event log (invoice authorized, rejected, cancelled, document received...)	Yes	No

Amounts in listar_documentos are filtered in cents: R$ 1.500,00 is 150000. The tool's own description tells the model this.

The agent cannot: issue, validate, cancel or replace an invoice, create or change a company, upload a certificate, create a webhook, or perform any other write.

Read-only, and this is a design decision

The Sudrel MCP server does not issue invoices, does not cancel, does not create companies and does not remove anything. It only reads. The write endpoints of this API exist and work, but none of them is exposed to the agent.

The reason is the MCP threat model. An MCP server hands its tools to a model that decides on its own when to call them, based on text that may have come from anywhere, including the content of a fiscal document that the tool itself just fetched. The service description of an invoice is free text that any supplier writes. In a server that can issue invoices, this text becomes an injection surface with real tax consequences.

If you need to automate issuance, use the REST API directly, with code that goes through review and a deploy, not through a model deciding in the middle of a conversation.

Internally, every access of the MCP server goes through a single function that only does GET. Exposing writes would require changing this function on purpose, and that is the intended friction.

If you write an agent on top of the REST API

• The full specification is at https://sudrel.com.br/docs/openapi.json (and /docs/openapi.yaml). A text summary, designed for models, is at https://sudrel.com.br/docs/llms.txt.
• Read operations (every GET) are safe to repeat. Write operations (POST, PATCH, DELETE) have real effects; in POST /v1/nfse and POST /v1/lotes, always use Idempotency-Key and referencia.
• Make the agent decide by codigo and status, never by mensagem.
• Test with the sdr_test_ key: nothing it issues has tax validity.
• Follow the Integration rules.