Túnel MCP para ChatGPT: conecte um servidor MCP local ao ChatGPT

Seu servidor MCP roda perfeitamente em localhost:3000. Então você cola esse endereço no ChatGPT e recebe um erro. Nada está errado com seu código. O ChatGPT roda na nuvem da OpenAI, e seu notebook fica atrás de um roteador que nunca o convidou para entrar. Um túnel MCP para ChatGPT fecha essa lacuna: um pequeno programa na sua máquina abre uma conexão de saída com um intermediário, o intermediário entrega a você um endereço HTTPS público, e cada requisição que o ChatGPT envia para esse endereço desce pela conexão até o seu servidor local.

Este artigo segue a ordem em que você de fato vai trabalhar: o que o ChatGPT exige de um servidor MCP remoto, um servidor pequeno que vale a pena testar, duas opções de túnel com comandos exatos, o formulário de conector dentro do ChatGPT, os erros que consomem uma tarde inteira e os hábitos que impedem uma URL pública de virar um risco. No máximo, você precisa de uma conta gratuita de túnel, e nada além de um notebook comum.

💡 Resumo rápido: sirva seu endpoint MCP por Streamable HTTP, aponte um túnel para essa porta, cole https://<your-tunnel-host>/mcp no formulário de conector no modo desenvolvedor do ChatGPT e mantenha os dois processos rodando enquanto você conversa.

Por que o ChatGPT não consegue acessar localhost

Apenas servidores remotos

Os conectores do ChatGPT são feitos para servidores que vivem na internet pública. Um servidor que fala stdio, o transporte em que um cliente de desktop inicia seu programa como processo filho, não funciona aqui, porque o ChatGPT não tem como iniciar um processo no seu computador. O que ele consegue fazer é chamar um endpoint HTTPS, e a documentação da OpenAI lista tanto Server-Sent Events quanto Streamable HTTP como protocolos suportados. Escolha Streamable HTTP, a menos que tenha um motivo para não escolher: ele substituiu o antigo transporte HTTP mais SSE na especificação do Model Context Protocol, e é o que os SDKs atuais recomendam.

Há um segundo motivo, mais simples, para o localhost falhar. A palavra significa "esta máquina" para quem a lê. Quando o ChatGPT tenta http://localhost:3000, ele olha para os próprios servidores, não encontra nada na porta 3000 e desiste.

O que um túnel realmente faz

Um túnel inverte a direção da conexão. Sua máquina disca para fora, para o provedor do túnel, o que todo roteador doméstico e a maioria dos firewalls corporativos permitem, e mantém essa conexão aberta. O provedor tem um nome de host público com um certificado TLS válido e empurra as requisições recebidas pela conexão aberta. Na prática, uma requisição percorre cinco etapas:

1. O ChatGPT envia uma requisição para https://abc123.ngrok-free.app/mcp.
2. A borda do provedor recebe a requisição e encontra sua sessão aberta.
3. A requisição desce até o cliente de túnel no seu notebook.
4. O cliente a encaminha para http://localhost:3000/mcp.
5. A resposta do seu servidor volta pelo mesmo caminho.

Em comparação com o redirecionamento de portas clássico, você dispensa configurações de roteador, DNS dinâmico e renovação de certificados. Você também ganha um interruptor: feche o túnel e o endereço público deixa de funcionar imediatamente.

O que preparar primeiro

Plano e modo desenvolvedor

Os conectores personalizados para servidores MCP remotos ficam atrás do modo desenvolvedor. A documentação da OpenAI o lista para contas Plus, Pro, Business, Enterprise e Education na web. Em planos de espaço de trabalho, um administrador pode precisar liberá-lo antes, então confira isso antes de culpar seu servidor.

Os nomes dos menus mudam entre versões. Hoje o interruptor fica em Configurações, na seção Apps, como um botão Modo desenvolvedor perto do final. Versões mais antigas o colocavam em Conectores. Se você não o encontrar, pesquise a palavra "desenvolvedor" no painel de configurações.

Um servidor Streamable HTTP mínimo

Você precisa de algo pequeno para testar o túnel. Este servidor em TypeScript expõe uma ferramenta, em modo sem estado, então não há sessões para perder quando você o reiniciar. Instale as dependências primeiro:

npm install @modelcontextprotocol/sdk express zod
npm install -D tsx typescript @types/express

Copiar prompt

Depois salve isto como server.ts:

import express from "express";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { z } from "zod";

const app = express();
app.use(express.json());

function buildServer() {
  const server = new McpServer({ name: "local-notes", version: "1.0.0" });
  server.tool(
    "add_numbers",
    "Use this when the user asks to add two numbers together.",
    { a: z.number(), b: z.number() },
    async ({ a, b }) => ({ content: [{ type: "text", text: String(a + b) }] })
  );
  return server;
}

app.post("/mcp", async (req, res) => {
  const server = buildServer();
  const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
  res.on("close", () => {
    transport.close();
    server.close();
  });
  await server.connect(transport);
  await transport.handleRequest(req, res, req.body);
});

app.listen(3000, "127.0.0.1", () => console.log("MCP on http://127.0.0.1:3000/mcp"));

Copiar prompt

Execute com npx tsx server.ts. Três detalhes importam. Primeiro, a rota é /mcp, e esse caminho exato acaba no formulário do ChatGPT. Segundo, sessionIdGenerator: undefined torna cada requisição independente, o que combina com um túnel que pode reiniciar. Terceiro, a descrição da ferramenta começa com "Use this when", um hábito que ajuda o ChatGPT a escolher a ferramenta certa, já que ele escolhe ferramentas lendo essas frases.

Antes de existir qualquer túnel, comprove que o servidor responde a um handshake:

curl -i http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

Copiar prompt

Você deve ver um HTTP 200 e uma resposta que mencione local-notes. Se isso falhar localmente, nenhum túnel vai resolver.

Abrir o túnel

ngrok em dois comandos

Instale o ngrok com brew install ngrok no macOS, ou use o instalador do site do ngrok no Windows e no Linux. Depois adicione o token do seu painel e inicie o túnel:

ngrok config add-authtoken YOUR_TOKEN
ngrok http 3000

Copiar prompt

O terminal mostra uma linha de encaminhamento como https://abc123.ngrok-free.app -> http://localhost:3000. Acrescente /mcp e você tem a URL do conector. O ngrok também oferece um inspetor local em http://127.0.0.1:4040, que lista cada requisição e resposta, a forma mais rápida de ver exatamente o que o ChatGPT enviou.

Por padrão, o endereço muda sempre que o túnel reinicia. Reserve um domínio estático gratuito no painel do ngrok e depois execute ngrok http --url=your-name.ngrok-free.app 3000 (versões mais antigas do cliente usam --domain), para que a URL do conector sobreviva a reinicializações e você pare de editá-la todas as manhãs.

Quick tunnel da Cloudflare

Se você preferir a Cloudflare, instale cloudflared e execute um comando:

cloudflared tunnel --url http://localhost:3000

Copiar prompt

Ele mostra um endereço como https://random-words.trycloudflare.com. Quick tunnels não exigem conta, e isso é tanto o charme quanto o limite deles: o nome de host é novo a cada execução, então você precisa colá-lo de novo no ChatGPT toda vez. Desenvolvedores também relatam que quick tunnels podem ter dificuldade com Server-Sent Events, o que torna Streamable HTTP o par mais seguro. Para um endereço permanente, crie um named tunnel vinculado a um domínio seu.

Escolhendo o túnel certo

Para um primeiro teste, use o ngrok ou um quick tunnel. Para o uso diário, um endereço estável importa mais do que qualquer recurso dessa tabela.

Adicionar o conector no ChatGPT

Ative o modo desenvolvedor

1. Abra o ChatGPT em um navegador e vá em Configurações.
2. Encontre o botão Modo desenvolvedor e ative-o.
3. Leia o aviso. Um conector pode ler seus dados e, se você permitir, alterar coisas, então conecte apenas servidores em que confia.

Crie o app

1. Ao lado do botão, clique em Criar app. Versões mais antigas rotulam esse botão como Criar em Conectores.
2. Digite um nome, como "Notas Locais".
3. Escreva uma descrição curta de quando o modelo deve usá-lo.
4. Cole seu endereço público em URL do servidor MCP, com a rota incluída: https://abc123.ngrok-free.app/mcp. Usar apenas o nome de host sem /mcp é o erro mais comum.
5. Defina Autenticação como Sem autenticação para um teste descartável, ou OAuth se seu servidor o implementar.
6. Marque a caixa confirmando que você confia no app e clique em Criar.

O ChatGPT agora contata sua URL, executa o handshake MCP e lista as ferramentas que encontra. Ver add_numbers nessa tela significa que toda a cadeia funciona: ChatGPT, túnel e seu servidor.

Execute sua primeira chamada de ferramenta

Inicie um novo chat, abra o menu +, escolha Mais, selecione Modo desenvolvedor e ative seu app. Depois peça algo que precise dele: "Use Notas Locais para somar 19 e 23."

O ChatGPT mostra a chamada de ferramenta que quer fazer. Ferramentas somente leitura podem rodar livremente, enquanto ferramentas que gravam dados pedem confirmação explícita, então aprove a chamada e observe três lugares ao mesmo tempo:

• O chat: a resposta 42, com a chamada de ferramenta expansível acima dela.
• O terminal do seu servidor: a requisição recebida.
• O inspetor do ngrok: o JSON bruto que o ChatGPT enviou e que o seu servidor devolveu.

Quando os três coincidirem, você tem um túnel MCP para ChatGPT funcionando e um modelo para cada ferramenta que adicionar depois.

Corrija os erros que você vai encontrar

Erros de conexão e o caminho /mcp

Quando o ChatGPT se recusa a salvar o app ou informa que não conseguiu alcançar o servidor, percorra esta lista antes de mexer em qualquer código:

• O servidor está rodando? Abra o terminal onde ele foi iniciado e confirme que ainda está ativo.
• O túnel aponta para a mesma porta? ngrok http 3000 só funciona se seu servidor escutar na porta 3000.
• O caminho bate? A URL no ChatGPT precisa terminar na mesma rota que seu código registra.
• O túnel reiniciou? Um novo nome de host aleatório significa que a URL antiga do conector morreu.
• O endereço é HTTPS? O ChatGPT não aceita HTTP simples.

Depois, repita seu teste de handshake local contra o endereço público. Se ele falhar ali mas passar no localhost, a falha está entre o túnel e seu servidor, nunca dentro do ChatGPT:

curl -i https://abc123.ngrok-free.app/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

Copiar prompt

Ferramentas desatualizadas e cabeçalhos de host

Dois problemas parecem bugs e não são.

Ferramentas desatualizadas. O ChatGPT guarda a lista de ferramentas quando você cria o app. Se você adicionar, renomear ou reescrever uma ferramenta, o chat continua mostrando a versão antiga até você atualizar o conector na página de configurações ou recriá-lo. Sempre que uma ferramenta nova se recusar a aparecer, atualize primeiro.

Verificações do cabeçalho Host. Alguns frameworks, e alguns auxiliares de SDK MCP, validam o cabeçalho Host para bloquear ataques de DNS rebinding. Uma requisição que chega pelo túnel traz o nome de host do túnel em vez de localhost, então seu servidor pode responder 403 ou 421. Adicione o nome de host do túnel à lista de hosts permitidos. Quick tunnels trocam de nome de host a cada execução, então permita um sufixo como .trycloudflare.com em vez de desligar a verificação.

Proteja tudo

Trate a URL como pública

Qualquer pessoa que obtenha o endereço do seu túnel pode chamar seu servidor, a menos que algo a impeça. Um nome de host aleatório é ocultação, não proteção, e ele aparece em logs, capturas de tela e histórico do navegador. Use OAuth no servidor ou coloque uma camada de acesso na frente do túnel: o Cloudflare Access e as políticas de tráfego do ngrok existem exatamente para isso. Vincule seu servidor a 127.0.0.1, como faz o código de exemplo, para que apenas o cliente de túnel na sua própria máquina possa alcançá-lo diretamente.

Limite o que as ferramentas podem gravar

Uma ferramenta é uma promessa sobre o que o modelo pode fazer na sua máquina. Mantenha-a pequena:

• Comece com ferramentas somente leitura e adicione ferramentas de gravação uma de cada vez.
• Nunca exponha um comando de shell geral nem a exclusão irrestrita de arquivos.
• Restrinja as ferramentas de arquivo a uma única pasta de projeto.
• Registre cada chamada com seus argumentos, para que você consiga ver o que aconteceu depois.
• Trate a saída das ferramentas como texto não confiável. Uma página da web ou um documento que sua ferramenta devolve pode conter instruções destinadas ao modelo, um risco conhecido como prompt injection.
• Pare o túnel com Ctrl+C quando terminar. Um endereço público ocioso só traz desvantagens.

Quando um servidor hospedado vence

Um túnel é a ferramenta certa para construir e depurar. Para o uso diário, um servidor hospedado elimina toda uma classe de problemas, porque ele já vive em um endereço público: nenhum notebook para manter acordado, nenhum nome de host para colar de novo, nenhuma porta para esquecer.

A PicassoIA funciona assim no lado da API. Sua API para desenvolvedores roda em https://api.picassoia.com/v1 com endpoints no estilo Replicate: você cria uma previsão, consulta o status e depois busca o resultado. As conexões MCP são gerenciadas na sua conta em picassoia.com/en/mcp/accounts depois que você faz login, e uma conta pode executar até 5 previsões ao mesmo tempo, compartilhadas entre os tokens e as conexões MCP. Confira a página da API da PicassoIA para as regras de acesso atuais antes de construir sobre ela.

Como usar o GPT 5.4 na PicassoIA

Depurar um servidor MCP envolve muita escrita: descrições de ferramentas, esquemas JSON, explicações de erros. O GPT 5.4 é um bom parceiro de rascunho para esse trabalho. Aqui está um fluxo de trabalho que se encaixa neste artigo:

1. Abra a página do modelo GPT 5.4 na PicassoIA.
2. Cole o nome de uma ferramenta, o esquema de entrada dela e um objetivo em uma linha. Peça três variantes de descrição que comecem com "Use this when".
3. Peça ao modelo que liste duas situações em que o ChatGPT não deveria chamar essa ferramenta, e depois acrescente essas linhas à descrição.
4. Cole o erro exato do seu terminal ou do inspetor do ngrok e peça as três causas mais prováveis, ordenadas por probabilidade.
5. Copie a melhor descrição de volta para o seu servidor, reinicie-o e atualize o conector no ChatGPT.

Dicas de parâmetros: cole esquemas reais em vez de descrevê-los, mude uma coisa por prompt e mantenha cada requisição restrita a uma única ferramenta. Para uma segunda opinião sobre código complicado, rode o mesmo prompt pelo Claude Sonnet 5 ou pelo GPT 5.6 Sol e compare as respostas.

💡 Dica: quando dois modelos discordam sobre o motivo de uma requisição falhar, confie naquele que aponta para uma linha que você pode verificar no inspetor do ngrok.

Crie suas próprias imagens em seguida

Depois que seu servidor funcionar, você vai querer documentá-lo, demonstrá-lo ou colocá-lo em um README, e um post precisa de elementos visuais. Cada fotografia deste artigo foi gerada, não fotografada: cada prompt nomeia um assunto, um cenário, a direção da luz, uma lente e um tipo de filme. Essa receita funciona para qualquer tema que você escolher.

• Nomeie a luz: "luz dourada e baixa vinda da esquerda" vence "iluminação bonita".
• Escolha uma lente: "85mm a f/1.8" dá um ar de retrato, "24mm a f/8" dá uma cena ampla e nítida.
• Descreva texturas: lã, alumínio escovado e tijolo molhado fazem a imagem parecer real.

Abra a PicassoIA, escolha um modelo de imagem e teste um prompt para o seu próprio projeto. Se uma imagem estática não bastar, um modelo de texto para vídeo pode transformar a mesma ideia em movimento. Comece com uma cena da sua própria configuração e veja o quão perto o primeiro resultado chega.