Um tutorial prático para adicionar um servidor MCP personalizado ao ChatGPT. Ative o modo desenvolvedor, preencha o formulário do conector, escolha OAuth ou nenhuma autenticação, teste o servidor com um túnel, corrija os erros mais comuns e adicione ferramentas de imagem e vídeo.
Você tem um servidor que faz algo útil e quer que o ChatGPT o chame a partir de um chat comum. A porta existe, e é um único formulário. O problema é que o formulário esconde quatro ou cinco armadilhas que fazem um servidor perfeitamente saudável parecer quebrado. Este tutorial percorre o caminho inteiro, desde ativar o modo desenvolvedor até aprovar a primeira chamada de ferramenta, e aponta cada armadilha antes que você caia nela. Você vai criar um pequeno servidor de teste, expô-lo com um túnel, corrigir os erros que as pessoas mais encontram e, em seguida, ver como ferramentas de imagem e vídeo do PicassoIA podem se conectar ao mesmo conector.
O Model Context Protocol (MCP) é um padrão aberto que permite que um cliente de IA chame ferramentas em um servidor. O servidor publica uma lista de ferramentas. Cada ferramenta tem um nome, uma descrição em linguagem simples e um esquema JSON para suas entradas. O cliente lê essa lista, decide quando uma ferramenta ajuda e envia uma solicitação estruturada. O servidor responde com dados ou executa uma ação.
No ChatGPT, um conector MCP personalizado é a entrada de configuração que aponta o ChatGPT para um desses servidores. Depois que ele é salvo, suas ferramentas aparecem nos chats ao lado das integradas.
Os conectores integrados atendem a aplicativos populares. Seu próprio servidor atende todo o resto:
💡 Somente remoto. O ChatGPT se comunica com servidores MCP remotos. Um servidor que roda como processo local via stdio, como muitas ferramentas de desktop, precisa ser encapsulado em um endpoint HTTP antes que o ChatGPT consiga acessá-lo.
O modo desenvolvedor começou como uma beta para contas Plus e Pro na web. Planos de workspace como Business, Enterprise e Edu acessam o recurso por meio de uma permissão controlada pelo administrador, em vez de uma chave pessoal. A OpenAI ajustou quais planos recebem ações de escrita e mudou a chave de lugar entre os menus mais de uma vez, então trate qualquer lista de planos (inclusive esta) como algo em constante mudança. Se sua tela for diferente dos passos abaixo, consulte o artigo de ajuda atual da OpenAI sobre o modo desenvolvedor.
Em um workspace, a permissão normalmente fica na área de permissões e funções das configurações do workspace. Se a chave não aparecer para você, peça a um administrador antes de culpar seu servidor.
O ChatGPT se conecta a partir da infraestrutura da OpenAI, não do seu notebook. Isso tem três consequências:
O ChatGPT aceita dois transportes remotos:
| Transporte | Funciona com o ChatGPT | URL típica | Observações |
|---|---|---|---|
| Streamable HTTP | Sim | https://your-domain.com/mcp | Melhor escolha para um servidor novo |
| SSE (Server-Sent Events) | Sim | https://your-domain.com/sse | Estilo mais antigo, ainda aceito |
| stdio (processo local) | Não | nenhuma | Encapsule primeiro em um servidor HTTP |
Os conectores personalizados ficam atrás de uma chave, porque um servidor personalizado pode ler e alterar dados reais. Este é o caminho:
Quando a chave estiver ativada, um botão Criar aparece na página de conectores.
💡 Não encontra a chave? A configuração mudou de lugar durante 2026. Pesquise na janela de configurações a palavra "developer" antes de concluir que seu plano não a tem.
Clique em Criar e preencha estes campos:
| Campo | O que digitar | Dica |
|---|---|---|
| Nome | Um rótulo curto, como "Consulta de pedidos" | É isso que você escolhe no menu do chat |
| Descrição | Uma ou duas frases sobre o que o servidor faz | O modelo lê isso ao decidir se deve chamar uma ferramenta, então escreva como uma instrução |
| Ícone | Opcional | Ajuda a encontrá-lo em uma lista longa |
| URL do servidor MCP | A URL HTTPS completa incluindo o caminho, como https://api.example.com/mcp | Um caminho ausente é uma causa muito comum de falha |
| Autenticação | Nenhuma autenticação ou OAuth | Detalhes na próxima seção |
Marque a caixa confirmando que você confia no aplicativo e clique em Criar.
| Opção | Use quando | Risco |
|---|---|---|
| Nenhuma autenticação | Dados públicos somente leitura ou um servidor de teste descartável | Qualquer pessoa que encontrar a URL pode chamar suas ferramentas |
| OAuth | Qualquer coisa ligada a uma conta de usuário, dados privados ou ações de escrita | Você precisa executar ou conectar um provedor OAuth |
Com OAuth, o ChatGPT leva você para a página de login do seu provedor de identidade logo depois que você clica em Criar. Entre, clique em permitir, e você volta ao ChatGPT com o conector autorizado.
Qualquer que seja o provedor, peça as permissões mais restritas de que suas ferramentas precisam. Um conector que só lê pedidos nunca deveria ter permissão para reembolsá-los, porque as permissões que você concede são o teto do dano que uma chamada de ferramenta ruim pode causar.
Comece sem autenticação em um servidor de teste que devolva dados inofensivos. Passe para OAuth antes que o servidor toque em algo real.
Nos primeiros testes, cite o conector no seu prompt: "Usando Consulta de pedidos, liste meus pedidos em aberto." Citar o nome elimina uma variável. Quando a ferramenta funcionar, retire o nome e veja se o ChatGPT a escolhe sozinho, o que mostra se sua descrição está cumprindo o papel.
💡 Leia o cartão de confirmação. No modo desenvolvedor, cada chamada de ferramenta é mostrada a você antes de ser executada. Esse cartão é seu último ponto de controle, então passe os olhos pelos argumentos em vez de clicar sem olhar.
Uma ferramenta inofensiva é a forma mais rápida de provar que a conexão funciona antes de apontar o ChatGPT para dados reais. Esta conta palavras, usando o SDK oficial de Python:
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("hello-connector", stateless_http=True)
@mcp.tool()
def word_count(text: str) -> int:
"""Count the words in a block of text.
Use when the user asks how long a draft is."""
return len(text.split())
if __name__ == "__main__":
mcp.run(transport="streamable-http")
Quatro hábitos tornam uma ferramenta fácil de usar para um modelo:
lookup_order e refund_order são melhores do que uma única manage_order.Instale o SDK com pip install "mcp[cli]" e execute o arquivo. Com os padrões do SDK na data em que este texto foi escrito, o endpoint é http://127.0.0.1:8000/mcp. Se sua versão usar outra porta ou caminho, a documentação dela vai informar.
Antes que o ChatGPT veja o servidor, aponte o MCP Inspector para ele:
npx @modelcontextprotocol/inspector
Escolha o transporte Streamable HTTP, cole a URL local, conecte e liste as ferramentas. Se word_count aparecer e executar, o servidor está saudável e qualquer falha posterior pertence à rede ou ao formulário.
Um túnel dá à sua porta local um endereço HTTPS público:
ngrok http 8000
O cloudflared tunnel --url http://localhost:8000 da Cloudflare faz o mesmo trabalho. Copie o endereço HTTPS que ele exibir, adicione /mcp e cole isso no campo URL do servidor MCP.
💡 URLs de túnel gratuitas mudam. Reinicie o túnel e o endereço muda, o que quebra o conector. Recrie-o com a nova URL ou migre para um domínio fixo depois que o teste funcionar.
| Sintoma | Causa provável | Correção |
|---|---|---|
| O conector não é criado | URL é HTTP, local ou atrás de uma VPN | Use um endereço HTTPS público ou um túnel |
| Não encontrado ao conectar | Caminho errado ou ausente (/, /mcp, /sse) | Abra a URL exata no Inspector primeiro |
| Conecta, mas mostra zero ferramentas | A solicitação da lista de ferramentas dá erro | Leia os logs do servidor referentes à solicitação da lista |
| O login OAuth entra em loop | Endereço de redirecionamento não permitido pelo provedor | Adicione o endereço de callback que a página de configuração do provedor pede |
| As ferramentas nunca são chamadas | As descrições são vagas | Diga quando usar cada ferramenta e quando não usar |
| Funcionava ontem, falha hoje | O endereço do túnel mudou | Recrie o conector com a nova URL |
Depure nesta ordem e pare na primeira etapa que falhar. Primeiro, abra o Inspector e conecte-se à URL exata. Segundo, solicite essa URL a partir de um terminal com curl e confirme que ela responde por HTTPS. Terceiro, leia os logs do servidor enquanto clica em Criar. Só então suspeite do ChatGPT ou do formulário. Trabalhar do servidor para fora evita que você mexa em configurações que nunca estiveram quebradas.
Você mudou a lista de ferramentas, mas o ChatGPT ainda mostra a antiga. Abra as configurações do conector e use a opção de atualizar. Se isso não resolver, exclua o conector e adicione-o de novo, o que força uma nova leitura do servidor.
Mais um detalhe que vale saber: a documentação da OpenAI descreve uma ferramenta search que devolve resultados candidatos e uma ferramenta fetch que devolve um documento por ID, para recursos como a pesquisa aprofundada. Um servidor com apenas ferramentas personalizadas pode funcionar no modo desenvolvedor e, mesmo assim, ficar invisível para esses recursos.
O texto que seu servidor devolve se torna texto que o modelo lê. Um ticket de suporte, uma página da web ou um documento compartilhado pode trazer instruções ocultas destinadas a levar o modelo a chamar uma ferramenta que você nunca pretendeu. O aviso da própria OpenAI é direto: fique atento à injeção de prompt e revise cada chamada de ferramenta, especialmente as ações de escrita.
Construa com isso em mente:
Os conectores mais satisfatórios produzem algo que você pode ver. O PicassoIA oferece uma API para desenvolvedores em https://api.picassoia.com/v1, autenticada com um token bearer que começa com pia_sk_. Os endpoints seguem o estilo Replicate: um POST para /v1/models/{owner}/{name}/predictions inicia um job, e um GET em /v1/predictions/{id} consulta o resultado. Quatro modelos estão disponíveis pela API e pelo MCP:
Os jobs são assíncronos, então crie duas ferramentas em vez de uma: uma que inicia e devolve um ID de predição, e uma que verifica e devolve a saída quando o job termina. O ChatGPT pode chamar a verificação até o resultado estar pronto.
import os
import httpx
PIA = "https://api.picassoia.com/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['PICASSOIA_TOKEN']}"}
@mcp.tool()
def start_image(prompt: str) -> dict:
"""Start an image job. Returns an id to pass to get_result."""
r = httpx.post(
f"{PIA}/models/picassoia/picassoia-image/predictions",
headers=HEADERS, json={"input": {"prompt": prompt}}, timeout=30,
)
r.raise_for_status()
return {"id": r.json()["id"]}
@mcp.tool()
def get_result(prediction_id: str) -> dict:
"""Check a job. Returns status and, when finished, the output."""
r = httpx.get(f"{PIA}/predictions/{prediction_id}", headers=HEADERS, timeout=30)
r.raise_for_status()
data = r.json()
return {"status": data.get("status"), "output": data.get("output")}
Trate isto como um esboço. O corpo da solicitação segue a convenção do Replicate, então confirme os campos de entrada exatos na página do modelo antes de publicar.
Alguns limites moldam o design. Uma conta executa no máximo 5 predições ao mesmo tempo, e essa contagem é compartilhada entre tokens e conexões MCP. Os prompts chegam a 4.000 caracteres, e o corpo de uma única solicitação a 10 MB. Os termos de acesso e os preços ficam na página de preços do PicassoIA, então leia-os antes de prometer a alguém um plano gratuito.
💡 Prefere não hospedar nada? O PicassoIA também oferece conexões MCP hospedadas, gerenciadas em picassoia.com/en/mcp/accounts depois que você fizer login. Verifique quais clientes uma conexão suporta antes de confiar nela no ChatGPT.
As descrições das ferramentas importam mais do que o código por trás delas, porque o modelo escolhe as ferramentas lendo essas descrições. Um modelo de linguagem (LLM) pode aprimorar as suas em poucos minutos:
Para uma segunda opinião sobre a redação, cole o mesmo material no Claude Sonnet 5 e compare as duas reescritas. Fique com a descrição que for mais curta e mais específica.
Crie primeiro o contador de palavras e acompanhe essa primeira chamada de ferramenta aparecer em um chat. Depois, dê ao conector algo para mostrar. Adicione o iniciador de imagem, peça ao ChatGPT uma foto de uma cena comum e mude um detalhe por pedido: a lente, a luz, a hora do dia. Pequenas edições ensinam mais sobre prompts do que qualquer descrição longa.
Quando quiser imagens finalizadas sem escrever um servidor, abra o PicassoIA e experimente criar suas próprias imagens com PicassoIA Image, refiná-las com o PicassoIA Image Editor Pro e dar vida a uma favorita com o PicassoIA Video. Escolha um prompt, execute-o de três maneiras e fique com a versão que chama mais atenção.
Escolha seu idioma
