Tutorial de Model Context Protocol em Python: crie seu primeiro servidor MCP
Aprenda Model Context Protocol em Python com um tutorial prático de primeiro servidor, os conceitos centrais do MCP e o caminho mais rápido de scripts personalizados a ferramentas de IA reutilizáveis.
A maior parte do conteúdo sobre MCP para na grande ideia: uma forma padrão de conectar ferramentas de IA a sistemas externos. Isso é útil, mas não ajuda muito quando você está diante de um projeto Python se perguntando o que construir primeiro. Este guia segue o caminho prático. Se você quer entender Model Context Protocol Python bem o suficiente para entregar algo, o melhor ponto de partida é um servidor pequeno que exponha uma ferramenta, um recurso e um caso de uso claro.
Esse ângulo tem forte intenção de busca neste momento porque os desenvolvedores estão superando os experimentos genéricos de “agentes de IA” e fazendo uma pergunta mais específica: como conecto modelos a arquivos, APIs e lógica de negócio reais sem inventar uma camada de cola personalizada toda vez? Se você ainda está construindo seu primeiro agente, comece pelo nosso guia Construindo agentes de IA com Python.
Por que este tema está em alta agora
O MCP saiu de uma conversa de protocolo de nicho para o fluxo de trabalho principal dos desenvolvedores.
A Anthropic anunciou em dezembro de 2025 que o MCP estava sendo doado à Agentic AI Foundation com o apoio da Anthropic, OpenAI, Microsoft, Google, AWS, Cloudflare, Block e Bloomberg. No mesmo anúncio, a Anthropic afirmou que o MCP tinha mais de 10.000 servidores públicos ativos e havia sido adotado por produtos como ChatGPT, Cursor, Gemini, Microsoft Copilot e VS Code. Isso importa porque transforma o MCP de uma ideia interessante em um canal de distribuição.
Para os desenvolvedores Python, o momento é especialmente bom. A página oficial de SDK lista o Python como um SDK de Nível 1, o que sinaliza forte compromisso de manutenção e completude de funcionalidades. Em outras palavras, o stack Python para MCP não é mais uma palavra-chave especulativa. Ele corresponde a um conjunto de ferramentas que já tem documentação oficial, um SDK ativo e padrões de implementação claros.
O que o MCP realmente oferece aos desenvolvedores Python
A maneira mais simples de pensar no MCP é esta: ele padroniza a fronteira entre uma aplicação de IA e o contexto ou as ações que ela pode usar.
O SDK oficial de Python descreve três blocos fundamentais de construção de servidores:
- tools para ações que o modelo pode invocar
- resources para contexto somente leitura que a aplicação pode carregar
- prompts para modelos de interação reutilizáveis
Essa distinção é importante.
Tools
As tools são a parte ativa da sua integração. Elas podem executar código, chamar APIs, gravar dados ou disparar efeitos colaterais. Se o seu assistente precisa criar um chamado, consultar uma API de clima ou iniciar um job, isso pertence a uma tool.
Resources
Os resources são a parte passiva. Comportam-se mais como endpoints GET em uma API tradicional. Expõem contexto útil, como documentação, configuração ou dados de referência, sem alterar nada.
Prompts
Os prompts permitem empacotar instruções reutilizáveis ou padrões de interação para que os clientes possam invocá-los de forma estruturada.
Essa separação é o verdadeiro valor. Antes do MCP, muitas equipes empurravam tudo para um esquema de tool superdimensionado ou apenas para engenharia de prompts. Com este protocolo, a arquitetura fica mais fácil de raciocinar e de reutilizar entre clientes.
Na minha experiência implantando padrões de chamada de ferramentas na Codiste, essa distinção entre tools e resources teria nos poupado um tempo significativo de refatoração. Quando construí um sistema de Document AI usando transformers ajustados, inicialmente expusemos o parsing de documentos tanto como uma ação quanto como uma fonte de dados pela mesma interface, o que gerou confusão sobre quando o modelo deveria chamá-lo versus quando o contexto deveria ser pré-carregado. Uma separação em nível de protocolo como a que o MCP impõe teria evitado isso completamente.
Construa primeiro um servidor MCP pequeno
O início rápido do SDK oficial de Python usa o FastMCP, que é o lugar certo para começar. Ele mantém os detalhes do protocolo fora do caminho para que você possa se concentrar na capacidade real que deseja expor.
Instale-o com uv ou pip:
1
uv add "mcp[cli]"
ou:
1
pip install "mcp[cli]"
Então comece com um servidor mínimo:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("Demo", json_response=True)
@mcp.tool()
def add(a: int, b: int) -> int:
"""Add two numbers."""
return a + b
@mcp.resource("greeting://{name}")
def greeting(name: str) -> str:
"""Return a greeting resource."""
return f"Hello, {name}!"
@mcp.prompt()
def greet_user(name: str) -> str:
return f"Write a friendly greeting for {name}."
if __name__ == "__main__":
mcp.run(transport="streamable-http")
Esse pequeno exemplo ensina o modelo que você deve seguir para quase todo servidor real:
- defina a capacidade
- classifique-a como tool, resource ou prompt
- execute o servidor com um transporte padrão
- conecte-o a partir de uma aplicação host ou inspector
Este é o ângulo prático de palavra-chave que torna Model Context Protocol Python digno de ser visado. Quem pesquisa geralmente não quer um ensaio sobre o protocolo. Quer um primeiro servidor funcional que possa adaptar hoje.
Quando o MCP é melhor que a cola de ferramentas personalizada
Se você só precisa de um auxiliar privado para uma aplicação, uma chamada direta ao SDK pode ser suficiente. Mas o MCP começa a vencer assim que reutilização e interoperabilidade importam.
Use o MCP quando:
- a mesma capacidade deve funcionar em vários clientes de IA
- você quer um contrato limpo entre sua aplicação e suas ferramentas
- sua equipe precisa que tools, resources e prompts permaneçam distintos
- você espera que a superfície de integração cresça com o tempo
Evite a superengenharia quando:
- você está testando um protótipo descartável
- a lógica está fortemente acoplada a uma única aplicação e não será reutilizada
- você ainda não sabe se a capacidade merece uma interface formal
A percepção chave é que o MCP não trata apenas do acesso ao modelo. Trata de empacotar contexto e ações de uma forma que outros clientes possam entender. Essa é uma história de longo prazo mais sólida do que escrever repetidamente wrappers pontuais de chamada de função. Por exemplo, você poderia expor um sistema RAG como um resource do MCP para que qualquer agente possa consultar sua base de conhecimento.
Melhores práticas para um começo pronto para produção
O README oficial do SDK e a documentação de conceitos de servidor apontam para alguns hábitos que vale a pena adotar cedo.
Mantenha as tools restritas
Não crie uma única tool chamada do_everything. Tools menores são mais fáceis de os modelos escolherem corretamente e mais fáceis de você testar. Quando construí fluxos de trabalho de agentes de IA para segmentação de imagens usando ControlNet, aprendi isso da maneira difícil – uma tool ampla “process_image” causava roteamento incorreto constante, enquanto dividi-la em “segment_image”, “apply_controlnet” e “postprocess_output” deu ao modelo limites de decisão claros.
Coloque dados somente leitura em resources
Se algo deve ser carregado como contexto em vez de executado como uma ação, exponha-o como um resource. Isso mantém a semântica clara.
Use contexto apenas onde ajuda
O SDK de Python suporta injeção de contexto para tools, incluindo relatórios de progresso e acesso a recursos gerenciados pelo ciclo de vida. Isso é poderoso, mas você não precisa disso em todo endpoint.
Comece com um transporte e um cliente
O SDK suporta transportes como stdio, SSE e Streamable HTTP. Escolha um caminho, comprove o fluxo de trabalho e depois expanda. O OpenAI Agents SDK é um cliente que funciona bem com servidores MCP.
Teste com ferramentas estilo inspector
O início rápido aponta explicitamente para o MCP Inspector como forma de testar seu servidor antes de conectá-lo a uma aplicação host completa. É um bom hábito porque isola problemas de protocolo de problemas de produto.
Considerações finais
A razão pela qual Model Context Protocol Python tem valor real de SEO neste momento é simples: combina o impulso da tendência com intenção de implementação imediata. Os desenvolvedores ouvem falar do MCP nos principais produtos de IA e então se voltam para buscar o caminho Python mais rápido para usá-lo eles mesmos.
Se esse é o seu objetivo, não comece com uma plataforma de agentes completa. Comece com um servidor MCP útil dentro de um projeto Python que você já entende. Exponha uma tool pequena, adicione um resource, teste-o com o inspector e conecte-o ao cliente que você realmente usa.
Esse fluxo de trabalho ensina o protocolo mais rápido do que a leitura abstrata jamais conseguirá. Depois que funcionar, você pode crescer de um único servidor local para uma interface reutilizável para ferramentas internas, sistemas de documentação, fluxos de trabalho de suporte ou automação para desenvolvedores.
Se você quer um próximo passo concreto esta semana, construa um pequeno servidor MCP em torno de uma tarefa que você já repete manualmente. Esse costuma ser o caminho mais curto da curiosidade para algo genuinamente útil.
Publicações relacionadas
- Tutorial de OpenAI Agents SDK em Python - Crie fluxos de trabalho multiagente que consomem tools e resources do MCP
- Construindo agentes de IA com Python - Entenda o loop do agente, o uso de ferramentas e os padrões de memória que o MCP padroniza
- RAG com Python: Retrieval-Augmented Generation - Construa um sistema de recuperação de conhecimento que você possa expor como um resource do MCP
Fontes
Machine Learning Engineer at Codiste, specializing in Generative AI, NLP, and Computer Vision. Building production AI systems with Python.