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
- Build an MCP server (MCP docs)conferido em 14 de nov. de 2026
- SDKs (MCP docs)conferido em 14 de nov. de 2026
- Understanding MCP servers (MCP docs)conferido em 14 de nov. de 2026
- MCP architecture overviewconferido em 14 de nov. de 2026
- Transports (MCP specification)conferido em 14 de nov. de 2026
- Streamable HTTP (MCP specification)conferido em 14 de nov. de 2026
- MCP Inspector (MCP docs)conferido em 14 de nov. de 2026
- Security considerations (MCP docs)conferido em 14 de nov. de 2026
Mais guias
- Como conectar servidores MCP ao Claude, ao ChatGPT e ao Cursor
- Como criar skills personalizadas para o Claude Code
- Segurança no MCP: perguntas para fazer antes de instalar um servidor ou uma skill
- MCP vs. API: qual é a diferença?
- MCP vs. skills: a diferença entre servidores MCP e skills de agente
- O que é uma skill do Claude?
- O que é um servidor MCP?