Solução de problemas

Como fazer a triagem de problemas

Quando algo der errado, como falhas na renderização de componentes, prompts não reconhecidos na descoberta ou ciclos de autenticação, comece identificando a camada responsável: servidor, componente ou cliente do ChatGPT. A lista de verificação abaixo abrange os problemas mais comuns e como resolvê-los.

As verificações de servidor, ferramentas e descoberta se aplicam a plug-ins no ChatGPT e no Codex. As verificações de interface, estado do widget e autenticação do cliente nesta página descrevem o comportamento do ChatGPT.

Problemas no servidor

• Nenhuma ferramenta listada: Confirme que seu servidor está em execução e que você está se conectando ao endpoint /mcp. Se você alterou as portas, atualize a URL do servidor MCP e reinicie o MCP Inspector.
• Apenas conteúdo estruturado, sem componente: Confirme que o descritor da ferramenta define _meta.ui.resourceUri como um recurso HTML registrado com mimeType: "text/html;profile=mcp-app" (o ChatGPT aceita _meta["openai/outputTemplate"] como um alias opcional de compatibilidade) e que o recurso carrega sem erros de CSP.
• Erros de incompatibilidade de esquema: Verifique se seus modelos Python ou TypeScript correspondem ao esquema informado em outputSchema. Gere os tipos novamente após fazer alterações.
• Respostas lentas: Os componentes parecem lentos quando as chamadas de ferramentas levam mais de algumas centenas de milissegundos. Analise o desempenho das chamadas ao servidor e armazene os resultados em cache quando possível.

Problemas com widgets

• O widget não carrega: Abra o console do navegador (ou os logs do MCP Inspector) para verificar se há violações de CSP ou bundles ausentes. Verifique se o HTML contém seu JavaScript compilado e se o bundle contém todas as dependências.
• Alterações feitas por arrastar e soltar ou edição não persistem: Se você depende da persistência de estado de widgets do ChatGPT, chame window.openai.setWidgetState após cada atualização e restaure o estado a partir de window.openai.widgetState na montagem do componente.
• Problemas de layout em dispositivos móveis: Se você usa os sinais de layout do ChatGPT, inspecione window.openai.displayMode e window.openai.maxHeight para ajustar o layout. Evite alturas fixas ou ações que dependam exclusivamente de passar o cursor sobre um elemento.

Problemas de descoberta e pontos de entrada

• A ferramenta nunca é acionada: Revise seus metadados. Reescreva as descrições usando frases como “Use esta ferramenta quando…”, atualize os prompts iniciais e teste novamente com seu conjunto de prompts de referência.
• A ferramenta errada é selecionada: Adicione detalhes que diferenciem ferramentas semelhantes ou especifique na descrição os cenários em que seu uso não é permitido. Considere dividir ferramentas grandes em ferramentas menores, cada uma com uma finalidade específica.
• A classificação no inicializador parece inadequada: Atualize seus metadados no diretório e verifique se o ícone e as descrições do plug-in correspondem ao que os usuários esperam.

Problemas de autenticação

• Erros 401: Inclua um cabeçalho WWW-Authenticate na resposta de erro para que o ChatGPT saiba que deve reiniciar o fluxo OAuth. Confira as URLs do emissor e as declarações de público-alvo.
• Falha no registro do cliente: Se você usa CIMD, confirme que os metadados do seu servidor de autorização incluem client_id_metadata_document_supported: true e que o servidor consegue buscar o documento de metadados do cliente do ChatGPT. Para private_key_jwt, confirme que seu servidor de autorização consegue buscar o JWKS público do ChatGPT e verificar a asserção assinada do cliente. Se você usa DCR, confirme que seu servidor de autorização expõe registration_endpoint e que os clientes recém-criados têm pelo menos uma conexão de login habilitada.
• Uma conexão existente com um servidor MCP retorna invalid_client: Confirme que o cliente OAuth registrado dinamicamente ainda existe e que seu servidor de autorização aceita o segredo do cliente, caso ele tenha um. O ChatGPT reutiliza essas credenciais, então restaure-as em vez de criar um novo cliente. Um token de acesso expirado exige uma correção diferente.

Problemas de implantação

• O túnel ngrok excede o tempo limite: Reinicie o túnel e verifique se seu servidor local está em execução antes de compartilhar a URL. Para produção, use um provedor de hospedagem estável com verificações de integridade.
• O streaming falha ao passar por proxies: Verifique se seu balanceador de carga ou CDN permite eventos enviados pelo servidor ou respostas HTTP em streaming sem armazenamento em buffer.

Quando encaminhar o problema

Se você verificou os pontos acima e o problema persiste:

1. Colete logs (do servidor, do console do componente e da transcrição das chamadas de ferramentas do ChatGPT) e capturas de tela.
2. Anote o prompt que você enviou e quaisquer mensagens de confirmação.
3. Compartilhe os detalhes com seu contato de parceria na OpenAI para que ele possa reproduzir o problema internamente.

Um registro claro e conciso da investigação reduz o tempo de resolução e mantém seu servidor MCP confiável para os usuários.