Você já tentou criar um servidor MCP e se deparou com dezenas de arquivos de configuração, boilerplate complexo e horas de debugging antes de ver sua primeira ferramenta funcionando? O tempo de desenvolver e testar servidores MCP precisa ser rápido - afinal, a iteração ágil é fundamental quando estamos experimentando com agentes de IA. É aí que entra o FastMCP.
O Problema: Desenvolvimento MCP é Muito Lento
Quando queremos testar uma ideia com MCP (Model Context Protocol), o ciclo tradicional envolve:
- ⚙️ Configurar estrutura de arquivos e dependências
- 📝 Escrever boilerplate para comunicação cliente-servidor
- 🔧 Implementar handlers de protocolo manualmente
- 🐛 Debugar problemas de transporte (STDIO, HTTP, SSE)
- 🧪 Finalmente testar sua ferramenta
Resultado: Horas até ter algo funcionando.
O que precisamos: Minutos para ir da ideia ao teste.
FastMCP: Simplicidade Extrema
FastMCP é uma biblioteca Python que reduz um servidor MCP completo a literalmente 3 linhas de código:
1
2
3
4
5
6
7
8
9
10
11
|
from fastmcp import FastMCP
mcp = FastMCP("Meu Servidor")
@mcp.tool
def multiplicar(a: float, b: float) -> float:
"""Multiplica dois números."""
return a * b
if __name__ == "__main__":
mcp.run()
|
Pronto. Você tem um servidor MCP funcional com uma ferramenta que pode ser chamada por Claude, GPT, GitHub Copilot ou qualquer cliente MCP.
Criando Seu Primeiro Servidor em 2 Minutos
Vamos criar um servidor de análise de dados do zero:
1. Instalação
2. Código Completo
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
|
from fastmcp import FastMCP
mcp = FastMCP(
"Analise Dados",
instructions="Servidor para análise de datasets numéricos. Use get_summary() para visão geral."
)
@mcp.tool
def calcular_media(numeros: list[float]) -> float:
"""Calcula a média de uma lista de números."""
if not numeros:
return 0.0
return sum(numeros) / len(numeros)
@mcp.tool
def encontrar_outliers(numeros: list[float], desvios: float = 2.0) -> list[float]:
"""
Identifica outliers em uma lista usando regra do desvio padrão.
Args:
numeros: Lista de números para análise
desvios: Número de desvios padrão para considerar outlier (padrão: 2.0)
"""
if len(numeros) < 2:
return []
media = sum(numeros) / len(numeros)
variancia = sum((x - media) ** 2 for x in numeros) / len(numeros)
desvio_padrao = variancia ** 0.5
limite_superior = media + (desvios * desvio_padrao)
limite_inferior = media - (desvios * desvio_padrao)
return [x for x in numeros if x > limite_superior or x < limite_inferior]
@mcp.resource("data://config")
def obter_config() -> dict:
"""Retorna configurações do servidor."""
return {
"versao": "1.0",
"modo": "producao",
"max_elementos": 10000
}
@mcp.prompt
def analisar_dataset(pontos: list[float]) -> str:
"""Gera prompt para análise de dataset."""
dados_formatados = ", ".join(str(p) for p in pontos[:10])
if len(pontos) > 10:
dados_formatados += f"... ({len(pontos)} pontos no total)"
return f"""Analise este dataset:
Dados: {dados_formatados}
Forneça:
1. Tendência geral
2. Valores atípicos
3. Insights principais"""
if __name__ == "__main__":
mcp.run()
|
Salve como servidor_dados.py e execute:
1
|
python servidor_dados.py
|
Boom! Servidor rodando em STDIO, pronto para conectar com qualquer cliente MCP.
Os 3 Tipos de Componentes
FastMCP expõe três tipos de componentes para clientes:
Funções que o agente pode invocar para realizar ações:
1
2
3
4
5
|
@mcp.tool
def buscar_preco_acao(simbolo: str) -> dict:
"""Busca preço atual de uma ação."""
# Sua lógica aqui
return {"simbolo": simbolo, "preco": 150.25, "moeda": "USD"}
|
📊 Resources (Recursos)
Dados passivos que clientes podem ler:
1
2
3
4
5
6
7
8
|
@mcp.resource("data://metricas")
def obter_metricas() -> dict:
"""Expõe métricas do sistema."""
return {
"requests_hoje": 1247,
"tempo_medio_resposta_ms": 45,
"taxa_erro_pct": 0.3
}
|
💬 Prompts (Templates)
Templates reutilizáveis para guiar LLMs:
1
2
3
4
5
6
7
|
@mcp.prompt
def revisar_codigo(codigo: str, linguagem: str) -> str:
"""Template para revisão de código."""
return f"""Revise este código {linguagem}:
```{linguagem}
{codigo}
|
Analise:
- Bugs potenciais
- Problemas de performance
- Boas práticas violadas
- Sugestões de melhoria"""
Transportes: STDIO, HTTP ou SSE
FastMCP suporta múltiplos transportes sem mudar seu código:
STDIO (Padrão - para integração local)
1
|
mcp.run() # Usa STDIO automaticamente
|
HTTP (Para serviços web)
1
|
mcp.run(transport="http", host="0.0.0.0", port=8000)
|
Agora você tem um endpoint HTTP com o protocolo MCP Streamable. Perfeito para deploy em produção.
SSE (Legado)
1
|
mcp.run(transport="sse")
|
Recursos Avançados
Organize ferramentas por categorias e exponha apenas o necessário:
1
2
3
4
5
6
7
8
9
10
11
12
13
|
@mcp.tool(tags={"publico", "util"})
def ferramenta_publica() -> str:
return "Acessível a todos"
@mcp.tool(tags={"interno", "admin"})
def ferramenta_admin() -> str:
return "Apenas administradores"
# Expor apenas ferramentas públicas
mcp.enable(tags={"publico"}, only=True)
# Ou esconder internas e deprecated
mcp.disable(tags={"interno", "deprecated"})
|
Rotas HTTP Customizadas
Adicione endpoints HTTP personalizados quando usar transporte HTTP:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
|
from starlette.requests import Request
from starlette.responses import JSONResponse
@mcp.custom_route("/health", methods=["GET"])
async def health_check(request: Request) -> JSONResponse:
return JSONResponse({"status": "ok", "server": "online"})
@mcp.custom_route("/metrics", methods=["GET"])
async def metricas(request: Request) -> JSONResponse:
return JSONResponse({
"ferramentas_registradas": 15,
"uptime_horas": 48
})
mcp.run(transport="http")
# Health check em: http://localhost:8000/health
# Métricas em: http://localhost:8000/metrics
|
Validação de Entrada Rigorosa
Por padrão, FastMCP é flexível (converte "10" → 10 automaticamente). Para validação estrita:
1
2
3
4
5
6
7
|
mcp = FastMCP("Servidor Estrito", strict_input_validation=True)
@mcp.tool
def processar(quantidade: int) -> str:
# Com strict=True, apenas int é aceito
# String "10" será rejeitada
return f"Processando {quantidade} itens"
|
Caso de Uso Real: Servidor de Criptomoedas
Vamos criar algo útil - um servidor para consultar dados de crypto:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
|
from fastmcp import FastMCP
import httpx
mcp = FastMCP(
"CryptoMCP",
instructions="Consulte preços e dados de criptomoedas em tempo real."
)
@mcp.tool
async def preco_bitcoin() -> dict:
"""Retorna preço atual do Bitcoin em USD."""
async with httpx.AsyncClient() as client:
response = await client.get(
"https://api.coingecko.com/api/v3/simple/price",
params={"ids": "bitcoin", "vs_currencies": "usd,brl"}
)
data = response.json()
return {
"moeda": "Bitcoin",
"preco_usd": data["bitcoin"]["usd"],
"preco_brl": data["bitcoin"]["brl"]
}
@mcp.tool
async def top_cryptos(limite: int = 10) -> list[dict]:
"""
Lista as top criptomoedas por market cap.
Args:
limite: Quantidade de moedas a retornar (padrão: 10, máx: 100)
"""
limite = min(limite, 100) # Proteger API
async with httpx.AsyncClient() as client:
response = await client.get(
"https://api.coingecko.com/api/v3/coins/markets",
params={
"vs_currency": "usd",
"order": "market_cap_desc",
"per_page": limite,
"page": 1
}
)
cryptos = response.json()
return [
{
"nome": c["name"],
"simbolo": c["symbol"].upper(),
"preco_usd": c["current_price"],
"variacao_24h_pct": round(c["price_change_percentage_24h"], 2),
"market_cap_usd": c["market_cap"]
}
for c in cryptos
]
@mcp.resource("data://status")
def status_api() -> dict:
"""Status da conexão com APIs de crypto."""
return {
"api": "CoinGecko",
"status": "online",
"rate_limit": "50 requests/min"
}
if __name__ == "__main__":
mcp.run()
|
Agora você pode perguntar ao Claude: “Qual o preço do Bitcoin agora?” ou “Me mostre as top 5 cryptos” e ele usará seu servidor automaticamente.
Configurando FastMCP no Claude Desktop
Para usar seu servidor FastMCP com o Claude Desktop, você precisa adicionar a configuração no arquivo claude_desktop_config.json:
Localizando o Arquivo de Configuração
O arquivo está localizado em:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:
%APPDATA%\Claude\claude_desktop_config.json
- Linux:
~/.config/Claude/claude_desktop_config.json
Adicionando Seu Servidor
Edite o arquivo e adicione sua configuração FastMCP:
1
2
3
4
5
6
7
8
9
10
|
{
"mcpServers": {
"crypto-mcp": {
"command": "python",
"args": [
"/caminho/completo/para/seu/servidor_crypto.py"
]
}
}
}
|
Importante: Use o caminho absoluto para o arquivo Python do seu servidor.
Se você usa um ambiente virtual Python (recomendado), aponte para o Python do ambiente:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
|
{
"mcpServers": {
"crypto-mcp": {
"command": "/home/usuario/.venvs/mcp-env/bin/python",
"args": [
"/home/usuario/projetos/mcp-servers/servidor_crypto.py"
]
},
"analise-dados": {
"command": "/home/usuario/.venvs/mcp-env/bin/python",
"args": [
"/home/usuario/projetos/mcp-servers/servidor_dados.py"
]
}
}
}
|
Múltiplos Servidores
Você pode registrar vários servidores FastMCP simultaneamente:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
|
{
"mcpServers": {
"crypto": {
"command": "python",
"args": ["/caminho/para/servidor_crypto.py"]
},
"dados": {
"command": "python",
"args": ["/caminho/para/servidor_dados.py"]
},
"web-scraper": {
"command": "python",
"args": ["/caminho/para/servidor_scraper.py"]
}
}
}
|
Testando a Configuração
- Salve o arquivo de configuração
- Reinicie o Claude Desktop completamente
- Abra uma nova conversa no Claude
- Verifique se os servidores foram carregados - você pode perguntar: “Quais ferramentas MCP você tem disponíveis?”
Troubleshooting
Se seu servidor não aparecer:
Verificar logs do Claude:
- macOS:
~/Library/Logs/Claude/mcp*.log
- Windows:
%APPDATA%\Claude\logs\mcp*.log
Problemas comuns:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
|
// ❌ Errado - Caminho relativo
{
"command": "python",
"args": ["./servidor.py"]
}
// ✅ Correto - Caminho absoluto
{
"command": "python",
"args": ["/home/usuario/projetos/servidor.py"]
}
// ❌ Errado - Python do sistema sem dependências
{
"command": "python3",
"args": ["/caminho/servidor.py"]
}
// ✅ Correto - Python do venv com fastmcp instalado
{
"command": "/home/usuario/.venv/bin/python",
"args": ["/caminho/servidor.py"]
}
|
Exemplo de Teste Completo
Crie teste_crypto.py:
1
2
3
4
5
6
7
8
9
10
11
|
from fastmcp import FastMCP
mcp = FastMCP("TesteCrypto")
@mcp.tool
def ola_claude() -> str:
"""Retorna uma saudação de teste."""
return "👋 Olá do FastMCP! Servidor funcionando perfeitamente!"
if __name__ == "__main__":
mcp.run()
|
Adicione no claude_desktop_config.json:
1
2
3
4
5
6
7
8
|
{
"mcpServers": {
"teste": {
"command": "python",
"args": ["/caminho/completo/para/teste_crypto.py"]
}
}
}
|
Reinicie o Claude e pergunte: “Use a ferramenta ola_claude”
Se receber a saudação, seu servidor FastMCP está configurado corretamente! 🎉
Vantagens do FastMCP
✅ Zero boilerplate - Foco na lógica, não na infraestrutura
✅ Type hints nativos - Validação automática via Pydantic
✅ Async por padrão - Performance para chamadas I/O
✅ Múltiplos transportes - STDIO, HTTP, SSE sem reescrever código
✅ Docstrings como documentação - LLMs entendem suas ferramentas automaticamente
✅ Deploy simples - Um arquivo Python é suficiente
✅ Debugging facilitado - Errors claros e informativos
Conclusão: Velocidade é Tudo
FastMCP remove toda a fricção do desenvolvimento MCP. O que levaria horas configurando agora leva minutos codificando. Isso muda completamente a experiência de desenvolver ferramentas para agentes de IA.
Quando você pode testar uma ideia em 5 minutos ao invés de 5 horas, você experimenta mais, aprende mais rápido e constrói coisas melhores.
O futuro da IA é agêntico. FastMCP garante que você chegue lá rapidamente.
