Dev Mode no ChatGPT: conectando um aplicativo local

1. O que é o Developer Mode na prática

Você já sabe um pouco sobre o Dev Mode, mas agora é importante montar um quadro completo, baseado em prática real.

O Developer Mode no ChatGPT é um modo especial em que a plataforma permite conectar seu aplicativo diretamente, sem publicar na Store. Você diz ao ChatGPT: “Aqui está o URL do meu servidor MCP”, e o ChatGPT passa a tratá-lo como uma ferramenta externa com UI — pode chamar suas ferramentas, carregar widgets, e tudo isso dentro de um chat normal.

Se lembrarmos a arquitetura, no Dev Mode o ChatGPT atua como cliente MCP, e seu template em Next.js — como servidor MCP. O ChatGPT estabelece conexão com o /mcp, pergunta: “O que você sabe fazer?” (lista de tools e resources) e, em seguida, no decorrer do diálogo, pode chamar essas ferramentas e exibir seus widgets em um iframe.

É importante separar Dev Mode de Store:

• Dev Mode — sua pequena “garagem” pessoal: você pode quebrar, experimentar, mudar o esquema de ferramentas a cada cinco minutos, sem se preocupar com usuários.
• Store — vitrine: vai para lá uma versão estável, após revisão e com política, descrições etc. Vamos chegar lá no fim do curso; por enquanto, brincamos na garagem.

No fim de 2025, o Dev Mode com o Apps SDK está disponível em todos os planos do ChatGPT, mas em contas corporativas às vezes é necessário que o administrador o habilite no nível do workspace. Se nas configurações o switch de Developer Mode não aparecer, esse é o primeiro ponto a verificar.

2. O que já temos no início da aula

Antes de clicar em qualquer coisa na interface do ChatGPT, vamos garantir que a parte local está pronta.

Primeiro, o servidor de desenvolvimento do Next.js. Na raiz do projeto você já executou:

npm run dev

Por padrão, o Next.js 16 escuta na porta 3000, então seu UI fica disponível em http://localhost:3000.

Segundo, a rota MCP. No template do CodeGym Labs, o servidor MCP é implementado como um route‑handler em app/mcp/route.ts. É exatamente nesse arquivo que as ferramentas e os recursos são registrados; é exatamente para lá que chegam as primeiras requisições do ChatGPT ao conectar o app no Dev Mode.

Do ponto de vista da arquitetura, agora está assim:

Seu navegador ──> http://localhost:3000 (Next.js dev, UI)
                           │
                           └── /mcp (Servidor MCP dentro do Next.js)

Por enquanto não há nenhuma conexão com o ChatGPT — ele está na nuvem, e o seu localhost não é visível para ele. A configuração detalhada do túnel é tema da próxima aula. Aqui, para simplificar, vamos supor que você já tem um HTTPS‑URL público para o /mcp (por exemplo, via ngrok ou Cloudflare Tunnel, configurado conforme o README do template).

Se você ainda não subiu o túnel — sem problemas. Agora você pelo menos vai percorrer com os olhos toda a cadeia de passos no Dev Mode e ver exatamente o que será necessário fazer quando o HTTPS‑URL existir.

Se você já tem um HTTPS‑URL para o /mcp, então pode repetir todos os passos manualmente.
Se ainda não tem — passe pela aula como um “tour da interface”: o importante é entender a cadeia de passos, e faremos a execução real na próxima aula, quando configurarmos o túnel.

3. Ativando o Developer Mode na interface do ChatGPT

O primeiro passo é simplesmente fazer o ChatGPT exibir as configurações de que precisamos. Faça o seguinte:

Entre na versão web do ChatGPT com a conta que você usará para desenvolver. Clique no ícone de perfil no canto inferior esquerdo (ou superior direito — o UI está sempre evoluindo) e escolha Settings (Configurações).

Nas configurações, encontre a seção relacionada a aplicativos: normalmente se chama Apps & Connectors ou Connected apps. Abra essa seção. Na parte de baixo da página (ou na aba Advanced / Avançado) aparecerá o switch Developer Mode. É exatamente isso que você precisa ativar.

Depois de ativar o Dev Mode, o ChatGPT normalmente mostra um aviso de que o modo de desenvolvedor foi ligado. Na mesma seção aparece um botão como Create, Create connector, New app — as frases podem variar um pouco, mas a ideia é a mesma: surgiu uma forma de criar seu próprio aplicativo conectado.

Se, nas configurações, você não tem a seção Apps & Connectors nem o switch de Developer Mode, verifique:

• se você realmente está logado na conta do ChatGPT que pretende usar;
• em contas corporativas, esse modo pode ser habilitado pelo administrador do workspace.

Às vezes basta sair e entrar de novo (o clássico “reconectar a internet” do Dev Mode).

4. Criando seu aplicativo/conector e informando o MCP URL

Agora que o Dev Mode está ativado, vamos registrar seu GiftGenius no ChatGPT. Abaixo — um roteiro de “como fazer de verdade”. Se o HTTPS‑URL ainda não estiver configurado, encare os passos como um ensaio: apenas veja o que faremos quando o túnel estiver pronto.

Tudo é feito pela seção de configurações do ChatGPT, onde você acabou de estar. A sequência será mais ou menos assim.

Abra novamente Settings → Apps & Connectors. Lá você verá a lista de apps já conectados (provavelmente ainda vazia) e um botão Create / Add connector. Clique nele — abrirá um formulário de criação de aplicativo.

O formulário geralmente tem três campos principais:

1. Nome (Name). É um nome legível por pessoas, visível para você e para o ChatGPT. Para o nosso curso, é conveniente chamar o app, por exemplo, de GiftGenius (dev) — assim fica claro que é a versão local de desenvolvimento.
2. Descrição (Description). Uma explicação breve do que o app faz e quando vale a pena usá-lo. Exemplo: “Seleciona ideias de presentes com base nos interesses da pessoa”. Essa linha influencia o discovery — o modelo a utiliza para decidir quando sugerir seu App no chat.
3. URL do servidor MCP (às vezes rotulado como Connector URL, MCP endpoint, App URL etc.). Este é o campo mais importante: aqui você cola um HTTPS‑URL público que aponte para /mcp do seu app.

Por exemplo:

https://my-giftgenius-dev.ngrok.app/mcp

ou

https://giftgenius-dev.trycloudflare.com/mcp

Pontos principais para esse campo:

• precisa ser https://, caso contrário o ChatGPT simplesmente se recusará a conectar;
• obrigatoriamente o path /mcp no final, porque é exatamente onde vive o servidor MCP dentro do template; é este path que está descrito na documentação oficial do Apps SDK.

De onde tirar esse URL, vamos detalhar na próxima aula (túneis, Cloudflare, ngrok). Agora o importante é entender a ideia: seu http://localhost:3000/mcp local precisa de alguma forma virar um https://…/mcp público, e é esse endereço público que você coloca no formulário.

Depois de preencher os campos, clique em Create / Salvar. Nesse momento, o ChatGPT faz um “aperto de mão” com seu servidor: envia requisições HTTP para o URL informado, espera receber um manifesto de capacidades (lista de tools/resources, metadados) e verifica se o servidor responde pelo protocolo MCP. Se tudo correr bem, o conector aparecerá na lista e você verá quais ferramentas o ChatGPT encontrou. Na próxima seção, vamos dissecar o que exatamente acontece nesse aperto de mão e como ver isso nos logs.

Se você ainda não configurou o túnel e colou um URL fictício, o ChatGPT vai dizer honestamente que não conseguiu alcançar o servidor. Isso também é útil: você vê imediatamente onde e como os erros são exibidos.

5. O que acontece “por baixo do capô”: MCP‑handshake em termos simples

Por fora, tudo parece um formulário comum “adicionar app por URL”. Por dentro, é um pouco mais interessante, e entender isso agora ajuda bastante na depuração depois.

Você já viu que, ao criar o conector, o ChatGPT acessa seu /mcp e espera um manifesto. Vamos detalhar um pouco essa conversa — isso ajuda muito na hora de depurar.

Ao clicar no botão Create, o ChatGPT faz alguns passos.

Primeiro, ele acessa o URL informado com /mcp, atuando como cliente MCP. Pelo protocolo MCP, ele espera que nesse endpoint HTTP exista um servidor implementando capacidades básicas: listar ferramentas (list tools), fornecer recursos (widgets), processar chamadas de ferramentas.

O servidor, por sua vez, responde com uma estrutura JSON contendo a descrição:

• nome do servidor e versão;
• lista de ferramentas: name, title, description, inputSchema etc.;
• lista de recursos: onde obter o HTML dos seus widgets, quais MIME types, como renderizá-los.

No template em Next.js do CodeGym, tudo isso já está implementado em app/mcp/route.ts: lá, com a ajuda do SDK, algo como server.registerTool(...) e server.registerResource(...) é chamado.

Se você quiser ver esse aperto de mão com seus próprios olhos, pode adicionar em app/mcp/route.ts um log simples. Isso é mais um truque de depuração para desenvolvedores; você pode pular e voltar a ele depois, quando quiser se aprofundar:

// app/mcp/route.ts
import { NextRequest, NextResponse } from "next/server";
// importe seu server/buildManifest já existente

export async function GET(req: NextRequest) {
  console.log("[MCP] Handshake from ChatGPT:", req.headers.get("user-agent"));
  const manifest = buildManifestSomehow(); // isso já existe no template
  return NextResponse.json(manifest);
}

Essa função é um pouco hipotética (no template, a estrutura pode diferir), mas a ideia é simples: app/mcp/route.ts é um route‑handler comum do Next.js, e você pode registrar logs das requisições recebidas. Ao conectar com sucesso no Dev Mode, você verá esse log no terminal onde o npm run dev está rodando.

Do ponto de vista do protocolo, podemos desenhar como um pequeno diagrama:

sequenceDiagram
    participant ChatGPT
    participant Tunnel as HTTPS URL (/mcp)
    participant NextDev as Next.js dev + MCP

    ChatGPT->>Tunnel: Requisição HTTP(S) para https://.../mcp
    Tunnel->>NextDev: Proxy para http://localhost:3000/mcp
    NextDev-->>Tunnel: JSON com ferramentas e recursos
    Tunnel-->>ChatGPT: Encaminha a resposta
    ChatGPT->>ChatGPT: Faz cache da lista de tools/resources

O fato de você ter inserido “apenas um URL” no formulário do Dev Mode, na verdade, dispara uma conversa de protocolo inteira.

6. Como o ChatGPT “vê” seu aplicativo após a conexão

Vamos supor que o aperto de mão tenha ocorrido com sucesso. E agora?

Primeiro, nas configurações, na seção Apps & Connectors, seu GiftGenius (dev) aparecerá na lista de apps conectados. No cartão, você verá o nome, a descrição e a lista de ferramentas detectadas. Ali também costumam existir botões como Refresh, Delete etc. O botão Refresh será útil mais tarde, quando você mudar o esquema de ferramentas.

Segundo, o aplicativo fica disponível nos próprios chats. Abra um novo chat e clique no botão “+” ao lado do campo de entrada. Há um menu “More”, “Apps”, “Tools” — dependendo da versão atual do UI. Seu GiftGenius (dev) deve aparecer na lista, e você pode selecioná-lo explicitamente para essa conversa.

Depois de escolhido, o aplicativo fica “conectado” a esse chat. Para você, isso se parece com:

• você escreve um pedido natural, por exemplo: “Escolha um presente para um fã de espaço por 50$”;
• o ChatGPT decide (pela descrição e pelo histórico do diálogo) que pode usar o GiftGenius e chama uma das suas ferramentas MCP;
• o resultado dessa chamada pode conter um widget HTML; ele é renderizado diretamente no chat como um cartão/painel.

No Dev Mode, com mais frequência você primeiro chamará o app explicitamente — via escolha no menu ou menção explícita pelo nome. Mas é importante entender: em produção, o ChatGPT pode “sugerir” seu App por conta própria, com base na descrição e nos metadados das ferramentas.

Para visualizar, é útil imaginar mais uma tabela:

7. Ciclo de desenvolvimento: muda o código → vê no ChatGPT

Conectar o App é metade do trabalho. A outra metade é entender como conviver com o Dev Mode no dia a dia.

Há dois tipos grandes de mudanças: mudanças no UI (widget) e mudanças na lógica/ferramentas do MCP.

Se você muda apenas o UI, por exemplo ajusta o título ou estilos em app/page.tsx, para o Next.js isso é frontend normal. O servidor de dev reinicia o módulo e, no navegador, você vê hot reload. No ChatGPT seu UI é aberto em um iframe, mas o comportamento é parecido: na próxima chamada da ferramenta que renderiza esse widget, o ChatGPT carregará o HTML já atualizado. Às vezes o HMR chega direto ao iframe, às vezes basta chamar a ferramenta novamente no chat. CACHE

Tente, para fixar, mudar um pouco o widget. Suponha que em app/page.tsx você tenha algo assim:

export default function GiftGeniusWidget() {
  return (
    <main style={{ padding: 16 }}>
      <h1>GiftGenius</h1>
      <p>Aqui ficará a seleção de presentes.</p>
    </main>
  );
}

Altere o título e o texto:

export default function GiftGeniusWidget() {
  return (
    <main style={{ padding: 16 }}>
      <h1>GiftGenius (dev)</h1>
      <p>Esta versão roda no Dev Mode. Não é para uso em produção.</p>
    </main>
  );
}

Salve o arquivo, volte ao chat com o GiftGenius conectado e chame o app de novo (por exemplo, com o mesmo pedido de presente). Você deve ver o título atualizado dentro do widget — é um bom sinal de que o encadeamento Next.js → túnel → ChatGPT está funcionando.

Se você muda a parte MCP — adiciona uma nova ferramenta, altera o inputSchema, muda nomes de tools — então entra em cena o cache do ChatGPT. Na primeira conexão no Dev Mode, o ChatGPT memoriza a lista de ferramentas e nem sempre capta as mudanças automaticamente. Nesse caso, volte à seção Apps & Connectors, escolha seu GiftGenius (dev) e clique em algo como Refresh schema / Refresh. Depois disso, o ChatGPT vai consultar novamente seu /mcp e atualizar a lista de tools.

Parece detalhe, mas sem isso é fácil cair na situação: você já corrigiu o código da ferramenta, mas o ChatGPT teima em não ver os novos parâmetros.

8. Mini prática: o primeiro cenário completo do GiftGenius no Dev Mode

Vamos juntar tudo em um cenário prático. Aqui vou considerar que você tem um HTTPS‑URL funcional para o /mcp (via túnel ou deploy). Se ainda não tem — apenas leia os passos; na próxima aula você os repetirá com o URL real.

1. Verifique se o npm run dev está rodando e os logs não têm erros. É especialmente bom ver algo como “MCP server running at http://localhost:3000/mcp” no terminal, se o template logar isso.
2. Abra o ChatGPT e ative o Developer Mode via Settings → Apps & Connectors → Advanced settings.
3. Crie um novo conector GiftGenius (dev) com uma descrição curta (“Helper for choosing gifts”) e um URL do tipo https://<seu-dominio>/mcp.
4. Verifique se o ChatGPT conseguiu conectar: na lista de aplicativos você verá o novo item. Se não conectou — veja os logs do servidor de dev e do túnel; isso é útil por si só.
5. Abra um novo chat, clique em “+”, escolha seu GiftGenius (dev), então faça o pedido: “Escolha um presente para um desenvolvedor que gosta de espaço e café, orçamento 40$”.
6. Veja o que seu template atual faz: na forma básica ele pode mostrar um cartão/widget simples. Ainda não é uma “seleção inteligente de presentes”, mas o fato de algo ter aparecido no chat vindo do seu código — já é um grande passo.

Como exercício extra, você pode criar uma ferramenta de teste no servidor MCP apenas para verificar o Dev Mode. Exemplo (não é obrigatório implementar agora, apenas veja a ideia):

// dentro de app/mcp/route.ts, junto com outras tools
server.registerTool(
  "ping_dev",
  {
    title: "Ping GiftGenius dev",
    description: "Verifica se o servidor de desenvolvimento está ativo.",
    inputSchema: { type: "object", properties: {} },
  },
  async () => ({
    content: [{ type: "text", text: "GiftGenius dev is alive ✅" }],
    structuredContent: {},
  })
);

Vamos detalhar o server.registerTool no módulo sobre ferramentas; por ora, basta lembrar: via MCP você descreve “o que o seu App sabe fazer”, e o Dev Mode é a forma de dar ao ChatGPT um URL no qual essas capacidades estão declaradas.

9. Onde ver erros e como distinguir “quebrou do meu lado” de “quebrou no ChatGPT”

Ninguém gosta de passar meia hora caçando bugs “no lado errado do sistema”, então é útil adotar desde já o hábito de olhar no lugar certo.

Se o erro aparece ao criar o conector. Se, ao criar o conector, o ChatGPT disser que não consegue conectar o App, a primeira coisa é ver os logs do seu servidor de dev e do túnel. Se no terminal onde o npm run dev está rodando não houver requisições de entrada para /mcp — o problema está no caminho ChatGPT → túnel. Se as requisições existem, mas o servidor responde 500 ou cai com erro no console — o problema está no seu código MCP.

Se o conector já foi criado, mas quebra no chat. Quando o conector já existe, e no chat periodicamente aparece um aviso “App unavailable / App broken”, isso quase sempre significa que:

• o servidor de dev caiu (o Next.js parou de escutar a porta 3000);
• o túnel foi desligado ou o URL mudou;
• o endpoint MCP retorna erro, timeout ou responde muito devagar.

Separadamente sobre o UI/widget. Em problemas de UI (widget não renderiza, tela em branco, estilos estranhos), veja também o DevTools do navegador. O widget carrega em um iframe, e no console desse iframe você verá erros de JavaScript/React — exatamente como em um app web comum.

Com o tempo, você vai começar a diferenciar “cheiro de túnel” de “cheiro de Next.js” só de olhar o erro, mas por enquanto basta lembrar: você tem três pontos potenciais de falha — seu código, o túnel e o ChatGPT — e a probabilidade de o problema estar no ChatGPT é geralmente a menor.

Insight

Se você está lendo este texto e não tem um túnel pago, pode comprá-lo agora mesmo. Você vai acabar fazendo isso nos próximos dias de qualquer jeito. Então economize seus nervos.

10. Erros típicos ao trabalhar com o Dev Mode

Erro nº 1: esqueceu de ativar o Developer Mode e ficou meia hora procurando o botão Create.
Às vezes os desenvolvedores entram direto no ChatGPT, vão nas configurações de Apps & Connectors e não veem nada interessante. Sem o Developer Mode ativado, o botão de criar conector pode simplesmente não existir. Sempre comece verificando se o Dev Mode está ligado em Advanced settings, especialmente em contas novas ou em outro navegador.

Erro nº 2: colou um URL sem /mcp ou que nem é um endpoint MCP.
Clássico: no campo de URL colam https://myapp-dev.ngrok.app sem o path /mcp, ou até um URL de landing/serviço diferente. O ChatGPT bate educadamente lá pelo protocolo MCP, não encontra a interface esperada e retorna erro de conexão. O template starter do Next.js diz claramente: a conexão deve ser com o URL que aponta para /mcp — e é exatamente esse que se informa no Dev Mode.

Erro nº 3: tentar usar http://localhost:3000/mcp diretamente.
É intuitivo colar no campo de URL aquele http://localhost:3000/mcp que você vê nos logs do servidor de dev. Mas o ChatGPT roda na nuvem, não no seu notebook, e não tem acesso ao seu localhost. Além disso, o ChatGPT exige HTTPS. Portanto, sem túnel ou deploy remoto, não vai funcionar. Não é bug do ChatGPT, é isolamento de rede normal.

Erro nº 4: esquecer o Refresh depois de mudar o esquema do MCP.
Após o aperto de mão bem-sucedido, o ChatGPT faz cache da lista de ferramentas e metadados para não chamar o servidor toda vez. Se você adicionou uma nova tool ou mudou o inputSchema e o ChatGPT continua se comportando como antes, quase certamente é preciso dar Refresh no conector na seção Apps & Connectors. Sem isso, o modelo simplesmente não sabe que as ferramentas mudaram.

Erro nº 5: tentar depurar o Dev Mode quando o servidor de dev não está rodando.
Parece óbvio, mas acontece muito: o aluno configura o Dev Mode e o túnel remotamente, embora no terminal o npm run dev já nem esteja rodando, ou o projeto não builda por erro de sintaxe. Enquanto o servidor de dev local estiver parado, é inútil correr atrás de erros do Dev Mode. Sempre garanta que o http://localhost:3000 funciona no seu navegador, e só então conecte o ChatGPT.

Erro nº 6: esperar que o Dev Mode seja “outro modelo que entende tudo”.
Às vezes parece que, já que ativamos o Dev Mode, agora o modelo “sabe” tudo sobre nosso app. Na verdade, o Dev Mode não muda o modelo em si; ele só dá acesso ao seu servidor MCP e às ferramentas. Se as ferramentas estão descritas de forma vaga, a descrição do App é imprecisa ou a lógica do servidor é esquisita, o modelo vai se confundir tanto quanto qualquer desenvolvedor que abrisse uma API mal documentada. Bons metadados e ferramentas são tema dos próximos módulos, mas vale ter isso em mente desde já.

Erro nº 7: usar o Dev Mode como produção.
Às vezes bate a tentação: “Já que tudo funciona bem no Dev Mode, vamos dar o link para os usuários conectarem o App por esse URL”. O problema é que o Dev Mode não é destinado a uso em massa: túneis são instáveis, configurações podem quebrar, e o próprio ChatGPT pode mudar o comportamento do Dev Mode sem compatibilidade retroativa. Para usuários reais existem a Store e o deploy de produção. Dev Mode é exclusivamente seu laboratório.