Conectando um MCP server customizado ao Claude e ao ChatGPT

A fonte deste TIL do Simon Willison é curta: ele registra que "conectar um MCP server customizado às interfaces padrão de chat do Claude e do ChatGPT é possível, mas pode exigir vários passos" e que "não é óbvio como configurar". Isso é honesto, mas rende pouco por si só. Como o assunto é útil para quem constrói ferramentas próprias, vou preencher a lacuna com o que é conhecimento estabelecido sobre MCP, deixando claro onde estou indo além da fonte.

O que é MCP, em uma frase

O Model Context Protocol (MCP) é um protocolo aberto que padroniza como modelos de linguagem descobrem e chamam ferramentas externas: suas APIs, bancos, scripts. Em vez de escrever um plugin específico para cada assistente, você expõe um server MCP e qualquer cliente compatível (Claude, ChatGPT e outros) consome as mesmas ferramentas.

Para o dev brasileiro, o ponto prático é esse: um único server MCP na frente da sua API interna já serve os dois assistentes, sem código duplicado.

O ponto de atrito que a fonte destaca

O recado do Simon é o que mais importa aqui: as UIs de chat do Claude e do ChatGPT conseguem acessar servidores MCP, mas a configuração não é intuitiva e envolve mais etapas do que se imagina. Isso bate com a realidade de quem já tentou. Os assistentes evoluíram do MCP local (via stdio, rodando na sua máquina através de apps de desktop) para conectores remotos expostos por HTTP, e é aí que mora a confusão.

Uma distinção que vale fixar antes de qualquer tentativa:

• MCP local (stdio): o server roda no seu computador e o cliente o inicia como subprocesso. Comum em configurações de desktop.
• MCP remoto (HTTP): o server fica acessível por uma URL pública, normalmente com autenticação. É esse modelo que as interfaces web usam para conectores customizados.

A maioria dos tropeços que vejo relatados cai em uma destas categorias: usar transporte errado para o contexto, esquecer autenticação no endpoint remoto, ou expor o server em localhost esperando que a interface web o alcance (ela não alcança).

Um esqueleto de server para testar

Antes de brigar com a UI, vale ter um server mínimo funcionando. Primeiro instale o SDK oficial de Python:

pip install mcp
# ou, se você usa uv:
uv add mcp

Depois, o server:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("meu-server")

@mcp.tool()
def consultar_pedido(pedido_id: str) -> str:
    """Retorna o status de um pedido pelo ID."""
    # aqui voce chamaria sua API interna de verdade
    return f"Pedido {pedido_id}: em separacao"

if __name__ == "__main__":
    mcp.run()

Atenção a este ponto, porque foi onde eu perdi tempo: mcp.run() sem argumentos usa o transporte stdio por padrão. Ele não abre porta nenhuma. Se você rodar esse script e mandar um ngrok http 8000 em seguida, não há nada escutando na 8000 e a URL gerada não leva a lugar algum.

Para expor via HTTP e alcançar as interfaces web, é preciso trocar o transporte:

if __name__ == "__main__":
    # streamable-http sobe um servidor HTTP; ajuste host/porta conforme sua versao do SDK
    mcp.settings.host = "0.0.0.0"
    mcp.settings.port = 8000
    mcp.run(transport="streamable-http")

Agora sim, com o server escutando na 8000, um túnel dá a URL pública em desenvolvimento:

ngrok http 8000

A URL https://... gerada é o que você cola no conector do assistente. Sem HTTPS e sem endpoint alcançável de fora, a UI simplesmente não conecta, e a mensagem de erro raramente é clara sobre isso.

Onde eu bati a cabeça (e o que checar)

Alguns pontos que economizam tempo, na linha do que o próprio Simon aponta sobre "vários passos":

• Transporte é o erro nº 1. Como mostrei acima, stdio serve clientes de desktop; HTTP serve as UIs web. Confundir os dois quebra o fluxo remoto inteiro.
• Autenticação, na prática, é obrigatória. Um server remoto sem auth é um convite aberto à sua API. Os fluxos costumam esperar OAuth ou ao menos um token, e a interface pode recusar servers sem ele.
• Cada assistente tem seu lugar de configuração. No Claude, conectores ficam em configurações da conta/workspace; no ChatGPT, o suporte a MCP customizado passa por recursos que podem depender do seu plano. Confira disponibilidade antes de assumir que o botão existe.
• Descrições de ferramenta importam. O modelo decide quando chamar sua tool lendo a docstring. Descrição vaga vira ferramenta ignorada.

Vale a pena?

Para automatizar suas próprias APIs e ferramentas dentro do chat que o time já usa, sim. O ganho é ter uma camada única de integração servindo múltiplos assistentes. O custo, como a fonte resume bem, é a configuração inicial pouco óbvia. Comece com um server local em stdio trivial, valide que a ferramenta é chamada, troque para streamable-http e só então parta para o deploy remoto com autenticação. Documentação de referência: modelcontextprotocol.io.

Fonte: Simon Willison