AI agents (MCP)

Connect Claude Code, Cursor and other agents to Corvo with OAuth.

The Corvo MCP server lets AI agents (Claude Code, Cursor and other MCP clients) issue and query NFS-e on behalf of a user, without you writing an integration. The agent connects with OAuth: it opens the browser, you sign in to Corvo, pick the workspace and approve. No API key is copied.

Connect an agent

Use the server URL below. It also appears in the dashboard under AI agents, with ready-to-copy commands.

Claude Code

claude mcp add --transport http corvo https://api.corvo.tech/mcp

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "corvo": {
      "url": "https://api.corvo.tech/mcp"
    }
  }
}

Add the server to the agent with the URL https://api.corvo.tech/mcp.
The agent opens the browser on the Corvo approval screen. If you are not signed in, sign in first; you then return to the approval.
Pick the workspace and click Allow (or Deny).
Go back to the agent. It now has the Corvo tools.

When you approve, you choose the connection environment: test (invoices with no fiscal value) or live (real invoices, using credits). Each connection stays in one environment; to switch, reconnect the agent. Start with test.

Permissions

Scope	What it allows	Roles that can grant it
`nfse:read`	Query, list and download the PDF of invoices	admin, developer, billing
`nfse:write`	Issue invoices	admin, developer

A member can only approve scopes that their own role in the workspace allows. A workspace where your role does not cover the request appears disabled on the approval screen.

Tools

Tool	Scope	Main input	Output
`nfse_issue`	`nfse:write`	`company_tax_id` (CNPJ) or `company_id`, `amount` (or `services [{description, quantity, unit_price}]`), `customer? {tax_id, name?, email?}` (`tax_id` required when a customer is sent), `description?`, `discount?`, `deduction?` (ISS base deduction declared by the issuer), `competence_date?` (default: today), `emission_type?` (`IMMEDIATE`/`SCHEDULE`), `send_email?`, `service_code?`, `external_id?`, `idempotency_key?`	`{ invoice_id, access_key, status }`
`company_list`	`nfse:read`	`tax_id?` (CNPJ), `limit?`, `cursor?`	`{ companies [{ id, legal_name, tax_id, status, tax_regime, setup_gaps, ready_to_issue }], next_cursor }`
`nfse_issue_batch`	`nfse:write`	`invoices` (1 to 50 items, each with the same fields as `nfse_issue`, including `company_tax_id` or `company_id` and `idempotency_key`)	`{ total, accepted, rejected, results [{ index, status, replayed?, invoice_id?, access_key?, invoice_status?, error? }] }`; invalid items are rejected in place and the valid ones are saved together
`company_get`	`nfse:read`	`tax_id` (CNPJ)	`{ company }` or `{ company: null }`
`company_create`	`nfse:write`	`legal_name`, `tax_id`, `tax_regime`, `municipality_code`, `simples_rate` (required for Simples Nacional), `simples_iss_rate?` and optional fiscal data	`{ id, legal_name, tax_id, status }`; certificates remain API-only
`nfse_calculate`	`nfse:read`	`company_tax_id` or `company_id`, `amount`, optional `discount`, `deduction` and fiscal data	Calculation result; no issue, credit reservation or DPS
`billing_usage`	`nfse:read`	No parameters	`QuotaStatus` with `canEmit`, allowance and usage
`nfse_cancel`	`nfse:write`	`invoice_id`, `reason` (`issue_error`, `service_not_provided` or `other`), `description?` (15–255 characters, required for an authorized NFS-e or one being issued)	`{ invoice_id, status, cancelled_at }` (`cancelled`, `cancelling`, or `processing` with the request recorded)
`nfse_query`	`nfse:read`	`access_key`	`{ access_key, status, nfse_number, authorized_at, last_error }`
`nfse_list`	`nfse:read`	`status?`, `limit?`, `cursor?`	`{ invoices, next_cursor }`
`nfse_download_pdf`	`nfse:read`	`access_key` (authorized invoice)	`{ access_key, pdf_base64 }`
`nfse_get_download_url`	`nfse:read`	`access_key`, `format` (`pdf` or `xml`; authorized invoice)	`{ download_url, expires_at, file_name, mime_type }` (signed URL, valid for one hour)

The simplest call is company_tax_id plus amount: the customer is optional (omit it for an invoice without tomador; if you send one, tax_id is required), the competence date defaults to today, the service code comes from the company or falls back to 100901 (LC 116 item 10.09) and the description from the service code. Use company_get for one CNPJ and billing_usage before issuing. A1 certificates are not exposed over MCP and must be uploaded through the API only. Tool failures come back as a result with isError: true and the message as text, so the agent can read and fix them.

See usage and revoke

In the dashboard, open AI agents → Connected apps: you see each agent, the workspace, the permissions, the last use and how many calls and invoices it made.
Click Revoke to cut access immediately. The agent has to be approved again to come back.
Workspace admins see and can revoke every member's connections; other members see only their own.
Reconnecting the same agent reuses the connection and revokes the previous session.