Crie seu primeiro MCP Server funcional — uma tool simples que retorna "Olá, mundo!" e conecte ao Claude Desktop.
Neste módulo, vamos criar o MCP Server mais simples possível: uma única tool que recebe um nome e retorna uma saudação. O objetivo não é impressionar pela complexidade, mas sim entender cada linha de código e o fluxo completo — do código Python até o Claude usando a tool. Se você entender o Hello World completamente, construir servers complexos será apenas uma questão de adicionar mais tools.
O Hello World MCP é um server com uma única tool: hello(nome: str) que retorna f"Olá, {nome}!". É o equivalente ao "Hello World" de qualquer linguagem de programação — o menor programa funcional possível. A diferença é que, em vez de imprimir no terminal, essa função será chamada por uma IA através do protocolo MCP. O modelo decide quando chamar, passa os parâmetros, e recebe o resultado.
Resista à tentação de adicionar features extras no Hello World. O objetivo aqui é clareza total, não funcionalidade. Quando você entender cada linha deste server mínimo, será capaz de construir qualquer coisa. Pense nisso como aprender a andar antes de correr — o fundamento sólido agora vai economizar horas de debugging depois.
Vamos usar o uv para criar e configurar o projeto. O uv cuida de tudo: inicializa o projeto com pyproject.toml, cria o ambiente virtual, e instala as dependências. Em três comandos, você terá um projeto Python pronto para receber o código do server.
A criação do projeto usa três comandos: uv init hello-mcp — cria o diretório com pyproject.toml; cd hello-mcp — entra no diretório; e uv add fastmcp — adiciona o FastMCP como dependência. Depois, crie o arquivo server.py onde ficará o código do server. Em menos de 30 segundos, você tem um projeto Python completo e configurado.
Execute uv init hello-mcp — cria o diretório do projeto com pyproject.toml, .python-version e estrutura inicial.
Entre no diretório com cd hello-mcp — todos os comandos seguintes devem ser executados de dentro do projeto.
Execute uv add fastmcp — instala o FastMCP e todas as suas dependências no ambiente virtual do projeto.
Crie o arquivo server.py no diretório raiz do projeto — é aqui que escreveremos o código do MCP Server.
Se você já tem o uv instalado, pode fazer tudo em uma linha: uv init hello-mcp && cd hello-mcp && uv add fastmcp. O uv é extremamente rápido — a instalação do FastMCP e todas as suas dependências leva apenas alguns segundos, muito mais rápido que o pip tradicional.
Agora vem a parte mais satisfatória: escrever o código do server. São apenas 10 linhas — mas cada uma tem um propósito preciso. Não copie e cole sem entender; leia cada linha e compreenda o que ela faz. Este é o código que transforma uma função Python comum em uma capability acessível por qualquer IA compatível com MCP.
O código completo do Hello World MCP Server:
Essas ~10 linhas são um MCP Server completo e funcional. O FastMCP cuida de todo o protocolo por baixo — JSON-RPC, transporte, negociação de capabilities, serialização — você só precisa se preocupar com a lógica da sua tool.
Sem o FastMCP, implementar o mesmo server usando o protocolo MCP de baixo nível exigiria mais de 150 linhas de código — incluindo parsing de JSON-RPC, gerenciamento de transporte stdio, negociação de capabilities, serialização de schemas, e tratamento de erros do protocolo. O FastMCP reduz isso para ~10 linhas, uma redução de mais de 90% no código necessário. Essa é a vantagem de usar um framework bem projetado.
Com o código pronto, é hora de conectar o server ao Claude Desktop. Isso é feito editando o arquivo de configuração do Claude e adicionando uma entrada para o seu server. O Claude Desktop vai usar o uv para iniciar o server automaticamente quando necessário.
Adicione ao arquivo claude_desktop_config.json do Claude Desktop:
Substitua /caminho/completo/hello-mcp pelo caminho absoluto real do seu projeto. Depois, reinicie o Claude Desktop para que ele detecte o novo server.
O caminho no --directory deve ser absoluto — caminhos relativos não funcionam. Use o caminho completo como /home/usuario/projetos/hello-mcp no Linux/Mac ou C:\\Users\\usuario\\projetos\\hello-mcp no Windows. Um caminho errado é a causa número 1 de "server não aparece no Claude" — verifique com cuidado!
Com o server configurado e o Claude Desktop reiniciado, é hora do momento mágico: testar se tudo funciona. Abra uma nova conversa no Claude e peça para ele usar a tool. Se tudo estiver correto, o Claude vai identificar a tool automaticamente, chamá-la com os parâmetros certos, e exibir o resultado. Essa é a experiência do MCP funcionando de ponta a ponta.
Para testar, abra o Claude Desktop e digite algo como "Diga olá para Maria". O Claude deve: (1) reconhecer que tem uma tool hello disponível; (2) decidir usá-la para atender o pedido; (3) chamar a tool com nome="Maria"; (4) receber o resultado "Olá, Maria!"; e (5) apresentar o resultado na conversa. Se isso acontecer, parabéns — seu primeiro MCP Server está funcionando!
Se a tool não aparecer no Claude Desktop, verifique: (1) o caminho no config.json está correto e absoluto; (2) o uv está instalado e acessível; (3) o Claude Desktop foi reiniciado; (4) o arquivo server.py não tem erros de sintaxe. Você pode testar o server manualmente com uv run server.py no terminal — se der erro, o problema está no código.
Abra o Claude Desktop e inicie uma nova conversa.
Verifique se o ícone de ferramentas (martelo) aparece — ele indica que MCP Servers estão conectados.
Digite "Diga olá para Maria" e envie a mensagem.
O Claude pedirá permissão para usar a tool "hello" — clique em "Allow" para autorizar.
Verifique que o resultado exibe "Olá, Maria!" — seu MCP Server está funcionando!
Agora que o server funciona, vamos voltar ao código e destrinchar cada linha em detalhe. Entender o "porquê" de cada elemento é o que separa copiar código de compreender código. Cada linha do Hello World tem uma função precisa no funcionamento do MCP Server, e nenhuma é supérflua.
from fastmcp import FastMCP — traz o framework para o código. Sem isso, Python não sabe o que é FastMCP.
mcp = FastMCP("hello-mcp") — cria o objeto server. O nome identifica o server no client.
@mcp.tool() — registra a função como uma tool MCP. Sem o decorator, é apenas uma função Python normal.
def hello(nome: str) -> str — a lógica da tool. O nome da função vira o nome da tool.
nome: str e -> str — definem o schema da tool. O modelo sabe que precisa enviar uma string e vai receber uma string.
"""Diz olá para a pessoa informada.""" — vira a descrição da tool que o modelo lê para decidir quando usá-la.
Cada elemento do código tem um mapeamento direto no protocolo MCP: o nome da função vira o campo name da tool; os type hints viram o inputSchema (JSON Schema); a docstring vira o campo description; e o retorno vira o content da resposta. O FastMCP faz essa tradução automaticamente — você escreve Python idiomático, e o framework gera o protocolo MCP correto.
Experimente mudar coisas e ver o que acontece: mude a docstring e veja como o Claude descreve a tool; adicione um segundo parâmetro e veja o Claude pedir as informações extras; mude o nome da função e veja o novo nome aparecer no Claude. Essa experimentação ativa é a melhor forma de internalizar como cada parte do código se conecta com o comportamento do MCP Server.
hello que retorna uma saudação personalizada.
uv init e uv add fastmcp — setup completo em segundos.
claude_desktop_config.json com caminho absoluto obrigatório.
Próximo Módulo: 3.3 — Entendendo Decorators e Schemas