Construindo Seu Primeiro Agente de IA com MCP: Um Guia Passo a Passo

Se você ouviu falar sobre o Protocolo de Contexto de Modelo (MCP), mas não tem certeza de como construir algo com ele, este guia é para você.

No meu artigo anterior, expliquei o que é o MCP e por que ele é importante. Se você ainda não leu, recomendo começar por lá.

Entender os conceitos é uma coisa. Construir um agente de IA que realmente usa o MCP é outra.

Neste guia, você construirá um agente de IA simples que se comunica com um servidor MCP, usa ferramentas externas e retorna respostas úteis. Mais importante, você entenderá por que cada componente existe e como eles funcionam juntos.

No final, você terá uma base sólida que pode ser estendida para aplicações de IA mais avançadas.

O que você vai construir

Imagine perguntar a um assistente de IA:

"Qual é o clima em Toronto hoje?"

Em vez de adivinhar a resposta, a IA contata uma ferramenta de clima, recupera informações reais e responde de forma natural.

Essa interação inteira é possível através do Protocolo de Contexto de Modelo.

Nosso agente de IA simples irá:

• Receber a pergunta de um usuário
• Decidir se uma ferramenta é necessária
• Chamar um servidor MCP
• Receber dados estruturados
• Gerar uma resposta final

Embora usaremos um exemplo de clima, essa mesma arquitetura é utilizada para:

• Assistentes de codificação de IA
• Agentes de suporte ao cliente
• Aplicações de busca de documentos
• Assistentes de banco de dados
• Chatbots internos de empresas

Pré-requisitos

Antes de começar, certifique-se de que você tem:

• Python 3.11 ou posterior
• Claude Desktop
• Visual Studio Code (recomendado)
• Conhecimento básico de Python

Também usaremos o SDK Python oficial do MCP.

Entendendo a Arquitetura

Antes de escrever código, é útil entender como os pedidos fluem através de uma aplicação MCP.

┌──────────┐
│   Usuário │
└────┬─────┘
     │
     ▼
┌───────────────┐
│ Claude Desktop│
└────┬──────────┘
     │
     ▼
┌───────────────┐
│  Cliente MCP  │
└────┬──────────┘
     │
     ▼
┌───────────────┐
│  Servidor MCP │
└────┬──────────┘
     │
     ▼
┌───────────────┐
│ Ferramenta    │
└────┬──────────┘
     │
     ▼
 Dados Estruturados
     │
     ▼
 Claude gera
 resposta natural
     │
     ▼
     Usuário

Cada componente tem uma responsabilidade específica.

Passo 1: Criar um Projeto

Crie uma nova pasta de projeto.

mkdir agente-clima
cd agente-clima

Crie um ambiente virtual.

python -m venv .venv

Ative-o.

Windows

.venv\Scripts\activate

macOS/Linux

source .venv/bin/activate

Instale o SDK do MCP.

pip install mcp

Passo 2: Construa Seu Primeiro Servidor MCP

Todo servidor MCP expõe uma ou mais ferramentas.

Uma ferramenta é simplesmente uma função que os modelos de IA podem chamar sempre que precisam de informações ou precisam realizar uma ação.

Exemplos incluem:

• Consulta de clima
• Calculadora
• Leitor de arquivos
• Consulta a banco de dados SQL
• Envio de e-mail

Vamos construir uma ferramenta de clima.

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("Servidor de Clima")

@mcp.tool()
def obter_clima(cidade: str):
    return f"O clima em {cidade} é ensolarado e 24°C."

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

Embora este exemplo retorne dados codificados, a mesma estrutura funciona com APIs reais.

Passo 3: Entendendo o Código

Vamos analisar o que aconteceu.

mcp = FastMCP("Servidor de Clima")

Criando um servidor MCP.

@mcp.tool()

Registra uma função Python como uma ferramenta MCP.

def obter_clima(cidade: str):

Define a ferramenta que Claude pode chamar.

mcp.run()

Inicia o servidor MCP.

Uma vez que o servidor está em execução, Claude descobre automaticamente todas as ferramentas registradas.

Você nunca diz explicitamente a Claude quando usar a ferramenta.

Claude decide isso com base no pedido do usuário.

Passo 4: Conectar o Claude Desktop

O Claude Desktop precisa saber onde seu servidor MCP está em execução.

Atualize sua configuração do MCP.

{
  "mcpServers": {