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.

O post Criando seu primeiro servidor FastMCP do zero apareceu primeiro em Ramon Domingos Blog.

Agora vamos dar um passo à frente: conhecer o FastMCP, a biblioteca Python que torna a criação de servidores MCP algo surpreendentemente simples — e entender por que ela existe.

O SDK oficial do MCP

A Anthropic disponibilizou um SDK oficial em Python para criar servidores MCP. Ele funciona, é completo e segue o protocolo à risca. Mas tem um problema: é verboso.

Para criar um servidor com uma única tool usando o SDK oficial, você escreve algo assim:

from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp import types
import asyncio

server = Server("meu-servidor")

@server.list_tools()
async def list_tools() -> list[types.Tool]:
    return [
        types.Tool(
            name="somar",
            description="Soma dois números",
            inputSchema={
                "type": "object",
                "properties": {
                    "a": {"type": "number"},
                    "b": {"type": "number"}
                },
                "required": ["a", "b"]
            }
        )
    ]

@server.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "somar":
        return [types.TextContent(
            type="text",
            text=str(arguments["a"] + arguments["b"])
        )]

async def main():
    async with stdio_server() as (read, write):
        await server.run(read, write, server.create_initialization_options())

asyncio.run(main())

from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp import types
import asyncio

server = Server("meu-servidor")

@server.list_tools()
async def list_tools() -> list[types.Tool]:
    return [
        types.Tool(
            name="somar",
            description="Soma dois números",
            inputSchema={
                "type": "object",
                "properties": {
                    "a": {"type": "number"},
                    "b": {"type": "number"}
                },
                "required": ["a", "b"]
            }
        )
    ]

@server.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "somar":
        return [types.TextContent(
            type="text",
            text=str(arguments["a"] + arguments["b"])
        )]

async def main():
    async with stdio_server() as (read, write):
        await server.run(read, write, server.create_initialization_options())

asyncio.run(main())

Funciona. Mas são mais de 30 linhas para uma operação trivial. Imagine isso escalando para 10, 20 tools.

O que é o FastMCP?

O FastMCP é uma biblioteca Python de alto nível construída sobre o SDK oficial do MCP. A inspiração é clara no nome: assim como o FastAPI simplificou a criação de APIs REST em Python, o FastMCP simplifica a criação de servidores MCP.

O mesmo servidor acima, com FastMCP:

from fastmcp import FastMCP

mcp = FastMCP("meu-servidor")

@mcp.tool()
def somar(a: float, b: float) -> float:
    """Soma dois números"""
    return a + b

from fastmcp import FastMCP

mcp = FastMCP("meu-servidor")

@mcp.tool()
def somar(a: float, b: float) -> float:
    """Soma dois números"""
    return a + b

4 linhas. Mesmo resultado. Mesmo protocolo. Mesma compatibilidade.

O FastMCP cuida de toda a camada de serialização, validação de schema, registro de tools e comunicação via JSON-RPC — você foca apenas na lógica.

Por que FastMCP e não o SDK puro?

	SDK Oficial	FastMCP
Linhas para 1 tool	~30	~4
Tipagem automática		via type hints
Validação de schema	Manual	Automática
Curva de aprendizado	Alta	Baixa
Compatibilidade MCP
Ideal para	Controle total	Produtividade

A escolha não é binária — para casos que exigem controle fino do protocolo, o SDK oficial ainda faz sentido. Mas para a grande maioria dos projetos, o FastMCP é a escolha certa.

Arquitetura de um servidor FastMCP

Um servidor FastMCP é composto pelos mesmos três conceitos do protocolo MCP:

Tools

Funções Python decoradas com @mcp.tool(). O FastMCP lê os type hints e a docstring automaticamente para gerar o schema JSON da tool.

@mcp.tool()
def buscar_usuario(user_id: int) -> str:
    """Busca um usuário pelo ID"""
    # sua lógica aqui
    return f"Usuário {user_id}"

@mcp.tool()
def buscar_usuario(user_id: int) -> str:
    """Busca um usuário pelo ID"""
    # sua lógica aqui
    return f"Usuário {user_id}"

Resources

Fontes de dados expostas via URI, decoradas com @mcp.resource().

@mcp.resource("dados://config")
def get_config() -> str:
    """Retorna a configuração atual"""
    return "versão: 1.0"

@mcp.resource("dados://config")
def get_config() -> str:
    """Retorna a configuração atual"""
    return "versão: 1.0"

Prompts

Templates reutilizáveis decorados com @mcp.prompt().

@mcp.prompt()
def resumir(texto: str) -> str:
    """Prompt para resumir um texto"""
    return f"Resuma o seguinte texto em 3 bullets:\n\n{texto}"

@mcp.prompt()
def resumir(texto: str) -> str:
    """Prompt para resumir um texto"""
    return f"Resuma o seguinte texto em 3 bullets:\n\n{texto}"

Instalação e configuração do ambiente

O FastMCP requer Python 3.10+. A instalação é simples:

# Com pip
pip install fastmcp

# Com uv (recomendado)
uv add fastmcp

# Com pip
pip install fastmcp

# Com uv (recomendado)
uv add fastmcp

Por que uv? O uv é um gerenciador de pacotes e ambientes Python extremamente rápido, escrito em Rust. É a ferramenta recomendada pelo ecossistema MCP para gerenciar dependências. Se ainda não usa, vale a pena conhecer.

Para verificar a instalação:

python -c "import fastmcp; print(fastmcp.__version__)"

python -c "import fastmcp; print(fastmcp.__version__)"

A estrutura mínima de um servidor FastMCP

Todo servidor FastMCP segue esta estrutura base:

from fastmcp import FastMCP

# 1. Instancia o servidor com um nome
mcp = FastMCP("nome-do-servidor")

# 2. Define tools, resources e prompts
@mcp.tool()
def minha_tool(parametro: str) -> str:
    """Descrição da tool — o LLM vai ler isso"""
    return f"Resultado: {parametro}"

# 3. Ponto de entrada
if __name__ == "__main__":
    mcp.run()

from fastmcp import FastMCP

# 1. Instancia o servidor com um nome
mcp = FastMCP("nome-do-servidor")

# 2. Define tools, resources e prompts
@mcp.tool()
def minha_tool(parametro: str) -> str:
    """Descrição da tool — o LLM vai ler isso"""
    return f"Resultado: {parametro}"

# 3. Ponto de entrada
if __name__ == "__main__":
    mcp.run()

Três partes: instância, definição e execução. Simples assim.

No próximo post, vamos pegar exatamente essa estrutura e transformar em um servidor funcional, rodando localmente e conectado a um cliente MCP real.

O FastMCP remove a fricção entre a ideia e a implementação. Com ele, você não precisa conhecer os detalhes do protocolo JSON-RPC, nem gerenciar manualmente schemas e serialização — tudo isso é abstraído de forma elegante.

Se o MCP é a “tomada universal” dos agentes de IA, o FastMCP é o cabo que torna tudo mais fácil de conectar.

No próximo post, vamos colocar a mão na massa: criar um servidor FastMCP do zero, definir tools reais, rodar localmente e conectar ao Claude Desktop para ver tudo funcionando.

Está acompanhando a série? Deixa um comentário ou compartilha com alguém que trabalha com IA!

O post FastMCP: a forma mais rápida de criar servidores MCP em Python apareceu primeiro em Ramon Domingos Blog.