# EmissorGratis.com — conexão de assistentes pelo MCP

Guia público do pacote MCP `0.2.0` para o ChatGPT. O endpoint é `https://emissor.gratis/mcp` e a metadata protegida está em `https://emissor.gratis/.well-known/oauth-protected-resource/mcp`.

> A versão 0.2.0 contém 16 ferramentas seguras. A lista disponível depende da instalação e da atualização da conexão; confira as ferramentas mostradas pelo ChatGPT ou o resultado de `tools/list`.

## Conexão e identidade

No ChatGPT web, adicione o endpoint como servidor MCP personalizado e escolha OAuth. O ChatGPT registra um cliente público por Dynamic Client Registration; não gere, copie ou cole client ID, segredo ou token. O registro aceita somente callbacks HTTPS oficiais do ChatGPT e usa authorization code com PKCE S256.

A pessoa entra na própria conta do EmissorGratis e escolhe explicitamente as empresas. O MCP autentica essa conta e essas empresas; ele não aceita credenciais genéricas da integração com o Engine.

Permissões:

- `emissor:read` — obrigatória para consultas, diagnósticos e links de orientação.
- `emissor:drafts` — opcional para rascunhos; também exige permissão atual `issue` na empresa.

Uma conexão antiga somente de leitura não recebe `emissor:drafts` automaticamente. Para criar rascunhos, atualize ou reconecte o app e autorize o novo escopo. Nunca informe senha, token, PIN fiscal, certificado, chave privada, XML, documento ou contato de cliente pelo chat.

## Ferramentas da versão 0.2.0

| Ferramenta | O que faz |
|---|---|
| `emissor_list_companies` | Lista as empresas selecionadas para a conexão. |
| `emissor_get_company_status` | Mostra status operacional, permissões e bloqueios sem documentos ou contatos. |
| `emissor_get_engine_capabilities` | Informa o modo do adaptador de NF-e e as capacidades realmente habilitadas. |
| `emissor_list_clients` | Procura clientes ativos por nome. |
| `emissor_list_services` | Lista serviços cadastrados. |
| `emissor_search_service_catalog` | Sugere códigos e descrições do catálogo, marcando aproximações. |
| `emissor_list_products` | Lista produtos ativos para composição de rascunhos. |
| `emissor_list_notes` | Lista NFS-e locais ou consultas previamente salvas. |
| `emissor_get_note` | Mostra o resumo seguro de uma NFS-e acessível. |
| `emissor_analyze_notes` | Calcula totais por fonte, período, situação e ambiente. |
| `emissor_list_nfe_documents` | Lista NF-e modelo 55 armazenadas em projeção resumida. |
| `emissor_get_nfe_document` | Mostra o detalhe seguro de uma NF-e armazenada. |
| `emissor_get_nfe_readiness` | Diagnostica cadastro e bloqueios locais; não autoriza emissão. |
| `emissor_start_onboarding` | Fornece links seguros para concluir o cadastro no site, sem coletar dados no chat. |
| `emissor_create_nfse_draft` | Salva um rascunho idempotente de NFS-e após confirmação. |
| `emissor_create_nfe_draft` | Salva um rascunho idempotente de NF-e modelo 55 após confirmação. |

O cliente deve ler parâmetros e disponibilidade com `tools/list`. Use apenas IDs retornados pela conexão; nunca invente identificadores nem assuma acesso a outra empresa.

## Limites

- O servidor revalida escopo, empresa, vínculo/delegação e permissão em cada chamada.
- NFS-e usa as fontes local/salva e rascunho local do aplicativo consumidor. Não existe adaptador tipado de NFS-e no Engine nesta versão.
- NF-e usa o adaptador existente do Engine. `engine_read_only` impede o rascunho de NF-e; não bloqueia o rascunho local de NFS-e.
- A conexão cria somente rascunhos. Não emite, transmite, cancela, corrige, inutiliza ou agenda notas.
- O diagnóstico e as análises usam dados locais ou resultados já salvos. Não consultam o governo e não confirmam situação fiscal ao vivo.
- Não há ferramenta de certificado, perfil tributário, XML, DANFE ou NFC-e. NFC-e existe apenas como preview offline interno, desabilitado por padrão.
- O Engine é um serviço de backend independente para NF-e e não armazena certificado nem senha por arquitetura. Transmissão, produção e previews permanecem desabilitados.
- As projeções omitem CPF/CNPJ, contatos, endereços, chaves fiscais, protocolos, XML, certificados e segredos.

## Atualizar a conexão no ChatGPT

Para recarregar as ferramentas disponíveis, use **Configurações → Plugins → EmissorGratis MCP - Produção → Atualizar ferramentas**. Conclua novamente o OAuth se quiser conceder rascunhos, abra uma conversa nova e confirme a lista oferecida antes de usar. Veja o [guia oficial para conectar ao ChatGPT](https://developers.openai.com/plugins/deploy/connect-chatgpt), a [autenticação](https://developers.openai.com/plugins/build/auth) e o [servidor MCP](https://developers.openai.com/plugins/build/mcp-server).

Claude e Gemini ainda não foram configurados nem validados para esta instalação.

## Exemplo de pedido

> Use o EmissorGratis somente nas empresas autorizadas. Mostre o status da empresa, procure produtos e liste as NF-e armazenadas. Se eu pedir um rascunho de NFS-e ou NF-e, apresente os dados seguros e peça minha confirmação antes de salvar. Nunca emita ou transmita uma nota.

Para revogar o acesso, remova a conexão no ChatGPT e também em Configurações → Conexões com assistentes de IA no EmissorGratis.