Blank white background with no objects or features visible.

Olá, EMEA! A TrueFoundry está expandindo sua presença pela Europa, Oriente Médio e África. Leia mais. →

Como construir um servidor MCP (Passo a passo)

Published: novembro 20, 2026

TL;DR
  • Um servidor MCP expõe três primitivas: ferramentas (ações invocadas pelo modelo com efeitos colaterais), recursos (contexto de leitura e identificável) e prompts (modelos reutilizáveis invocados pelo usuário). A maioria dos servidores que as pessoas constroem são na verdade apenas ferramentas; saiba quando você realmente precisa de um recurso ou de um prompt.
  • O transporte é a primeira decisão real. stdio local é correto para desenvolvimento e clientes desktop; Streamable HTTP remoto é correto para qualquer coisa multiusuário ou em produção. A partir da revisão de 28-07-2026, o Streamable HTTP suporta um modo stateless e carrega os cabeçalhos Mcp-Method e Mcp-Name, tornando muito mais fácil colocá-lo atrás de um gateway e de um balanceador de carga.
  • A qualidade da ferramenta é um problema de engenharia de prompt, não apenas de API. O modelo decide se e como chamar sua ferramenta com base em seu nome, descrição e esquema de entrada. Uma descrição vaga é o motivo mais comum para um servidor correto se comportar mal.
  • Servidores remotos precisam de autenticação real. A especificação aponta para OAuth 2.1 com indicadores de recurso (RFC 8707) para que um token gerado para um servidor não possa ser reutilizado contra outro. Não lance em produção um servidor remoto protegido por uma chave estática compartilhada.
  • A exposição direta não é produção. Um servidor funcional é o primeiro passo. Hospedagem, escalabilidade stateless, autenticação, um registro para que os clientes possam descobri-lo, observabilidade e guardrails são o que o torna seguro para exposição — e essa camada é o que um gateway MCP fornece, em vez de algo que você recria por servidor.

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.

The anatomy of an MCP server: tools, resources, and prompts on the server side, and the client-to-server message flow that lists and invokes them.
A anatomia de um servidor MCP: ferramentas, recursos e prompts no lado do servidor, e o fluxo de mensagens cliente-servidor que os lista e invoca.

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.

PrimitivaQuem controla a invocaçãoEfeitos colateraisUso típico
FerramentaO modelo, autonomamente, no meio da conversaSim, permitidosConsultar uma API, gravar em um banco de dados, criar um chamado, executar um cálculo
RecursoA aplicação ou o usuário selecionaNão, somente leituraAnexar um arquivo, um registro ou um documento de configuração como contexto
PromptO usuário invoca explicitamenteAtravés das ferramentas que disparaUma instrução em modelo reutilizável, frequentemente um comando com barra

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.

The dev-to-production path: a local stdio server during development, promoted to a remote Streamable HTTP service, then placed behind an MCP gateway for authentication, registry, and observability.
O caminho do desenvolvimento à produção: um servidor stdio local durante o desenvolvimento, promovido a um serviço Streamable HTTP remoto e, em seguida, posicionado atrás de um gateway MCP para autenticação, registro e observabilidade.
Consideraçãostdio localStreamable HTTP remoto
Onde executaSubprocesso na máquina do usuárioServiço de rede, hospedado
Usuários atendidosUm, localMuitos, concorrentes
AutenticaçãoNenhuma (confiança local)Obrigatória: OAuth 2.1 com indicadores de recurso
EscalabilidadeNão se aplicaHorizontal, modo stateless evita sticky sessions
Ciclo de vidaO cliente inicia e encerra o processoVocê o opera como qualquer outro serviço
Roteamento/GovernançaN/ACabeçalhos Mcp-Method / Mcp-Name permitem roteamento e limites por ferramenta
Ideal paraDesenvolvimento, clientes desktop/IDEProdução, servidores compartilhados e multiusuário

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.

The TrueFoundry MCP Gateway architecture. Source: TrueFoundry docs.
A arquitetura do TrueFoundry MCP Gateway. Fonte: documentação do TrueFoundry.

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.

  1. 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".
  2. 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.
  3. 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.
  4. 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.
  5. 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.

Try now.

One gateway for all your models, MCP servers, and agents. No credit card needed.

Start free
Table of Contents

One Gateway for Every LLM, Agent and MCP Server

Book a 30-min with our AI expert

Book a Demo

The fastest way to build, govern and scale your AI

Book Demo
Summarize with
ChatGPT logo by OpenAI
Perplexity AI logo
Blurry red snowflake on white background, symmetrical frosty design with soft edges and abstract shape.

Discover More

No items found.
novembro 20, 2026
|
5 min read

Grok 4.3 no Amazon Bedrock: Roteamos Quatro Modelos de Fronteira por um Único Gateway e Medimos o Custo

Ferramentas de LLM
comparação
novembro 20, 2026
|
5 min read

GPT-6.1 Terra: API, Benchmarks, Preço & Como Usar

No items found.
TrueFoundry AI gateway is an enterprise alternative to Bifrost and Portkey
novembro 20, 2026
|
5 min read

Bifrost vs Portkey: Precificação, Recursos de Gateway e Adequação Enterprise Comparados

No items found.
novembro 20, 2026
|
5 min read

Evolução do Machine Learning: Um Mergulho Profundo na Jornada de Savin

True ML Talks
No items found.
Take a quick product tour
Start Product Tour
Product Tour