REFERÊNCIA

Servidor MCP

A Stackin expõe a API como ferramentas MCP: um agente conectado emite, consulta, cancela e explica rejeições conversando, sem escrever requisição. Doze ferramentas, oito prompts, e o escopo verificado a cada chamada.

Conversa, não requisição
O agente chama a ferramenta, monta o payload e lê o retorno. Quem usa descreve o que quer emitir.
Escopo verificado a cada chamada
Cada ferramenta declara o escopo que exige, e o token é conferido na hora — não no cadastro do plugin.
Doze ferramentas, oito prompts
Emitir, consultar, cancelar, corrigir, manifestar e explicar rejeição — a mesma superfície da API.

Começar pelo ChatGPT

Cadastrar o plugin leva um endereço e um login. O resto é conversa.

1. Ver o fluxo inteiroGravação do cadastro à emissão 2. Conectar o clienteOAuth 2.1 ou API key 3. Conferir os escoposO que cada permissão libera

Endpoint

https://mcp.stackin.io/mcp

O mesmo endereço para os dois modos de autenticação.

Plugin do ChatGPT

No ChatGPT, a Stackin entra como um plugin MCP: você cadastra o endereço https://mcp.stackin.io/mcp, autentica por OAuth e passa a emitir, consultar, explicar rejeição e cancelar conversando. A gravação abaixo percorre o caminho inteiro, do cadastro ao cancelamento, em homologação.

Gravação de tela, sem áudio, em ambiente de homologação — as notas emitidas ali não têm valor fiscal.

Conectar

O servidor fala streamable-http e responde num endereço fixo. Um cliente MCP se conecta por OAuth 2.1 com PKCE — é o caminho de quem usa o plugin no ChatGPT — ou por uma API key da empresa, que é o mais direto num cliente local.

Com uma API key

A key vai no header Authorization, como na API. Sobre HTTP a credencial vem sempre da requisição — o servidor atende muitas empresas e nunca cai para uma chave do ambiente.

.mcp.json

{
  "mcpServers": {
    "stackin": {
      "type": "http",
      "url": "https://mcp.stackin.io/mcp",
      "headers": {
        "Authorization": "Bearer ${STACKIN_API_KEY}"
      }
    }
  }
}

Escopos

Um token OAuth carrega os escopos que o titular aprovou, e a API compara o escopo com a operação a cada chamada. Recusar acontece na API, não no agente.

invoice:read: Consultar, listar, baixar PDF e ler o histórico de envio.
invoice:issue: Emitir e reemitir documento.
invoice:cancel: Cancelar documento e inutilizar faixa de numeração.
invoice:write: Carta de correção e manifestação sobre nota recebida.

oauth-protected-resource

curl https://mcp.stackin.io/.well-known/oauth-protected-resource

{
  "resource": "https://mcp.stackin.io",
  "authorization_servers": ["https://api.stackin.io"],
  "scopes_supported": [
    "invoice:read",
    "invoice:issue",
    "invoice:write",
    "invoice:cancel"
  ]
}

Ferramentas

Doze ferramentas. Sete alteram um documento e declaram destructiveHint; as outras cinco são leitura. validate_invoice_payload não chama a API e por isso não exige escopo.

Ferramenta	Escopo	Obrigatórios	Efeito
`issue_invoice`	`invoice:issue`	`document_typeclient_nametax_iditems`	Altera documento
`reissue_invoice`	`invoice:issue`	`invoice_id`	Altera documento
`cancel_invoice`	`invoice:cancel`	`access_keydocument_typereason`	Altera documento
`correct_invoice`	`invoice:write`	`access_keycorrection`	Altera documento
`invalidate_numbering`	`invoice:cancel`	`seriesnumber_startnumber_endreason`	Altera documento
`manifest_received_invoice`	`invoice:write`	`access_keymanifestation`	Altera documento
`consult_invoice`	`invoice:read`	`access_keydocument_type`	Leitura
`list_invoices`	`invoice:read`	—	Leitura
`get_invoice_pdf`	`invoice:read`	`access_keydocument_type`	Leitura
`get_invoice_submissions`	`invoice:read`	`invoice_id`	Leitura
`list_received_invoices`	`invoice:read`	—	Leitura
`validate_invoice_payload`	`noauth`	`document_typeitems`	Leitura

Prompts

Oito prompts guiam o modelo nas tarefas mais comuns — o que perguntar antes de emitir, o que nunca inventar, e quando cancelar não é a resposta.

issue_nfseEmitir uma nota de serviço.

issue_nfeEmitir uma nota de mercadoria.

recent_invoicesMostrar os últimos documentos da empresa.

diagnose_rejectionExplicar por que um documento foi rejeitado e o que corrigir.

inspect_invoiceMostrar o estado atual de um documento.

correct_nfeCarta de correção para texto, não para valores.

manifest_receivedDeclarar a posição da empresa sobre a NF-e de um fornecedor.

cancel_invoice_promptCancelar um documento autorizado, com confirmação.

Permissões do conector

As ferramentas que alteram documento declaram readOnlyHint: false e openWorldHint: true, porque transmitem ao fisco. É essa combinação que o modo padrão bloqueia.

Além disso, toda operação irreversível pede confirmação: as skills mandam ler os dados de volta antes de emitir, cancelar, inutilizar numeração ou manifestar-se — e emitir e cancelar aceitam idempotency_key, então repetir a chamada não gera um segundo documento.

No ChatGPT, escolha Perguntar sempre nas Permissões do conector antes de emitir. No padrão, Permitir ações de baixo risco, toda escrita é negada em silêncio — a chamada não sai da plataforma e nada chega aqui.