🐍 Criando Seu Primeiro MCP Server

Um MCP Server é composto por componentes essenciais: o objeto FastMCP que gerencia tudo, as funções decoradas que definem tools, resources e prompts, e o ponto de entrada que inicia o servidor. Cada parte tem uma responsabilidade clara.

Conhecer a anatomia de um server te permite entender qualquer código MCP que encontrar e criar seus próprios servers com confiança, sabendo onde cada peça se encaixa.

FastMCP, objeto server, decorators, ponto de entrada, componentes, responsabilidades.

A inicialização de um MCP Server envolve criar a instância FastMCP com um nome, configurar parâmetros opcionais como versão e descrição, e preparar o ambiente para receber conexões. O setup é o momento onde tudo é registrado.

Um setup bem feito garante que seu server funcione corretamente desde o primeiro momento. Erros na inicialização são os mais difíceis de diagnosticar se você não entende o processo.

FastMCP(), nome do server, parâmetros de configuração, instanciação, setup inicial.

Registrar tools é o processo de decorar funções Python com @mcp.tool() para torná-las disponíveis para o modelo de IA. O decorator extrai automaticamente o nome, descrição e schema de parâmetros da função.

O registro de tools é a operação mais fundamental de um MCP Server. Dominar este processo é essencial para criar servers que expõem funcionalidades úteis ao modelo.

@mcp.tool(), registro automático, introspecção de função, schema generation, decorators Python.

O ciclo de vida de um MCP Server inclui: inicialização, handshake com o Client, registro de capabilities, espera por requisições, processamento de chamadas, e encerramento gracioso. Cada fase tem eventos e comportamentos específicos.

Entender o ciclo de vida permite criar servers robustos que lidam corretamente com cada fase, incluindo inicialização e shutdown limpos.

Lifecycle, handshake, capabilities, request loop, graceful shutdown, eventos de ciclo.

A estrutura de arquivos de um MCP Server típico inclui o arquivo principal do server, um pyproject.toml ou requirements.txt para dependências, e opcionalmente módulos separados para tools complexas. Servers simples podem ser um único arquivo.

Uma boa organização de arquivos facilita a manutenção, os testes e a colaboração. Seguir convenções permite que outros desenvolvedores entendam seu server rapidamente.

Estrutura de projeto, arquivo principal, dependências, pyproject.toml, módulos, organização.

As configurações essenciais de um MCP Server incluem o nome do server, versão, transporte utilizado, e variáveis de ambiente. Essas configurações definem como o server se apresenta ao Client e como ele se comporta em diferentes ambientes.

Configurar corretamente seu server garante compatibilidade com diferentes Hosts e ambientes. Configurações erradas são uma causa comum de problemas de conexão.

Nome e versão, transporte, variáveis de ambiente, configuração de Host, compatibilidade.

O objetivo é criar o MCP Server mais simples possível: um server com uma única tool que retorna "Olá, mundo!". Este é o equivalente do Hello World para o ecossistema MCP — o mínimo funcional que prova que tudo está funcionando.

Começar com o mínimo funcional elimina a complexidade e permite focar no essencial. Uma vez que o Hello World funciona, você tem uma base sólida para adicionar features.

Hello World, mínimo funcional, proof of concept, base de aprendizado, simplicidade.

Criar o arquivo do server envolve definir o diretório do projeto, criar o arquivo Python principal (ex: server.py), e garantir que o ambiente virtual está configurado com as dependências corretas instaladas via pip.

Saber criar a estrutura inicial corretamente evita problemas de importação, dependências e execução. É o alicerce sobre o qual todo o resto é construído.

Criação de projeto, server.py, ambiente virtual, pip install, estrutura de diretórios.

O código do Hello World MCP consiste em importar FastMCP, criar a instância do server, definir uma função decorada com @mcp.tool() que retorna "Olá, mundo!", e adicionar o ponto de entrada com mcp.run(). São menos de 10 linhas de código.

Escrever o código do zero, ao invés de copiar e colar, garante que você entenda cada linha. Este é o conhecimento fundamental que será expandido em todos os módulos seguintes.

from mcp.server.fastmcp import FastMCP, instanciação, @mcp.tool(), return string, mcp.run().

Para que o Claude Desktop reconheça seu server, é preciso adicioná-lo ao claude_desktop_config.json. A entrada inclui o comando para executar o Python, o caminho para o arquivo do server, e opcionalmente variáveis de ambiente.

A configuração no Host é o passo que conecta seu código ao modelo de IA. Sem ela, seu server existe mas ninguém consegue usá-lo. É a ponte entre o desenvolvimento e o uso real.

claude_desktop_config.json, mcpServers, command, args, caminho do script, reiniciar Claude.

Testar o Hello World envolve reiniciar o Claude Desktop, verificar que o server aparece na lista de conexões, e enviar uma mensagem que acione a tool. O Claude deve chamar sua tool e exibir "Olá, mundo!" na resposta.

Ver seu primeiro server funcionando é o momento mais motivador do curso. Confirmar que tudo funciona te dá confiança para construir servers mais complexos.

Teste manual, verificação de conexão, tool calling, resposta esperada, troubleshooting básico.

Uma análise linha por linha do código Hello World: o import traz o framework, FastMCP() cria o server, @mcp.tool() registra a função, a docstring vira a descrição da tool, o return define a resposta, e mcp.run() inicia o loop de eventos.

Entender cada linha em profundidade transforma código memorizado em conhecimento real. Você saberá modificar e expandir qualquer parte do server com segurança.

Import statement, instanciação, decorator pattern, docstring como metadata, event loop, execução.

Decorators em Python são funções que envolvem outras funções, adicionando comportamento sem modificar o código original. O símbolo @ antes de uma função indica que ela está sendo decorada. No MCP, decorators registram funções como tools, resources ou prompts.

Decorators são o mecanismo central do FastMCP. Sem entendê-los, o código parece mágico. Com esse conhecimento, você controla exatamente o que está acontecendo.

Python decorators, @syntax, wrapper functions, metaprogramação, registro automático.

O decorator @mcp.tool() transforma uma função Python comum em uma tool MCP. Ele extrai o nome da função, sua docstring como descrição, e os type hints dos parâmetros como schema de entrada. Também aceita parâmetros opcionais para personalizar o registro.

@mcp.tool() é o decorator que você vai usar em 90% dos casos. Dominar suas opções e comportamentos te permite criar tools precisas e bem documentadas.

@mcp.tool(), nome automático, docstring como descrição, type hints, parâmetros opcionais.

Schemas de parâmetros definem os tipos de entrada que uma tool aceita. O FastMCP usa type hints do Python (str, int, float, bool, list, dict) para gerar automaticamente o JSON Schema que o modelo usa para construir chamadas corretas.

Schemas bem definidos garantem que o modelo envie dados no formato correto. Sem schemas adequados, suas tools recebem dados inesperados e falham silenciosamente.

JSON Schema, type hints, str, int, float, bool, Optional, parâmetros obrigatórios vs opcionais.

Tools MCP podem retornar strings simples, dicionários que são serializados em JSON, ou listas de conteúdo com tipos específicos (texto, imagem, etc). O tipo de retorno define como o modelo interpreta e apresenta o resultado ao usuário.

Escolher o tipo de retorno adequado impacta como o modelo usa o resultado. Retornos bem formatados permitem que o modelo gere respostas mais precisas e úteis.

Return string, return dict, TextContent, ImageContent, serialização, formatação de resposta.

As descrições de tools vêm das docstrings das funções Python. O modelo lê essas descrições para decidir quando e como usar cada tool. Descrições claras e específicas fazem o modelo usar suas tools de forma mais inteligente e precisa.

A qualidade das descrições impacta diretamente a qualidade das interações. Uma tool com descrição ruim será ignorada ou usada incorretamente pelo modelo.

Docstrings, descrição de tool, descrição de parâmetros, prompt engineering para tools, clareza.

Boas práticas para tools MCP incluem: nomes descritivos em snake_case, docstrings detalhadas, type hints em todos os parâmetros, valores padrão quando faz sentido, retornos informativos, e tratamento de erros consistente.

Seguir boas práticas desde o início cria hábitos que resultam em servers mais robustos, mais fáceis de manter e mais eficazes na interação com o modelo.

Naming conventions, documentação, type safety, default values, error handling, consistência.

Planejar as tools da calculadora envolve definir 4 operações matemáticas (somar, subtrair, multiplicar, dividir), seus parâmetros (dois números), tipos de entrada (float), e comportamentos especiais como validação de divisão por zero.

Planejar antes de codar é um hábito essencial. Definir a interface das tools antes de implementá-las garante consistência e evita retrabalho.

Planejamento de API, definição de interface, parâmetros consistentes, edge cases, validação.

Implementar soma e subtração como tools MCP envolve criar funções decoradas que recebem dois parâmetros float, executam a operação, e retornam o resultado formatado. São as tools mais simples e servem como modelo para as próximas.

Começar com as operações mais simples permite focar no padrão de implementação. Uma vez que soma e subtração funcionam, multiplicação e divisão seguem o mesmo modelo.

Implementação de tools, parâmetros float, retorno formatado, docstrings descritivas, padrão replicável.

A tool de multiplicação segue o mesmo padrão das anteriores, mas introduz a oportunidade de discutir formatação de resultados com muitas casas decimais e como apresentar números grandes de forma legível para o modelo.

A multiplicação parece trivial, mas levanta questões práticas sobre formatação e precisão numérica que são relevantes para qualquer tool que trabalhe com números.

Multiplicação, formatação numérica, precisão decimal, números grandes, apresentação de resultado.

A tool de divisão introduz o primeiro caso real de validação de entrada: verificar se o divisor é zero antes de executar a operação. Isso demonstra como tratar erros de forma elegante e retornar mensagens informativas ao modelo.

Validação de entrada é uma habilidade crítica para qualquer server. A divisão por zero é o exemplo perfeito para introduzir o conceito de way tools devem lidar com entradas inválidas.

Validação de entrada, divisão por zero, mensagem de erro, retorno condicional, robustez.

Testar todas as tools da calculadora envolve verificar cada operação com diferentes tipos de entrada: números inteiros, decimais, negativos, zero, e números muito grandes. Inclui testar o caso de divisão por zero para confirmar que a validação funciona.

Testes abrangentes garantem que seu server funciona em todos os cenários. Criar o hábito de testar com inputs variados evita bugs em produção.

Testes manuais, casos de teste, edge cases, inputs variados, verificação de validação.

Melhorar a calculadora com tratamento de erros robusto inclui: adicionar try/except para capturar exceções inesperadas, validar tipos de entrada, limitar o tamanho dos números aceitos, e retornar mensagens de erro padronizadas que o modelo pode interpretar.

Transformar um protótipo funcional em código robusto é uma habilidade profissional. Este passo mostra como evoluir seu server de "funciona" para "funciona sempre".

Try/except, validação robusta, limites de entrada, mensagens de erro padronizadas, defensive programming.

Escolher uma API de clima gratuita e confiável é o primeiro passo para construir o server. APIs como Open-Meteo oferecem dados meteorológicos sem necessidade de chave de API, tornando o setup mais simples e acessível para aprendizado.

Saber escolher e avaliar APIs externas é uma habilidade fundamental. Muitos MCP Servers na prática são wrappers que conectam modelos de IA a APIs existentes.

API de clima, Open-Meteo, API gratuita, endpoints, documentação de API, rate limits.

Fazer requisições HTTP dentro de um MCP Server requer o uso de bibliotecas assíncronas como httpx, já que o FastMCP roda em um event loop asyncio. As requisições buscam dados da API e retornam respostas JSON que precisam ser parseadas.

Requisições HTTP são a base de qualquer integração com serviços externos. Dominar chamadas assíncronas garante que seu server não trava enquanto espera respostas de APIs.

httpx, async/await, requisição GET, JSON parsing, headers, query parameters.

Implementar a tool de clima envolve criar uma função async decorada que recebe o nome da cidade como parâmetro, faz a requisição à API, extrai os dados relevantes (temperatura, umidade, condição), e retorna uma string formatada com as informações.

Esta é a primeira tool que conecta seu server ao mundo externo. O padrão de receber input, buscar dados, e formatar resposta é usado em 80% dos MCP Servers reais.

async def, parâmetro cidade, chamada de API, extração de dados, formatação de resposta.

Formatar a resposta significa transformar dados brutos da API em uma string organizada e legível. Isso inclui apresentar temperatura com unidades, condição climática em texto descritivo, e informações adicionais de forma estruturada para o modelo interpretar.

A qualidade da formatação determina quão bem o modelo interpreta e apresenta os dados ao usuário. Dados bem formatados geram respostas mais naturais e informativas.

Formatação de dados, f-strings, unidades de medida, estruturação de informação, legibilidade.

Erros de rede são inevitáveis: a API pode estar fora do ar, a conexão pode cair, ou a resposta pode vir em formato inesperado. Tratar esses erros envolve try/except para httpx.HTTPError, timeouts configuráveis, e mensagens de erro informativas.

Tools que dependem de APIs externas precisam ser resilientes. Sem tratamento de erros, uma falha de rede derruba todo o server ao invés de retornar uma mensagem útil.

HTTPError, timeout, ConnectionError, retry logic, fallback, mensagem de erro amigável.

Testar com Claude envolve perguntar sobre o clima em diferentes cidades e verificar que o modelo chama a tool corretamente, recebe os dados, e apresenta as informações de forma natural ao usuário. Inclui testar com cidades inexistentes para validar o tratamento de erros.

O teste com Claude é o teste real de integração. Ele mostra como o modelo decide quando usar sua tool e como interpreta os resultados que ela retorna.

Teste de integração, interação com Claude, tool calling real, validação end-to-end, cenários de erro.

No código, Resources são funções decoradas com @mcp.resource() que retornam dados quando acessadas por uma URI específica. Diferente de tools, resources não executam ações — eles expõem informações que o modelo pode ler para enriquecer seu contexto.

Resources são o segundo pilar de um MCP Server. Implementá-los no código complementa o conhecimento teórico da Trilha 1 e amplia as capacidades do seu server.

@mcp.resource(), URI, retorno de dados, exposição de contexto, diferença de tools.

Resources estáticos retornam sempre o mesmo conteúdo — como documentação, guias, configurações padrão, ou qualquer dado que não muda entre chamadas. São os mais simples de implementar e ideais para contexto de referência.

Resources estáticos são a forma mais simples de fornecer contexto rico ao modelo. Eles podem transformar a qualidade das respostas ao dar ao modelo informações de referência sempre disponíveis.

Conteúdo estático, documentação, configurações, guias de referência, dados imutáveis.

Resources dinâmicos calculam ou buscam dados a cada acesso — como o status atual do sistema, dados de um banco de dados, ou informações que mudam com o tempo. Eles usam as mesmas URIs mas retornam conteúdo atualizado.

Resources dinâmicos permitem que o modelo acesse dados em tempo real sem precisar de tool calls. Eles são ideais para dashboards, status e informações que mudam frequentemente.

Conteúdo dinâmico, dados em tempo real, cálculo sob demanda, atualização automática, freshness.

URI schemes definem como os resources são identificados e acessados. Cada resource tem uma URI única (ex: config://app/settings, data://users/list) que o Client usa para solicitar o conteúdo. O scheme indica o tipo e o path indica o recurso específico.

URIs bem projetadas tornam seus resources intuitivos e organizados. Um bom esquema de URIs facilita a descoberta e o uso dos resources pelo modelo.

URI, scheme, path, identificação única, convenções de naming, hierarquia de recursos.

O protocolo MCP permite que o Client liste todos os resources disponíveis no Server via resources/list. Isso permite descoberta automática: o modelo sabe quais dados estão disponíveis sem precisar de documentação externa.

A listagem de resources é o que torna o protocolo auto-documentável. O modelo pode explorar os resources disponíveis e escolher os mais relevantes para cada situação.

resources/list, descoberta automática, auto-documentação, metadata de resources, listagem dinâmica.

Testar resources envolve verificar que eles aparecem na listagem, que suas URIs são acessíveis, que o conteúdo retornado está correto, e que resources dinâmicos atualizam seus dados. O teste pode ser feito via Claude ou MCP Inspector.

Testar resources garante que o modelo tem acesso aos dados corretos. Resources quebrados podem fazer o modelo gerar respostas baseadas em informações desatualizadas ou incorretas.

Teste de resources, verificação de URI, conteúdo correto, atualização dinâmica, debugging.

No código, Prompts são funções decoradas com @mcp.prompt() que retornam templates de mensagens pré-definidas. Eles podem aceitar parâmetros para personalização e retornam uma lista de mensagens que guiam o comportamento do modelo.

Prompts são o terceiro pilar do MCP e o mais subutilizado. Implementá-los no código completa seu domínio sobre as três capacidades de um MCP Server.

@mcp.prompt(), templates de mensagens, parâmetros, lista de mensagens, role (user/assistant).

Um prompt simples é uma função que retorna uma mensagem fixa sem aceitar parâmetros. Por exemplo, um prompt que instrui o modelo a agir como um revisor de código ou um assistente de debugging, com instruções detalhadas sobre o comportamento esperado.

Prompts simples são o ponto de partida mais acessível. Eles demonstram o mecanismo sem a complexidade de parâmetros, permitindo focar na estrutura e no formato.

Prompt sem parâmetros, mensagem fixa, instrução de comportamento, formato de retorno, simplicidade.

Prompts com parâmetros aceitam argumentos que personalizam a mensagem gerada. Por exemplo, um prompt de code review que recebe a linguagem de programação e o foco da revisão como parâmetros, gerando instruções específicas para cada caso.

Prompts parametrizados são muito mais versáteis que prompts fixos. Eles permitem criar templates reutilizáveis que se adaptam a diferentes contextos com um único código.

Parâmetros de prompt, templates dinâmicos, f-strings em prompts, personalização, reutilização.

Assim como tools e resources, prompts podem ser listados pelo Client via prompts/list. A listagem mostra o nome, descrição e parâmetros aceitos por cada prompt, permitindo que o Host ofereça uma interface de seleção ao usuário.

A listagem de prompts é como o Host descobre quais workflows estão disponíveis. Prompts bem documentados aparecem de forma clara na interface do usuário.

prompts/list, descoberta de prompts, metadata, descrição de parâmetros, interface do Host.

Os melhores casos de uso para prompts MCP incluem: workflows padronizados (code review, análise de dados), onboarding de novos usuários, instruções de domínio específico, e templates que combinam contexto de resources com instruções para usar tools.

Saber quando usar prompts vs tools vs resources é uma decisão de design importante. Prompts brilham em cenários onde o comportamento do modelo precisa ser guiado de forma consistente.

Workflows padronizados, onboarding, instruções de domínio, combinação com tools e resources, consistência.

Testar prompts envolve verificar que eles aparecem na listagem, que aceitam parâmetros corretamente, e que as mensagens geradas guiam o modelo conforme esperado. O teste inclui verificar o comportamento do modelo quando o prompt é ativado.

Prompts mal testados podem fazer o modelo se comportar de forma inesperada. Testar garante que as instruções são claras e produzem o comportamento desejado.

Teste de prompts, validação de parâmetros, verificação de comportamento, qualidade de instrução, iteração.

Erros em MCP Servers se dividem em categorias: erros de entrada (parâmetros inválidos), erros de execução (falhas na lógica), erros de rede (APIs inacessíveis), erros de sistema (falta de memória, disco cheio), e erros de protocolo (mensagens mal formatadas).

Classificar erros é o primeiro passo para tratá-los corretamente. Cada tipo de erro requer uma estratégia diferente de tratamento e uma mensagem de retorno apropriada.

Erros de entrada, erros de execução, erros de rede, erros de sistema, classificação, estratégia.

Validação de entrada é o processo de verificar que os parâmetros recebidos são válidos antes de executar a lógica da tool. Inclui verificar tipos, ranges, formato de strings, tamanho de listas, e qualquer condição que os dados devem atender.

Validar entrada é a primeira linha de defesa contra erros. É mais fácil e seguro rejeitar inputs ruins do que lidar com os erros cascata que eles causam durante a execução.

Input validation, type checking, range checking, early return, mensagens de rejeição claras.

Usar try/except em tools permite capturar exceções durante a execução e retornar mensagens de erro úteis ao invés de crashes. O padrão recomendado é capturar exceções específicas, logar o erro, e retornar uma mensagem que o modelo pode usar para informar o usuário.

Try/except bem implementado é a diferença entre um server que crasha e um que se recupera elegantemente. Exceptions não tratadas podem derrubar todo o server MCP.

try/except, exceções específicas, logging, recuperação, mensagem de erro como retorno.

Erros de rede incluem conexão recusada, DNS não resolvido, timeout de conexão, e respostas HTTP com status de erro. Cada tipo requer tratamento específico: retry para erros transitórios, fallback para indisponibilidade prolongada.

Se seu server depende de APIs externas, erros de rede são inevitáveis. Saber tratá-los garante que seu server continua útil mesmo quando serviços externos falham.

ConnectionError, TimeoutError, HTTP status codes, retry, fallback, circuit breaker.

Timeouts limitam quanto tempo uma operação pode demorar antes de ser cancelada. Em tools MCP, é essencial configurar timeouts para chamadas de rede, operações de disco, e qualquer processamento que pode travar. O asyncio.wait_for() é a ferramenta padrão.

Sem timeouts, uma tool pode ficar pendurada indefinidamente, bloqueando o server e frustrando o usuário. Timeouts garantem que o server sempre responde em tempo razoável.

asyncio.wait_for(), timeout configurável, TimeoutError, cancelamento, tempo de resposta.

Logging em MCP Servers usa o módulo logging do Python para registrar eventos, erros e informações de debug. Logs devem ir para stderr (não stdout, que é usado pelo protocolo). Níveis como DEBUG, INFO, WARNING e ERROR ajudam a filtrar informações.

Sem logs, debugar um MCP Server é como navegar no escuro. Bons logs são essenciais para diagnosticar problemas em desenvolvimento e em produção.

módulo logging, stderr vs stdout, níveis de log, formatação, debug em produção, rastreabilidade.

O MCP Inspector é uma ferramenta oficial que permite conectar-se a um MCP Server e testar suas tools, resources e prompts de forma interativa, sem precisar de um modelo de IA. Ele funciona como um Client MCP com interface visual.

O Inspector é a ferramenta mais eficiente para desenvolver e debugar MCP Servers. Ele permite testar rapidamente sem depender do Claude Desktop, acelerando o ciclo de desenvolvimento.

MCP Inspector, ferramenta de teste, interface visual, Client MCP, desenvolvimento rápido.

O MCP Inspector pode ser executado via npx sem instalação permanente. O comando npx @modelcontextprotocol/inspector inicia a ferramenta, que abre uma interface web onde você pode conectar-se ao seu server e explorar suas capacidades.

Instalar e executar o Inspector rapidamente é uma habilidade prática que acelera todo o seu workflow de desenvolvimento MCP. É uma ferramenta que você vai usar constantemente.

npx, @modelcontextprotocol/inspector, interface web, sem instalação permanente, Node.js.

Conectar o Inspector ao seu server envolve especificar o comando para iniciar o server (ex: python server.py), o transporte (geralmente STDIO), e clicar em conectar. O Inspector executa o handshake MCP e lista todas as capabilities disponíveis.

Saber conectar o Inspector ao seu server é o passo fundamental para usá-lo. A conexão revela imediatamente se há problemas de inicialização ou configuração no seu server.

Conexão STDIO, comando de execução, handshake, capabilities, detecção de problemas.

O Inspector permite selecionar qualquer tool listada, preencher seus parâmetros manualmente, e executá-la. O resultado é exibido na interface com detalhes completos: conteúdo retornado, tempo de execução, e qualquer erro que tenha ocorrido.

Testar tools no Inspector é muito mais rápido que testar via Claude. Você pode iterar rapidamente, testar edge cases, e verificar que suas tools funcionam corretamente antes de integrá-las.

Execução manual, preenchimento de parâmetros, visualização de resultado, tempo de execução, iteração rápida.

Analisar respostas no Inspector significa examinar o conteúdo retornado por tools, resources e prompts em formato raw. Você pode ver exatamente o JSON que o server envia, incluindo tipos de conteúdo, metadata, e estrutura da resposta.

Ver as respostas raw permite entender exatamente o que o modelo recebe. Isso é crucial para otimizar a formatação e garantir que as respostas são interpretáveis.

Respostas raw, JSON, tipos de conteúdo, metadata, formatação, análise de output.

O Inspector mostra erros detalhados quando algo dá errado: stack traces de Python, erros de protocolo, timeouts, e problemas de conexão. Combinado com logs do server, permite identificar a causa raiz de qualquer problema rapidamente.

Debugging eficiente é o que separa um desenvolvedor produtivo de um que fica travado por horas. O Inspector é sua ferramenta principal para diagnosticar e resolver problemas em MCP Servers.

Stack traces, erros de protocolo, diagnóstico, causa raiz, correção, ciclo debug-fix-test.