Servidor MCP - Captura SEFAZ

O servidor fala JSON-RPC 2.0 sobre HTTP (transporte Streamable HTTP): o cliente faz um POST para o endpoint MCP com o corpo JSON-RPC. Os metodos de protocolo suportados sao initialize, tools/list, tools/call e ping.

Qualquer cliente MCP que suporte servidor HTTP remoto com header de autenticacao consegue se conectar. O token vai no header Authorization.

Copiarclaude mcp add --transport http estoque-nfe "https://estoquenfe.optago.app.br/api/v1/mcp" \
  --header "Authorization: Bearer <token>"

Copiar{
  "mcpServers": {
    "estoque-nfe": {
      "type":    "http",
      "url":     "https://estoquenfe.optago.app.br/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

Toda requisicao ao endpoint MCP exige o header Authorization: Bearer <token>. Sem token valido, o servidor responde 401 antes de qualquer metodo. O token precisa ter acesso ativo ao estoque-nfe; o escopo por empresa e aplicado em cada chamada de ferramenta pelo CNPJ informado.

Lista os documentos fiscais capturados da SEFAZ para uma empresa, com filtros opcionais e paginacao.

Retorna o XML completo autorizado (procNFe) de uma NF-e pela chave de acesso. O conteudo volta como texto no resultado da ferramenta.

Gera o DANFE em PDF de uma NF-e pela chave de acesso. Retorna um recurso embutido (resource) com mimeType: application/pdf e o conteudo em base64.

Registra a manifestacao do destinatario. Requer papel de gestor na empresa.

Para depurar sem um cliente MCP, da pra chamar o endpoint direto com curl.

Copiarcurl -X POST "https://estoquenfe.optago.app.br/api/v1/mcp" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Copiarcurl -X POST "https://estoquenfe.optago.app.br/api/v1/mcp" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"listar_documentos","arguments":{"cnpj":"12345678000190","per_page":10}}}'

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      { "type": "text", "text": "{ ...documentos e pager em JSON... }" }
    ],
    "isError": false
  }
}