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.

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.

Claude Code

O plugin traz as sete skills e aponta para o endpoint. A autenticação é por OAuth 2.1 com PKCE, sem chave nenhuma: o cliente se registra sozinho e você entra pelo navegador.

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

01Instalar o pluginO repositório é o próprio marketplace: claude plugin marketplace add stackin-io/stackin-mcp-plugin e depois claude plugin install stackin@stackin.
02EntrarRode /mcp na sessão. A primeira chamada devolve 401, o cliente se registra sozinho e abre a tela de consentimento no navegador. Autorize e o token fica guardado.
03UsarPeça em português — “emita uma NFS-e de consultoria”, “por que a última nota foi rejeitada?” — ou chame uma skill direto pelo nome.

As skills que vêm junto

Uma skill existe onde a ordem das operações, ou uma regra fiscal, carrega algo que a descrição de uma ferramenta não carrega sozinha.

/stackin:issue-invoiceQual documento a situação pede, e validar antes de emitir.

/stackin:consult-invoiceAchar um documento, e qual identificador cada operação aceita.

/stackin:cancel-invoiceConfirmar antes de um ato irreversível, e quando a carta de correção é a ferramenta certa.

/stackin:diagnose-invoiceLer o código de rejeição do fisco, e escolher entre reemitir e corrigir.

/stackin:correct-invoiceRegistrar uma CC-e contra uma NF-e autorizada, e o que ela não pode mudar.

/stackin:invalidate-numberingDeclarar uma faixa de numeração reservada e nunca usada.

/stackin:received-invoicesLer o que emitiram contra a empresa, e responder.

Conectar

O servidor fala streamable-http e responde num endereço fixo. Um cliente MCP entra por OAuth 2.1 com PKCE — sem chave nenhuma, é assim que o plugin no ChatGPT e no Claude Code se conectam — ou por uma API key da empresa, útil quando não há navegador à mão.

Entrando pelo navegador

No Claude Code, instale o plugin e rode /mcp na sessão: a primeira chamada devolve 401 com WWW-Authenticate, o cliente segue a pista até o documento de recurso protegido, se registra sozinho e abre a tela de consentimento. Não há client ID para colar, e a callback é o localhost que o próprio cliente escolhe na hora.

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.

Claude Code

claude plugin marketplace add stackin-io/stackin-mcp-plugin
claude plugin install stackin@stackin

.mcp.json

{
  "mcpServers": {
    "stackin": {
      "type": "http",
      "url": "https://mcp.stackin.io/mcp"
    }
  }
}

.mcp.json — API key

{
  "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.

Servidor MCP

Conversa, não requisição

Escopo verificado a cada chamada

Doze ferramentas, oito prompts

Começar pelo ChatGPT

ChatGPT

Claude Code

As skills que vêm junto

Conectar

Entrando pelo navegador

Com uma API key

Escopos

Ferramentas

Prompts

Permissões do conector