Criando seu primeiro servidor FastMCP do zero

Nos dois posts anteriores entendemos o que é o Model Context Protocol e conhecemos o FastMCP, a biblioteca que simplifica a criação de servidores MCP em Python. Agora é hora de colocar a mão na massa.

Post 1: O que é MCP e por que ele importa para o futuro dos agentes de IA?
Post 2: FastMCP: a forma mais rápida de criar servidores MCP em Python

Neste post vamos construir um servidor FastMCP real, do zero, que consulta endereços a partir de um CEP usando a API pública ViaCEP — sem chave de API, sem autenticação, pronto para usar.

Ao final, você vai conectar esse servidor ao Claude Desktop e perguntar diretamente ao Claude: “Qual o endereço do CEP 01310-100?” — e ele vai responder usando a sua tool.

Pré-requisitos

Antes de começar, certifique-se de ter:

• Python 3.10+ instalado
• pip atualizado
• Claude Desktop instalado (download aqui)
• Terminal (usaremos o Terminal do Mac)

Para verificar sua versão do Python:

python3 --version

python3 --version

1. Criando o ambiente do projeto

Abra o Terminal e crie uma pasta para o projeto:

mkdir mcp-cep-server
cd mcp-cep-server

mkdir mcp-cep-server
cd mcp-cep-server

Crie e ative um ambiente virtual:

python3 -m venv .venv
source .venv/bin/activate

python3 -m venv .venv
source .venv/bin/activate

Você verá o prefixo (.venv) no terminal — isso confirma que o ambiente está ativo.

Instale as dependências:

pip install fastmcp httpx

pip install fastmcp httpx

• fastmcp — o framework do servidor
• httpx — cliente HTTP moderno para consumir a API ViaCEP

Você irá ver os logs, com o sucesso da instalação.

2. Criando o servidor

Crie o arquivo principal do servidor:

touch server.py
# ou voce pode criar direto no vscode mesmo...

touch server.py
# ou voce pode criar direto no vscode mesmo...

Abra seu editor de código favorito e escreva o código:

import httpx
from fastmcp import FastMCP

mcp = FastMCP("servidor-cep")

@mcp.tool()
async def consultar_cep(cep: str) -> str:
    """
    Consulta o endereço completo a partir de um CEP brasileiro.
    Retorna rua, bairro, cidade e estado.
    """
    cep_limpo = cep.replace("-", "").replace(" ", "")

    if len(cep_limpo) != 8 or not cep_limpo.isdigit():
        return "CEP inválido. Informe um CEP com 8 dígitos numéricos."

    async with httpx.AsyncClient() as client:
        response = await client.get(
            f"https://viacep.com.br/ws/{cep_limpo}/json/"
        )

    if response.status_code != 200:
        return "Erro ao consultar o CEP. Tente novamente."

    dados = response.json()

    if "erro" in dados:
        return f"CEP {cep} não encontrado."

    return (
        f"CEP: {dados.get('cep', '-')}\n"
        f"Rua: {dados.get('logradouro', '-')}\n"
        f"Bairro: {dados.get('bairro', '-')}\n"
        f"Cidade: {dados.get('localidade', '-')}\n"
        f"Estado: {dados.get('uf', '-')}"
    )

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

import httpx
from fastmcp import FastMCP

mcp = FastMCP("servidor-cep")

@mcp.tool()
async def consultar_cep(cep: str) -> str:
    """
    Consulta o endereço completo a partir de um CEP brasileiro.
    Retorna rua, bairro, cidade e estado.
    """
    cep_limpo = cep.replace("-", "").replace(" ", "")

    if len(cep_limpo) != 8 or not cep_limpo.isdigit():
        return "CEP inválido. Informe um CEP com 8 dígitos numéricos."

    async with httpx.AsyncClient() as client:
        response = await client.get(
            f"https://viacep.com.br/ws/{cep_limpo}/json/"
        )

    if response.status_code != 200:
        return "Erro ao consultar o CEP. Tente novamente."

    dados = response.json()

    if "erro" in dados:
        return f"CEP {cep} não encontrado."

    return (
        f"CEP: {dados.get('cep', '-')}\n"
        f"Rua: {dados.get('logradouro', '-')}\n"
        f"Bairro: {dados.get('bairro', '-')}\n"
        f"Cidade: {dados.get('localidade', '-')}\n"
        f"Estado: {dados.get('uf', '-')}"
    )

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

O que esse código faz?

• Linha 4: instancia o servidor FastMCP com o nome "servidor-cep"
• Linha 6: decora a função com @mcp.tool() — o FastMCP registra automaticamente a tool no protocolo
• Linhas 7-10: a docstring vira a descrição da tool que o LLM vai ler para decidir quando usá-la
• Linhas 12-14: limpa o CEP removendo traços e espaços, e valida o formato
• Linhas 16-20: faz a requisição HTTP para a API ViaCEP de forma assíncrona
• Linhas 22-30: trata erros e formata a resposta

3. Testando o servidor localmente

Antes de conectar ao Claude Desktop, vamos garantir que o servidor está funcionando. O FastMCP tem um modo de inspeção embutido:

fastmcp dev inspector  server.py

fastmcp dev inspector  server.py

Esse comando sobe o servidor e abre o MCP Inspector no navegador, uma interface visual onde você pode chamar suas tools manualmente.

No Inspector:

1. Clique em “Tools” no menu lateral
2. Selecione “consultar_cep”
3. Preencha o campo cep com 01310-100
4. Clique em “Run”

Você deve ver a resposta:

4. Conectando ao Claude Desktop

Agora vamos conectar o servidor ao Claude Desktop para que o Claude possa usar a tool diretamente nas conversas.

4.1 Localize o arquivo de configuração

O Claude Desktop usa um arquivo JSON para registrar servidores MCP. No Mac, ele fica em:

~/Library/Application Support/Claude/claude_desktop_config.json  

~/Library/Application Support/Claude/claude_desktop_config.json  

Abra o Terminal e edite o arquivo:

open -a TextEdit ~/Library/Application\ Support/Claude/claude_desktop_config.json

open -a TextEdit ~/Library/Application\ Support/Claude/claude_desktop_config.json

Se o arquivo não existir, crie-o com o comando:

mkdir -p ~/Library/Application\ Support/Claude
touch ~/Library/Application\ Support/Claude/claude_desktop_config.json

mkdir -p ~/Library/Application\ Support/Claude
touch ~/Library/Application\ Support/Claude/claude_desktop_config.json

4.2 Adicione o servidor

Cole o seguinte conteúdo no arquivo, ajustando o caminho para o seu projeto:

{
  "mcpServers": {
    "servidor-cep": {
      "command": "/caminho/para/seu/projeto/mcp-cep-server/.venv/bin/python",
      "args": [
        "/caminho/para/seu/projeto/mcp-cep-server/server.py"
      ]
    }
  }
}

{
  "mcpServers": {
    "servidor-cep": {
      "command": "/caminho/para/seu/projeto/mcp-cep-server/.venv/bin/python",
      "args": [
        "/caminho/para/seu/projeto/mcp-cep-server/server.py"
      ]
    }
  }
}

Para descobrir o caminho correto do Python no seu ambiente virtual, rode:

which python

which python

4.3 Reinicie o Claude Desktop

Feche e abra o Claude Desktop novamente. Após reiniciar, você verá um ícone de conectore na interface de chat — isso indica que tools MCP estão disponíveis.

5. Testando no Claude Desktop

Com tudo configurado, abra uma nova conversa no Claude Desktop e pergunte:

“Qual o endereço do CEP 01310-100?”

O Claude vai identificar que tem uma tool disponível para isso, vai chamá-la automaticamente e retornar a resposta formatada.

Você também pode testar casos de erro:

“Consulta o CEP 00000-000 pra mim”

E o Claude vai retornar a mensagem de CEP não encontrado — exatamente como programamos.

Conclusão

Em menos de 40 linhas de Python, criamos um servidor MCP real que:

• ✅ Expõe uma tool funcional via protocolo MCP
• ✅ Consome uma API externa de forma assíncrona
• ✅ Valida entradas e trata erros
• ✅ Está conectado ao Claude Desktop e pronto para uso

Isso é o poder do MCP na prática: você escreve a lógica, o protocolo cuida da comunicação, e o LLM sabe exatamente quando e como usar sua tool.

Próximos passos

A partir daqui, as possibilidades são muitas:

• Adicionar mais tools ao mesmo servidor (ex: consulta de CNPJ, cotação de moeda)
• Criar Resources para expor dados estáticos ou dinâmicos
• Fazer deploy do servidor em modo SSE para acesso remoto
• Publicar seu servidor no ecossistema MCP para que outros usem

A série não para por aqui — fique ligado nos próximos posts.

Conseguiu rodar? Compartilha um print nos comentários! Tem alguma dúvida? Me chama.