Agentes de IA (MCP)

Conecte Claude Code, Cursor e outros agentes à Corvo por OAuth.

O servidor MCP da Corvo deixa agentes de IA (Claude Code, Cursor e outros clientes MCP) emitirem e consultarem NFS-e em nome de um usuário, sem você escrever integração. O agente se conecta por OAuth: abre o navegador, você entra na Corvo, escolhe o workspace e aprova. Nenhuma chave de API é copiada.

Conectar um agente

Use a URL do servidor abaixo. Ela também aparece no painel, em Agentes de IA, com os comandos prontos para copiar.

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"
    }
  }
}

Adicione o servidor no agente com a URL https://api.corvo.tech/mcp.
O agente abre o navegador na tela de aprovação da Corvo. Se você não estiver logado, entre primeiro; depois volta para a aprovação.
Escolha o workspace e clique em Permitir (ou Negar).
Volte ao agente. Ele já recebe as ferramentas da Corvo.

Ao aprovar, você escolhe o ambiente da conexão: test (notas sem valor fiscal) ou live (notas reais, com consumo de créditos). Cada conexão fica em um ambiente; para trocar, reconecte o agente. Comece pelo teste.

Permissões

Escopo	O que permite	Papéis que podem conceder
`nfse:read`	Consultar, listar e baixar o PDF de notas	admin, developer, billing
`nfse:write`	Emitir notas	admin, developer

Um membro só consegue aprovar escopos que o próprio papel no workspace permite. Um workspace em que o seu papel não cobre o pedido aparece desabilitado na tela de aprovação.

Ferramentas

Ferramenta	Escopo	Entrada principal	Saída
`nfse_issue`	`nfse:write`	`company_tax_id` (CNPJ) ou `company_id`, `amount` (ou `services [{description, quantity, unit_price}]`), `customer? {tax_id, name?, email?}` (`tax_id` obrigatório quando há tomador), `description?`, `discount?`, `deduction?` (dedução da base do ISS declarada pelo emitente), `competence_date?` (padrão: hoje), `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 a 50 itens, cada um com os mesmos campos de `nfse_issue`, incluindo `company_tax_id` ou `company_id` e `idempotency_key`)	`{ total, accepted, rejected, results [{ index, status, replayed?, invoice_id?, access_key?, invoice_status?, error? }] }`; itens inválidos são rejeitados no lugar e os válidos são salvos juntos
`company_get`	`nfse:read`	`tax_id` (CNPJ)	`{ company }` ou `{ company: null }`
`company_create`	`nfse:write`	`legal_name`, `tax_id`, `tax_regime`, `municipality_code`, `simples_rate` (obrigatório no Simples Nacional), `simples_iss_rate?` e dados fiscais opcionais	`{ id, legal_name, tax_id, status }`; certificado continua somente pela API
`nfse_calculate`	`nfse:read`	`company_tax_id` ou `company_id`, `amount`, mais `discount`, `deduction` e dados fiscais opcionais	Resultado da apuração sem emitir, reservar crédito ou criar DPS
`billing_usage`	`nfse:read`	Sem parâmetros	`QuotaStatus` com `canEmit`, franquia e uso
`nfse_cancel`	`nfse:write`	`invoice_id`, `reason` (`issue_error`, `service_not_provided` ou `other`), `description?` (15–255 caracteres, obrigatória para NFS-e autorizada ou em emissão)	`{ invoice_id, status, cancelled_at }` (`cancelled`, `cancelling` ou `processing` com o pedido registrado)
`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` (nota autorizada)	`{ access_key, pdf_base64 }`
`nfse_get_download_url`	`nfse:read`	`access_key`, `format` (`pdf` ou `xml`; nota autorizada)	`{ download_url, expires_at, file_name, mime_type }` (URL assinada, válida por 1 hora)

A chamada mais simples é company_tax_id mais amount: o tomador é opcional (omita para uma nota sem tomador; se enviar, tax_id é obrigatório), a data de competência é hoje por padrão, o código de serviço vem da empresa ou, sem ele, 100901 (LC 116 item 10.09), e a descrição vem do nome do código de serviço. Use company_get para consultar um CNPJ específico e billing_usage antes de emitir. Certificados A1 não são expostos no MCP e devem ser enviados somente pela API. Falhas das ferramentas voltam como resultado com isError: true e a mensagem em texto, para o agente ler e corrigir.

Ver uso e revogar

No painel, abra Agentes de IA → Aplicativos conectados: você vê cada agente, o workspace, as permissões, o último uso e quantas chamadas e notas emitidas ele fez.
Clique em Revogar para cortar o acesso na hora. O agente precisa ser aprovado de novo para voltar.
Administradores do workspace veem e podem revogar as conexões de todos os membros; os demais veem só as próprias.
Reconectar o mesmo agente reaproveita a conexão e revoga a sessão anterior.