Solução de problemas

Como identificar a origem do problema

Se um componente não for renderizado, a descoberta de ferramentas não reconhecer um prompt ou a autenticação entrar em loop, comece identificando em qual camada ocorre a falha (servidor, componente ou cliente do ChatGPT). A lista abaixo reúne os problemas mais comuns e explica como resolvê-los.

As verificações de servidor, ferramentas e descoberta se aplicam aos plugins 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 aparece na lista: Verifique se o servidor está em execução e se você está se conectando ao endpoint /mcp. Se mudou de porta, atualize a URL do servidor MCP e reinicie o MCP Inspector.
• Aparece apenas o conteúdo estruturado, sem o componente: Verifique se _meta.ui.resourceUri no descritor da ferramenta aponta para um recurso HTML registrado com mimeType: "text/html;profile=mcp-app". O ChatGPT também aceita _meta["openai/outputTemplate"] como alias opcional para compatibilidade. Confirme que o recurso carrega sem erros de CSP.
• Erros de incompatibilidade de schema: Verifique se os modelos em Python ou TypeScript correspondem ao schema declarado em outputSchema. Gere os tipos novamente após fazer alterações.
• Respostas lentas: Quando as chamadas de ferramentas demoram mais de algumas centenas de milissegundos, os componentes parecem lentos. Analise o desempenho das chamadas ao servidor e, quando possível, armazene os resultados em cache.

Problemas com widgets

• O widget não carrega: Abra o console do navegador ou consulte os logs do MCP Inspector para verificar se há violações de CSP ou pacotes ausentes. Verifique se o HTML inclui o JavaScript compilado e se o pacote contém todas as dependências.
• As alterações feitas ao arrastar e soltar ou ao editar não são salvas: Se você usa o ChatGPT para salvar o estado do widget, 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, consulte window.openai.displayMode e window.openai.maxHeight para ajustar o layout. Evite alturas fixas e ações que só ficam disponíveis ao passar o ponteiro sobre um elemento.

Problemas na descoberta de ferramentas e nos pontos de entrada

• A ferramenta nunca é acionada: Revise os metadados. Reescreva as descrições usando frases como “Use esta ferramenta quando…”, atualize os prompts iniciais e repita os testes com seu conjunto de prompts de referência.
• A ferramenta selecionada está incorreta: Acrescente detalhes que diferenciem ferramentas semelhantes ou especifique na descrição em quais situações a ferramenta não deve ser usada. Considere dividir ferramentas grandes em ferramentas menores, cada uma com uma finalidade específica.
• A ordem no inicializador parece incorreta: Atualize os metadados no diretório e verifique se o ícone e as descrições do plugin correspondem ao que os usuários esperam.

Problemas de autenticação

• Erros 401: Inclua o 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 os valores das declarações de público-alvo.
• Falha no registro do cliente: Se você usa CIMD, confirme que os metadados do 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. Se você usa private_key_jwt, confirme que o 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 o 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: Verifique se o cliente OAuth registrado dinamicamente ainda existe e se o servidor de autorização aceita o segredo do cliente, caso ele tenha um. Como o ChatGPT reutiliza essas credenciais, restaure-as em vez de criar um novo cliente. Se o token de acesso expirou, a solução é outra.

Problemas de implantação

• O tempo de conexão do túnel ngrok se esgota: Reinicie o túnel e verifique se o servidor local está em execução antes de compartilhar a URL. Em produção, use um provedor de hospedagem estável que ofereça verificações de integridade.
• Falhas de streaming ao usar proxies: Verifique se o balanceador de carga ou a CDN permite eventos enviados pelo servidor ou respostas HTTP em streaming sem armazenar os dados em buffer.

Quando acionar a OpenAI

Se você já verificou os itens acima e o problema persiste, siga estas etapas:

1. Reúna os logs do servidor e do console do componente, a transcrição da chamada de ferramenta no ChatGPT e as capturas de tela.
2. Anote o prompt que você enviou e as mensagens de confirmação, se houver.
3. Compartilhe os detalhes com seu contato de parcerias na OpenAI para que ele possa reproduzir o problema internamente.

Um registro claro do problema e das verificações realizadas ajuda a resolvê-lo mais rápido e a manter o servidor MCP confiável para os usuários.