O que você vai criar

Todo plugin baseado em MCP tem três partes:

• Um servidor MCP que define as ferramentas, retorna dados, aplica as regras de acesso e indica ao ChatGPT onde encontrar os recursos da interface.
• Um componente web opcional, exibido em um iframe do ChatGPT. Você pode criá-lo com React ou apenas com HTML, CSS e JavaScript.
• Um modelo que usa os metadados fornecidos por você para decidir quando chamar as ferramentas do plugin.

O Codex é mais útil quando assume as tarefas repetitivas de engenharia relacionadas a essas partes:

• Planejar quais ferramentas oferecer e definir seus metadados.
• Criar a estrutura inicial do servidor e do widget.
• Configurar os scripts de execução local.
• Implementar o controle de acesso e as mudanças necessárias para a implantação em etapas separadas.
• Criar uma rotina de verificação que comprove o funcionamento do plugin no ChatGPT.

Por que usar o Codex

• Os plugins baseados em MCP têm uma divisão clara entre o servidor, a interface opcional e as chamadas de ferramentas que o modelo decide fazer.
• O Codex responde melhor a prompts que definem uma tarefa explícita, com escopo delimitado e resultado fácil de verificar. O desenvolvimento de plugins se presta bem a esse tipo de tarefa.
• As Habilidades e o arquivo AGENTS.md fornecem ao Codex instruções reutilizáveis e regras para orientar seu trabalho no projeto.

Para saber como instalar e usar Habilidades, consulte a documentação sobre Habilidades.

Como usar

Pré-requisitos

• Comece definindo uma tarefa principal que o usuário poderá realizar, em vez de tentar levar um produto inteiro para o chat.
• Escolha as tecnologias desde o início: TypeScript ou Python para o servidor e React ou apenas HTML, CSS e JavaScript para o widget.
• Defina como você disponibilizará o servidor via HTTPS durante o desenvolvimento, por exemplo, com ngrok ou Cloudflare Tunnel.
• Algumas configurações ainda usam termos antigos para a conexão com um servidor MCP. Durante os testes locais, entenda esses rótulos como referências ao servidor registrado.

1. Escolha uma tarefa específica que o plugin deve ajudar o usuário a realizar e peça ao Codex que proponha de três a cinco ferramentas, definindo com clareza o nome, a descrição, as entradas e as saídas de cada uma.
2. Decida se a primeira versão pode retornar apenas dados ou se precisa de um widget. Crie a estrutura inicial do servidor MCP e, se necessário, do widget seguindo os padrões do repositório antes de adicionar dependências.
3. Execute o servidor MCP localmente com acesso via HTTPS, conecte-o ao ChatGPT usando a opção Adicionar um servidor MCP personalizado e teste-o com um pequeno conjunto de prompts diretos, indiretos e negativos.
4. Ajuste os metadados, o gerenciamento de estado e os payloads de structuredContent e _meta até que o fluxo principal de leitura funcione de forma confiável no ChatGPT.
5. Adicione OAuth 2.1 somente quando o acesso a dados específicos do usuário ou as operações de escrita exigirem autorização, sem complicar os fluxos anônimos ou de somente leitura.
6. Prepare uma prévia hospedada com um endpoint /mcp estável, verifique o streaming das respostas e a hospedagem dos recursos da interface e confira a lista de verificação de lançamento antes de compartilhar ou enviar o plugin para análise.

Sugestões de prompts

Os prompts mais eficazes para esse fluxo de trabalho incluem os seguintes elementos:

• Um objetivo claro: diga o que o plugin deve ajudar o usuário a fazer no ChatGPT.
• Tecnologias bem definidas: indique se prefere TypeScript ou Python no servidor e se o widget deve usar React ou manter uma implementação leve.
• Responsabilidades bem delimitadas: peça ao Codex que proponha ou crie um conjunto pequeno de ferramentas, cada uma com uma única função.
• Requisitos de acesso: esclareça se a primeira versão pode permitir acesso anônimo ou se precisa de contas vinculadas e operações de escrita.
• Acesso ao ambiente de desenvolvimento local: indique o túnel ou a opção de hospedagem que pretende usar nos testes via HTTPS no ChatGPT.
• Etapas de verificação: diga ao Codex quais comandos executar, quais prompts testar e quais evidências apresentar.

Evite pedir planejamento, implementação, controle de acesso, implantação, envio para análise e ajustes finais em um único prompt. Divida o trabalho em etapas menores.

Planeje o plugin antes de criar a estrutura inicial

Crie a estrutura da primeira versão funcional

Adicione o controle de acesso somente depois que o fluxo principal estiver funcionando

Prepare o plugin para implantação e revisão

Verificações antes do lançamento

• O plugin tem um objetivo específico e fácil de entender para os usuários.
• O conjunto de ferramentas é pequeno, e cada ferramenta tem metadados, entradas e saídas explícitos.
• O servidor MCP funciona de ponta a ponta e retorna conteúdo conciso em structuredContent, reservando _meta para os dados de uso exclusivo do widget.
• O widget, se necessário, é exibido corretamente no ChatGPT.
• É possível executar a rotina de testes locais via HTTPS com o servidor MCP personalizado conectado ao ChatGPT.
• Os testes com um pequeno conjunto de prompts diretos, indiretos e negativos passam e produzem o fluxo de conversa e os payloads das ferramentas esperados.
• O controle de acesso foi implementado apenas onde os dados específicos do usuário ou as operações de escrita o exigem.
• Antes de compartilhar ou enviar o plugin para análise, o plano de implantação e a revisão de lançamento contemplam metadados, indicações de uso das ferramentas, privacidade e prompts de teste.

Erros comuns

• Pedir ao Codex que leve o produto inteiro para o ChatGPT. Limite o pedido a uma tarefa principal do usuário, de três a cinco ferramentas e um widget de escopo restrito.
• Começar com um prompt que pede toda a implementação de uma vez. Divida o trabalho em etapas de planejamento, criação da estrutura inicial, controle de acesso, implantação e revisão.
• Criar a interface antes de definir o contrato das ferramentas. Planeje primeiro quais ferramentas oferecer e qual será o schema das respostas. Em seguida, crie o widget.
• Deixar de usar a documentação oficial como fonte de fundamentação. Use $chatgpt-apps com $openai-docs para que a estrutura inicial siga as orientações atuais para plugins.
• Deixar os metadados para o fim. Escreva as descrições das ferramentas e a documentação dos parâmetros logo no início. Depois, execute novamente um conjunto de prompts para testar essas definições.
• Adicionar controle de acesso antes de validar o fluxo anônimo ou de somente leitura. Faça o fluxo principal de chamadas de ferramentas funcionar primeiro. Depois, adicione OAuth às ferramentas que realmente precisam dele.
• Considerar o plugin pronto antes de testá-lo no ChatGPT. Conecte o servidor MCP personalizado ao ChatGPT, inspecione os payloads das ferramentas e verifique o fluxo real da conversa.