Como construir um servidor MCP (Passo a passo)
.webp)
Built for Speed: ~10ms Latency, Even Under Load
Blazingly fast way to build, track and deploy your models!
- Handles 350+ RPS on just 1 vCPU — no tuning needed
- Production-ready with full enterprise support
O Model Context Protocol oferece a um LLM uma maneira padronizada de chamar ferramentas, ler contexto e reutilizar prompts em qualquer cliente compatível. Construir um servidor que fale esse protocolo não é difícil; construir um que seja correto, seguro para expor e agradável para um modelo usar exige mais algumas decisões do que os tutoriais rápidos cobrem. Este guia percorre o caminho completo: o que um servidor expõe, qual transporte escolher e por quê, como definir uma ferramenta que o modelo realmente usará bem, como autenticar um servidor remoto, como testá-lo e o que muda quando você passa do seu laptop para a produção.
Os exemplos práticos são pseudocódigo estrutural em um estilo similar ao Python. Eles mostram o formato correto (nomes, esquemas, assinaturas de manipuladores) sem prender você a uma versão específica do SDK, porque a estrutura é o que se transfere. Se você quiser primeiro o embasamento conceitual, o que é um servidor MCP cobre o modelo; este post é a construção.
Construiu um servidor MCP? Coloque-o atrás de um gateway para autenticação, registro e auditoria. Agende uma demonstração.
O que um servidor MCP expõe
Um servidor MCP oferece três tipos de capacidades a um cliente. Acertar essa distinção na fase de design evita o erro mais comum, que é socar tudo dentro de ferramentas.

Ferramentas (Tools) são funções invocadas pelo modelo. O modelo decide, durante uma conversa, chamar uma ferramenta para realizar algo: consultar um banco de dados, criar um chamado, enviar uma requisição para uma API interna. Ferramentas podem ter efeitos colaterais. Elas são a primitiva que você usa quando o modelo precisa agir. Uma ferramenta possui um nome, uma descrição e um JSON Schema para suas entradas, e retorna conteúdo estruturado.
Recursos (Resources) são contextos somente leitura, controlados pela aplicação e identificados por um URI. Um recurso é um dado que o cliente pode ler e entregar ao modelo como contexto: um arquivo, um documento de configuração, o conteúdo atual de um registro. A principal diferença em relação a uma ferramenta é o controle e a intenção. Um recurso é somente leitura e normalmente é selecionado pela aplicação ou pelo usuário ("anexe este documento"), não invocado pelo modelo no meio do raciocínio para causar um efeito. Se o item que você está expondo nunca altera o estado e é apenas "aqui está um contexto para leitura", trata-se de um recurso, não de uma ferramenta.
Prompts são modelos invocados pelo usuário. Um prompt é uma mensagem reutilizável e parametrizada (ou sequência de mensagens) que o usuário aciona explicitamente, frequentemente exibida no cliente como um comando com barra (slash command) ou um item de menu. "Resuma este PR no nosso estilo interno" com um parâmetro pr_url é um prompt. Prompts são controlados pelo usuário, não escolhidos autonomamente pelo modelo.
Uma regra prática: se o modelo deve decidir quando usar, construa uma ferramenta. Se o usuário ou o app decide qual contexto carregar, construa um recurso. Se o usuário deseja uma instrução pronta e repetível, construa um prompt. A maioria dos servidores lança legitimamente apenas ferramentas, mas um servidor que expõe, por exemplo, seus manuais operacionais internos é melhor modelado com recursos do que com uma ferramenta get_runbook que o modelo precisa adivinhar como chamar.
Escolha um transporte
O protocolo define como o cliente e o servidor trocam mensagens JSON-RPC. Dois transportes são relevantes, e essa escolha direciona quase tudo sobre como você faz o deployment.
stdio local executa o servidor como um subprocesso do cliente e troca mensagens por meio da entrada e saída padrão (standard input/output). É a escolha certa para desenvolvimento e para clientes desktop, como uma IDE ou um assistente local, onde o servidor roda na mesma máquina do usuário. Não há rede, nem autenticação para configurar, e o cliente gerencia o ciclo de vida do processo. Para executar servidores locais especificamente dentro de um cliente de código, veja servidores MCP no Claude Code. A limitação é óbvia: o stdio atende exatamente a um usuário local e não pode ser compartilhado, ter carga balanceada ou ser acessado por uma rede.
Streamable HTTP remoto executa o servidor como um serviço de rede que os clientes acessam via HTTP, com streaming do servidor para o cliente para notificações e progresso. Este é o transporte para qualquer cenário multiusuário, hospedado ou em produção. A revisão do protocolo de 28-07-2026 é importante aqui: o Streamable HTTP suporta um modo stateless, onde o servidor não precisa prender o cliente a uma sessão de longa duração em uma única instância. A operação stateless é o que permite executar várias réplicas idênticas atrás de um balanceador de carga e escalar horizontalmente sem sessões pegajosas (sticky sessions), que é a propriedade mais importante para hospedagem em produção. A mesma revisão padronizou os cabeçalhos Mcp-Method e Mcp-Name nas requisições, expondo o método JSON-RPC e o nome da ferramenta ou recurso na camada HTTP. Isso parece pequeno, mas não é. Significa que um gateway, proxy ou balanceador de carga pode rotear, aplicar rate limit, autorizar e registrar logs por ferramenta sem precisar analisar o corpo do JSON-RPC, que é exatamente o que você precisa para governar um servidor em escala.

Construa e depure em stdio; lance em Streamable HTTP. Escrever seu servidor de forma que o transporte seja apenas uma camada externa fina (manipuladores que não se importam com a forma como foram acessados) permite alternar entre eles sem reescrever a lógica.
Defina uma ferramenta que o modelo realmente usará
A definição de uma ferramenta possui três partes, e o comportamento do modelo é governado por todas elas. É aqui que a maioria dos problemas de "meu servidor não funciona" realmente se origina.
# Structural pseudocode — shape, not a specific SDK version.
@server.tool()
def search_orders(
customer_id: str, # required
status: str = "any", # enum: open | shipped | cancelled | any
limit: int = 20, # 1..100
) -> list[Order]:
"""Search a customer's orders by status.
Use this when the user asks about the state, history, or
contents of orders for a known customer_id. Returns up to
`limit` orders, newest first. Does NOT create or modify
orders. If the customer_id is unknown, ask the user for it
rather than guessing.
"""
...
As três partes:
Nome. Curto, iniciado por um verbo, inequívoco. search_orders, em vez de orders ou do_order_stuff. O modelo lê o nome primeiro ao decidir entre dezenas de ferramentas disponíveis.
Descrição. Este é o texto mais importante que você escreverá, e trata-se de engenharia de prompt, não de documentação. O modelo decide se deve chamar a ferramenta e como preencher seus argumentos quase inteiramente com base na descrição. Declare o que a ferramenta faz, quando usá-la, quando não usá-la, o que ela retorna e como lidar com entradas ausentes. O exemplo acima informa ao modelo que a operação é somente leitura ("NÃO cria ou modifica") e fornece um comportamento de contingência ("pergunte ao usuário em vez de adivinhar"). Descrições vagas geram um modelo que chama a ferramenta errada, chama a ferramenta certa com argumentos errados ou a invoca quando não deveria. Trate cada descrição como um mini prompt do sistema.
Esquema de entrada (Input schema). Um JSON Schema preciso. Marque os campos obrigatórios como necessários. Use enums para conjuntos fechados (onde status é um de quatro valores) para que o modelo não invente "in_progress". Defina limites (limit entre 1 e 100). Forneça uma descrição para cada campo. Um esquema rigoroso restringe o modelo e permite que o servidor, ou um gateway à frente dele, valide as entradas antes que qualquer manipulador seja executado.
Duas armadilhas comuns que afetam a todos:
- Idempotência para retransmissões. Chamadas remotas passam por retentativas — por clientes, por redes e por qualquer gateway executando fallback. Uma ferramenta com efeitos colaterais (
create_refund) deve tolerar ser chamada duas vezes com as mesmas entradas sem duplicar o efeito. Aceite uma chave de idempotência ou torne a operação naturalmente idempotente. Projete para entrega pelo menos uma vez (at-least-once), pois é isso que você receberá na prática. - Manipulação de credenciais e segredos. O servidor — e não o modelo nem o cliente — mantém as credenciais dos sistemas com os quais se comunica. Nunca retorne segredos no resultado de uma ferramenta, nunca os coloque em um recurso e nunca espere que o modelo os passe como argumentos. Carregue-os a partir do ambiente do servidor ou de um cofre de segredos, com escopo restrito ao processo do servidor.
Autentique um servidor remoto
Um servidor stdio local herda a confiança da máquina do usuário e não precisa de autenticação. No momento em que você expõe um servidor via HTTP, ele precisa de autenticação real, e o protocolo é específico sobre o que "real" significa.
O modelo de autorização do MCP baseia-se no OAuth 2.1. Duas partes são particularmente importantes. Primeiro, o servidor é um recurso protegido por OAuth: os clientes obtêm um token de acesso de um servidor de autorização e o apresentam como um bearer token. Segundo, e fácil de ignorar, a especificação exige indicadores de recurso (RFC 8707) para que o token fique vinculado ao servidor MCP específico para o qual foi emitido (o recurso), em vez de ser um token de uso geral. Sem indicadores de recurso, um token gerado para o servidor A pode ser reutilizado contra o servidor B que confia no mesmo servidor de autorização — um problema do tipo confused-deputy. Com eles, o servidor de autorização emite um token com escopo para o recurso pretendido, e cada servidor rejeita tokens que não foram destinados a ele.
Na prática, você não precisa implementar isso do zero. Você coloca o servidor atrás de algo que finalize o OAuth corretamente e valide a audiência de cada token. Esse é um dos papéis de um gateway MCP. Os mecanismos mais profundos, validação de token, escopos e a falha do confused-deputy, são abordados em autenticação MCP. A regra para este guia: um servidor MCP remoto protegido por uma chave de API estática compartilhada não está autenticado, está apenas ofuscado. Use OAuth 2.1 com tokens vinculados à audiência.

Veja como o TrueFoundry hospeda e governa seus servidores MCP remotos. Agende uma demonstração.
Teste o servidor com um cliente real
Antes de expor qualquer coisa, exercite o servidor por meio de um cliente MCP e observe a troca real de mensagens.
- Lister capacidades. Conecte um cliente e confirme se o servidor anuncia as ferramentas, recursos e prompts esperados, com os nomes e esquemas pretendidos. Um número surpreendente de bugs é do tipo "a ferramenta foi registrada com o nome errado" ou "o esquema não serializou o enum".
- Invocar cada ferramenta com entradas válidas e inválidas. Chame todas as ferramentas com argumentos válidos, depois com campos obrigatórios ausentes, valores fora do intervalo e tipos incorretos. Confirme se o servidor rejeita entradas ruins com um erro claro, em vez de falhar bruscamente (crash) ou fazer a coisa errada silenciosamente. Se você definiu limites no esquema, confirme se estão sendo aplicados.
- Deixar um modelo operá-lo. O teste real é se um modelo, recebendo apenas seus nomes, descrições e esquemas, chama a ferramenta certa com os argumentos corretos para uma requisição realista. Observe se o modelo escolhe a ferramenta errada, alucina um valor de argumento ou deixa de solicitar um campo obrigatório ausente. Cada um desses problemas costuma ser resolvido com ajustes na descrição ou no esquema, e não no código.
- Exercitar o caminho de streaming. Para Streamable HTTP, confirme se as notificações de progresso e os resultados transmitidos chegam de forma incremental, e não acumulados até o final.
- Forçar falhas. Faça uma dependência upstream sofrer timeout ou retornar erro, e confirme se a ferramenta retorna um erro estruturado sobre o qual o modelo possa raciocinar, em vez de um erro 500 opaco.
O teste guiado por modelo na etapa 3 é o que as equipes costumam pular, mas é o mais importante. Um servidor tecnicamente correto, mas com ferramentas mal descritas, falhará exatamente da forma mais difícil de depurar pelos logs: o modelo simplesmente o usará de forma errada.
De um servidor funcional para a produção
Um servidor que roda no seu laptop via stdio e um servidor seguro para receber tráfego real são artefatos diferentes. Aqui está o que preenche essa lacuna.
Hospedagem e ciclo de vida. O servidor passa a ser um serviço que você faz deployment, monitora, atualiza e faz rollback. Ele precisa de health checks, limites de recursos e um destino de deployment. Hospedagem de servidor MCP cobre as opções e compensações.
Escalabilidade stateless. Para executar múltiplas réplicas atrás de um balanceador de carga, mantenha o servidor stateless por requisição, que é exatamente o objetivo do modo stateless Streamable HTTP da revisão de 28-07-2026. Qualquer estado de sessão deve residir em um armazenamento compartilhado, e não na memória da instância; caso contrário, a requisição seguinte de um cliente roteada para uma réplica diferente falhará.
Autenticação e autorização. OAuth 2.1 com indicadores de recurso para autenticação, seguido pela autorização: quais usuários e quais agentes podem chamar quais ferramentas. Trate o agente como uma identidade de primeira classe, não apenas o humano por trás dele; identidade de agente de IA e autorização granular por ferramenta são o que evitam que um servidor capaz se torne um risco de segurança.
Descoberta via registro. Clientes e equipes de plataforma precisam encontrar o servidor, saber qual é a versão dele e o que ele expõe. Um registro é o catálogo que torna os servidores descobríveis e governáveis em toda a organização; veja o que é um registro MCP. Sem ele, cada equipe redescobre e reconfigura os mesmos servidores manualmente.
Observabilidade. Você precisa de visibilidade por chamada: quem chamou qual ferramenta, com quais argumentos, quanto tempo levou, se gerou erro e quanto custou. Servidores puros não emitem nada disso de forma padronizada.
Guardrails. As entradas e saídas das ferramentas podem carregar PII, segredos ou payloads de injeção de prompt ocultos no conteúdo retornado. Inspecioná-los é uma preocupação transversal que você não deseja reinterpretar e reescrever em cada servidor.
O padrão que torna isso viável é não reconstruir essa camada para cada servidor. Construa seu servidor para realizar muito bem a sua função sobre Streamable HTTP e posicione-o atrás de um gateway MCP que forneça autenticação, autorização, registro, observabilidade e guardrails de forma unificada. Essa é a diferença entre expor um servidor isolado e operar uma frota deles. O que é um gateway MCP apresenta esse modelo, e governança corporativa de MCP cobre os requisitos de controle, auditoria e acesso associados. A TrueFoundry oferece essa solução como um gateway e registro MCP com controle de acesso (RBAC, SSO, SCIM) e guardrails, implantável em SaaS, in-VPC, on-premise ou em ambientes isolados (air-gapped), mantendo o plano de dados dentro da sua rede.
Onde as equipes erram
Transformam tudo em ferramenta. Contexto de somente leitura é forçado em ferramentas get_* que o modelo precisa adivinhar como chamar, quando deveria ser um recurso anexado pela aplicação. Instruções prontas e repetitivas são codificadas diretamente, quando deveriam ser prompts invocados pelo usuário. Modele as três primitivas deliberadamente.
Escrevem descrições superficiais de ferramentas. Uma descrição de uma linha deixa o modelo adivinhando quando e como chamar a ferramenta, e ele adivinhará errado. A descrição governa o comportamento; escreva-a como um prompt de sistema, incluindo quando não usar a ferramenta.
Lançam um servidor remoto protegido por chave compartilhada. Uma chave de API estática não é autenticação. Servidores remotos precisam de OAuth 2.1 com tokens vinculados à audiência (indicadores de recurso) para que um token emitido para um servidor não possa ser reutilizado em outro. Ignorar isso cria uma brecha de confused-deputy.
Ignoram a idempotência. Clientes, redes e mecanismos de fallback de gateways realizam retentativas. Uma ferramenta com efeito colateral que não seja idempotente coborá em dobro, criará registros duplicados ou enviará dados duas vezes sob condições perfeitamente normais de retransmissão. Projete para entrega pelo menos uma vez (at-least-once).
Tratam "está rodando" como "está em produção". Um servidor funcional é apenas o começo. Hospedagem, escalabilidade stateless, autenticação, registro, observabilidade e guardrails são o trabalho real para torná-lo seguro para exposição — e reconstruir isso por servidor é a razão pela qual as organizações terminam com dezenas de endpoints sem governança.
Conclusão
Construir um servidor MCP é uma caminhada curta com uma longa jornada depois. A caminhada é o início rápido: escolha um transporte, registre uma ferramenta com nome, descrição e esquema, e teste com um cliente. Você pode ter um servidor funcional em uma tarde. A jornada é tudo o que o torna correto e seguro: modelar ferramentas versus recursos versus prompts com intencionalidade, escrever descrições sobre as quais o modelo possa agir, tornar idempotentes as ferramentas com efeitos colaterais, autenticar o acesso remoto com OAuth 2.1 e indicadores de recurso, e escalar de forma stateless.
A etapa que a maioria das equipes subestima é a transição de "roda no meu laptop" para "exposto ao tráfego real". Essa transição envolve hospedagem, autenticação, autorização, descoberta, observabilidade e guardrails — e a grande vantagem está em não reconstruir essa camada a cada novo servidor. Construa o servidor para fazer seu trabalho via Streamable HTTP, coloque-o atrás de um gateway e registro MCP para obter governança, e você terá algo que pode realmente operar, em vez de um endpoint isolado que ninguém consegue proteger ou encontrar.
Leve seu servidor MCP do ambiente local para uma produção governada. Agende uma demonstração.
TrueFoundry AI Gateway delivers ~3–4 ms latency, handles 350+ RPS on 1 vCPU, scales horizontally with ease, and is production-ready, while LiteLLM suffers from high latency, struggles beyond moderate RPS, lacks built-in scaling, and is best for light or prototype workloads.














.webp)







