Pular para o conteúdo
Kitbay

Como criar um servidor MCP

Pela equipe editorial do Kitbay ·

Para criar um servidor MCP, escolha um dos SDKs oficiais do MCP, defina as tools (ferramentas) que o servidor oferece (e, se quiser, resources e prompts), rode-o via stdio para uso local ou via Streamable HTTP para uso remoto e teste com o MCP Inspector antes de conectá-lo a um cliente de IA. Um servidor simples, só com tools, cabe em poucas dezenas de linhas de código.

Este guia segue a documentação oficial do MCP, cujo tutorial cria um pequeno servidor de previsão do tempo. Se os termos forem novos para você, comece por o que é um servidor MCP.

Passo 1: escolha um SDK

O projeto MCP mantém SDKs oficiais e os classifica em níveis, de acordo com a cobertura de recursos e a manutenção:

Nível Linguagens
Tier 1 TypeScript, Python, C#, Go, Rust, Ruby
Tier 2 Java
Tier 3 Swift, PHP, Kotlin

Todos os SDKs conseguem expor tools, resources e prompts e suportam transportes locais e remotos. Cada SDK adota as novas versões do protocolo no seu próprio ritmo, então confira qual revisão o seu suporta. A revisão atual da especificação é de 28 de julho de 2026 e torna o protocolo stateless: cada requisição traz as próprias informações de versão e de recursos. Os SDKs cuidam disso para você.

Passo 2: defina o que o servidor oferece

Os servidores MCP oferecem três tipos de blocos:

Bloco Quem controla Para que serve
Tools (ferramentas) O modelo decide quando chamá-las Ações e consultas: criar uma issue, buscar registros, converter um arquivo
Resources (recursos) A aplicação decide o que incluir Contexto somente leitura: um arquivo, o schema de um banco de dados, a documentação de uma API
Prompts O usuário escolhe Modelos reutilizáveis, muitas vezes exibidos como comandos de barra (/)

A maioria dos servidores começa pelas tools. Para cada uma, escreva um nome claro, uma descrição que diga ao modelo quando usá-la e um schema de entrada. A documentação do MCP sugere nomes específicos, como calculator_arithmetic, em vez de um simples calculate. Faça cada tool executar uma única operação e decida desde o início quais tools só leem e quais podem alterar dados, porque usuários e clientes vão querer saber.

Passo 3: escreva o servidor

A versão em Python do tutorial oficial instala o SDK com uv add "mcp[cli]", e o código fica mais ou menos assim:

from mcp.server import MCPServer

mcp = MCPServer("weather")

@mcp.tool()
async def get_forecast(latitude: float, longitude: float) -> str:
    """Get the weather forecast for a location.

    Args:
        latitude: Latitude of the location
        longitude: Longitude of the location
    """
    # call the weather service's API here and return readable text
    ...

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

O SDK lê as type hints e a docstring para montar o nome, a descrição e o schema de entrada da tool. O tutorial em TypeScript usa o pacote @modelcontextprotocol/server com zod para os schemas, cria um McpServer e adiciona tools com registerTool. As outras linguagens seguem as próprias convenções; o tutorial também traz versões em Java, Kotlin e C#.

Logs: mantenha a saída padrão limpa

Esse é o erro mais comum no começo. Com stdio, o cliente e o servidor trocam mensagens JSON-RPC pela saída padrão, então qualquer texto extra impresso ali quebra a conexão. Em Python, evite print(); em Node, evite console.log(). Grave os logs na saída de erro padrão, por exemplo com o módulo logging do Python ou com console.error().

Passo 4: escolha um transporte

A especificação define dois transportes padrão:

  • stdio. O cliente inicia o servidor como um subprocesso e troca mensagens separadas por quebra de linha pela entrada e pela saída padrão dele. Use para servidores que rodam no computador do usuário. As orientações de segurança do MCP recomendam stdio para servidores locais, porque ele limita o acesso ao cliente que iniciou o servidor.
  • Streamable HTTP. O servidor roda como um processo independente, com um único endpoint, como https://example.com/mcp, que aceita requisições POST. Cada resposta é um objeto JSON ou um stream curto de Server-Sent Events. Use para servidores hospedados aos quais muitos usuários se conectam por URL.

O transporte HTTP+SSE mais antigo, de 2024, está obsoleto; servidores novos não devem usá-lo.

Se você escolher Streamable HTTP, a especificação traz requisitos de segurança: valide o cabeçalho Origin em toda requisição para bloquear DNS rebinding, faça o bind em 127.0.0.1 em vez de todas as interfaces quando rodar localmente e autentique as conexões. A documentação do MCP recomenda OAuth para obter tokens, e um servidor precisa rejeitar tokens que não foram emitidos para ele.

Passo 5: teste com o MCP Inspector

O MCP Inspector é a ferramenta de referência do projeto para testar servidores. Ele exige Node 22.19.0 ou mais recente e roda via npx, sem instalação:

# browser interface, connected to a local stdio server
npx @modelcontextprotocol/inspector uv --directory /path/to/weather run weather.py

# scriptable command line: list tools and exit
npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list

# a remote server
npx @modelcontextprotocol/inspector --server-url https://example.com/mcp --transport http

Ele tem três modos: uma interface web, uma CLI para scripts e CI e uma interface de terminal (--tui). Use-o para conferir se cada tool aparece com o schema certo, se as chamadas retornam o esperado e se os erros são claros. Atenção: ele guarda segredos no chaveiro do sistema quando existe um; sem chaveiro, eles vão para um arquivo sem criptografia, a menos que você defina uma chave.

Passo 6: conecte a um cliente

Para um servidor local, adicione o comando de inicialização a um cliente. No Claude Desktop, o tutorial adiciona este trecho ao claude_desktop_config.json:

{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": ["--directory", "/ABSOLUTE/PATH/TO/weather", "run", "weather.py"]
    }
  }
}

Use caminhos absolutos e, se o cliente não encontrar o uv, informe o caminho completo dele. No Claude Code, o equivalente é claude mcp add --transport stdio weather -- uv --directory /ABSOLUTE/PATH/TO/weather run weather.py. Para outros clientes, veja como conectar servidores MCP a clientes de IA.

Antes de publicar

  • Documente cada tool. Diga quais tools leem e quais alteram dados, e quais credenciais o servidor precisa.
  • Peça o mínimo de acesso. Solicite escopos de API restritos e evite tokens amplos, de "acesso total".
  • Trate as entradas como não confiáveis. Os argumentos das tools vêm de um modelo que pode ter lido conteúdo malicioso.
  • Mostre os comandos de instalação completos. Os usuários devem ver exatamente o que vai rodar na máquina deles.
  • Escolha uma licença e diga se o servidor é mantido.

Uma observação sobre segurança

Servidores agem sobre dados reais. Durante o desenvolvimento, aponte o seu para contas de teste e arquivos de exemplo, não para sistemas em uso, e leia as orientações de segurança do projeto MCP sobre o tratamento de tokens e servidores locais. Nossas perguntas sobre segurança no MCP mostram o que usuários cuidadosos vão conferir.

Veja também

Ferramentas para desenvolvedores ficam nas áreas de testes e depuração do Kitbay, e você pode explorar os servidores MCP existentes para ver como outras pessoas documentam suas tools. Se o objetivo for mais ensinar um procedimento a um agente do que conectar um sistema, uma skill pode ser mais adequada: veja MCP vs. skills.

Perguntas

Qual linguagem devo usar para criar um servidor MCP?
Qualquer linguagem com SDK oficial. O projeto MCP classifica TypeScript, Python, C#, Go, Rust e Ruby como Tier 1, Java como Tier 2, e Swift, PHP e Kotlin como Tier 3.
Como testo um servidor MCP?
Use o MCP Inspector, a ferramenta de testes do próprio projeto. Execute npx @modelcontextprotocol/inspector seguido do comando que inicia o seu servidor e depois liste e chame as tools no navegador, no terminal ou na CLI.
Por que meu servidor MCP stdio quebra quando imprimo mensagens de debug?
Com o transporte stdio, a saída padrão carrega as mensagens do protocolo, então qualquer outra coisa impressa ali as corrompe. Envie os logs para a saída de erro padrão.
Preciso hospedar um servidor MCP na internet?
Não. Um servidor local que usa stdio roda no computador do usuário e é iniciado pelo cliente de IA dele. Hospede na internet com Streamable HTTP só se os usuários precisarem se conectar por URL.

Fontes

Mais guias