Protocolo MCP (Model Context Protocol) Tutorial: Guia Prático

Agentes de IA

Protocolo MCP (Model Context Protocol) Tutorial: Guia Prático

O protocolo mcp model context protocol tutorial mostra na prática como implementar o Model Context Protocol (MCP) da Anthropic. Você vai criar um servidor MCP em Python, conectar um cliente e entender por que Block e Apollo já adotaram o protocolo em produção. Este guia cobre da arquitetura ao código funcional.

O que é o Model Context Protocol (MCP)?

O Model Context Protocol (MCP) é um padrão aberto que conecta modelos de linguagem a fontes externas de dados e ferramentas, eliminando a necessidade de integrações customizadas. A Anthropic anunciou o MCP em novembro de 2024 como uma solução para o problema de isolamento dos LLMs — modelos de linguagem sabem muito, mas não têm acesso nativo a sistemas externos.

A analogia mais usada para entender o model context protocol é compará-lo a um "USB-C para IA". O USB-C padronizou a conexão de periféricos a computadores — antes cada dispositivo exigia um cabo diferente. O MCP faz o mesmo com a comunicação entre LLMs e sistemas externos: unifica em um único protocolo o que antes exigia dezenas de integrações manuais.

Antes do MCP, cada ferramenta exigia código customizado. O MCP substitui esse modelo por um protocolo comum onde o LLM descobre dinamicamente quais ferramentas estão disponíveis.

A especificação do MCP, mantida na documentação oficial, define três blocos fundamentais: Resources (dados que podem ser consumidos), Tools (funções executáveis que o LLM invoca) e Prompts (templates reutilizáveis de interação). Essas capacidades são publicadas pelo servidor e descobertas pelo cliente no momento da conexão — não existe contrato fixo pré-definido.

Como o MCP funciona: arquitetura cliente-servidor

O MCP adota arquitetura cliente-servidor com três camadas — hosts, clients e servers — que se comunicam via transporte STDIO ou SSE. Cada camada tem um papel específico no fluxo de comunicação:

Hosts são as aplicações que iniciam a conexão. Claude Desktop, IDEs como Zed e VS Code, ou agentes de IA personalizados entram nessa categoria. O host é quem "precisa" de contexto externo para responder ao usuário. Clients são conectores internos que mantêm uma conexão dedicada com cada servidor — dentro de um host, cada servidor MCP tem seu próprio client. Servers são sistemas leves, geralmente processos independentes, que expõem recursos, ferramentas e prompts específicos.

O fluxo começa quando o host precisa de dados que não estão no treinamento do modelo. O cliente MCP negocia a conexão com o servidor — via STDIO (processo filho executado localmente) ou SSE (requisição HTTP para um servidor remoto). Uma vez conectado, o servidor publica suas capacidades e o cliente pode invocá-las sob demanda.

Um único host pode se conectar a múltiplos servidores simultaneamente. Um agente de IA pode, na mesma conversa, consultar arquivos locais, pesquisar no GitHub e acessar um banco PostgreSQL — cada fonte vindo de um servidor diferente.

Pré-requisitos para implementar o MCP

Para implementar um servidor MCP em Python você precisa de Python 3.10+, uv e o SDK oficial do MCP. A lista de requisitos é enxuta:

  1. Python 3.10 ou superior — versão mínima exigida pelo SDK Python oficial.
  2. uv — gerenciador de projetos Python mais rápido que pip/venv, recomendado pelo quickstart oficial.
  3. SDK Python do MCP — pacote mcp instalável via uv add "mcp[cli]" ou pip install mcp.

O SDK Python oficial está hospedado na organização modelcontextprotocol no GitHub e oferece o FastMCP, uma abstração de alto nível que permite criar servidores com poucas linhas de código. A organização mantém SDKs oficiais em TypeScript, Java, Kotlin, C#, Go, PHP, Ruby, Rust e Swift — você pode implementar servidores na linguagem mais adequada ao seu projeto.

O MCP se integra naturalmente a frameworks como LangGraph e CrewAI. Para entender o ecossistema completo, veja o guia de Orquestração de Agentes de IA: Arquitetura, Padrões e Melhores Práticas.

Passo a passo: configurando um servidor MCP em Python

Use o FastMCP para criar um servidor de clima que expõe tools e resources com menos de 30 linhas de código. Vamos construir o servidor passo a passo.

1. Inicialize o projeto

uv init mcp-weather-server
cd mcp-weather-server
uv add "mcp[cli]"

O comando uv init cria a estrutura do projeto, e uv add instala o SDK do MCP com suporte à CLI. O pacote mcp[cli] inclui o comando mcp run que usaremos para testar o servidor.

2. Crie o servidor com FastMCP

Crie o arquivo weather_server.py:

from mcp.server.fastmcp import FastMCP

# Inicializa o servidor MCP
mcp = FastMCP("WeatherServer")

@mcp.tool()
def get_temperature(city: str) -> str:
    """Retorna a temperatura atual de uma cidade.
    
    Args:
        city: Nome da cidade (ex: São Paulo, Rio de Janeiro)
    """
    temperatures = {
        "São Paulo": "22°C",
        "Rio de Janeiro": "30°C",
        "Brasília": "25°C",
        "Curitiba": "18°C",
        "Recife": "28°C"
    }
    temp = temperatures.get(city, "não encontrada")
    return f"A temperatura atual em {city} é {temp}"

@mcp.resource("weather://cidades")
def list_cities() -> str:
    """Lista todas as cidades disponíveis para consulta."""
    return "São Paulo, Rio de Janeiro, Brasília, Curitiba, Recife"

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

O decorator @mcp.tool() registra get_temperature como uma ferramenta executável — o LLM pode invocá-la quando o usuário perguntar sobre clima. O decorator @mcp.resource() expõe dados que o cliente pode consultar como um recurso identificado por URI.

3. Teste o servidor

mcp run weather_server.py

Esse comando inicia o servidor em modo STDIO e publica a tool get_temperature e o resource weather://cidades. O servidor fica aguardando conexão de um cliente MCP para começar a processar requisições.

Conectando um cliente MCP ao servidor

Configure o Claude Desktop via claude_desktop_config.json para conectar automaticamente ao seu servidor MCP local. Com o servidor rodando, o próximo passo é conectar um cliente.

Configuração no Claude Desktop

No arquivo de configuração do Claude Desktop (claude_desktop_config.json), adicione:

{
  "mcpServers": {
    "weather": {
      "command": "python",
      "args": ["/caminho/completo/para/weather_server.py"]
    }
  }
}

Após reiniciar o Claude Desktop, ele inicia automaticamente o servidor MCP como processo filho (transporte STDIO). O protocolo negocia a conexão, o servidor publica suas capacidades, e o cliente fica pronto para uso.

Agora, ao perguntar "Qual a temperatura em São Paulo?" no Claude, o modelo pode decidir invocar a tool get_temperature que criamos. A resposta virá do servidor, não de dados de treinamento — contexto real, atualizado e controlado por você.

Configuração programática com Anthropic SDK

Para integração via código, o SDK Python da Anthropic oferece suporte direto a chamadas MCP. Você pode conectar seu servidor programaticamente sem depender do Claude Desktop:

from anthropic import Anthropic

client = Anthropic()
# O cliente Anthropic pode ser configurado 
# para usar servidores MCP personalizados

Múltiplos servidores simultâneos

A configuração JSON permite conectar vários servidores ao mesmo tempo. Cada entrada em mcpServers representa um servidor diferente, e o Claude Desktop gerencia todas as conexões simultaneamente. Você pode ter servidores de arquivos, banco de dados e clima rodando lado a lado — o LLM decide qual usar baseado no contexto.

Ferramentas e recursos (tools) no MCP

O MCP define três tipos de capacidades que um servidor pode expor: Resources, Tools e Prompts. Cada uma atende a um propósito diferente na comunicação entre LLM e mundo externo.

Resources expõem dados que o cliente pode consumir — arquivos, registros de banco, resultados de API. São identificados por URIs padronizados e funcionam como uma camada de dados universal. Um resource pode ser file:///relatorios/vendas.pdf ou weather://cidades.

Tools são funções executáveis que o LLM pode invocar com base no contexto da conversa. Cada tool tem um schema JSON que define parâmetros de entrada (nome, tipo, descrição) e a estrutura da resposta. O modelo analisa o schema e decide se deve chamar a tool — e com quais argumentos.

Prompts são templates reutilizáveis de interação. Um prompt pode ser "Resuma o documento atual" ou "Traduza este texto para inglês". Eles fornecem contexto pré-formatado que guia o comportamento do LLM em cenários específicos.

A especificação do MCP define que essas três capacidades são descobertas dinamicamente. Quando o cliente se conecta ao servidor, ele recebe a lista completa de resources, tools e prompts disponíveis. Não existe contrato fixo — o cliente descobre as capacidades no momento da conexão e pode se adaptar automaticamente a mudanças.

MCP vs APIs tradicionais: principais diferenças

MCP difere de APIs tradicionais por ser um protocolo padronizado com descoberta dinâmica de capacidades, em vez de endpoints fixos e integrações customizadas. Essa diferença muda radicalmente a forma como sistemas de IA se conectam a ferramentas.

APIs tradicionais exigem integração manual para cada provedor — um adapter para GitHub, outro para Slack, outro para PostgreSQL. Cada API tem endpoint, autenticação e schema próprios. Adicionar uma nova ferramenta significa código e manutenção novos.

MCP substitui todas por um protocolo único. O servidor publica suas capacidades (tools, resources, prompts) em formato padronizado. O cliente descobre o que está disponível dinamicamente — sem documentação externa ou contratos pré-negociados.

O anúncio oficial da Anthropic destaca que "em vez de manter conectores separados para cada fonte de dados, os desenvolvedores podem construir contra um protocolo padrão". Essa abordagem reduz drasticamente a complexidade de manutenção e permite que novos servidores sejam adicionados sem modificar o código do cliente.

Na prática, isso significa que um mesmo cliente MCP pode interagir com servidores de domínios completamente diferentes — financeiro, bancos de dados, arquivos, comunicação — usando o mesmo mecanismo de descoberta e invocação. É o equivalente a ter uma única chave USB-C que funciona com monitor, teclado, disco e carregador.

Casos de uso reais do MCP

Empresas como Block, Apollo, Zed, Replit e Codeium usam MCP em produção desde o anúncio do protocolo em novembro de 2024. Cada uma encontrou um caso de uso específico onde o protocolo resolve problemas reais de integração.

Block (Square/CashApp) usa MCP para conectar agentes a sistemas financeiros e de pagamento. Apollo integrou MCP para dar a LLMs acesso contextual a gráficos e dados de engenharia. Zed implementou MCP em seu editor de código, permitindo que a IA acesse arquivos do projeto e execute comandos Git.

Replit usa MCP para conectar agentes de IA a ambientes de desenvolvimento completos. O protocolo permite que o modelo crie, leia e modifique arquivos no ambiente de execução do Replit. Codeium adotou MCP como mecanismo principal de integração com ferramentas externas de desenvolvimento.

No repositório oficial de servidores MCP, mantido na organização modelcontextprotocol do GitHub, você encontra servidores de referência prontos para uso:

  • Filesystem: acesso seguro a arquivos e diretórios locais
  • Git: operações de repositório (commit, push, log)
  • Memory: armazenamento persistente de contexto entre sessões
  • PostgreSQL: consultas SQL diretas em banco de dados
  • Slack: envio e leitura de mensagens em canais
  • Fetch: requisições HTTP para APIs externas

A comunidade contribui com centenas de servidores adicionais — cobrindo desde bancos NoSQL até serviços cloud como AWS, GCP e Azure. Qualquer sistema que tenha uma API pode ser encapsulado como servidor MCP.

Perguntas Frequentes sobre MCP

MCP é open source?

Sim, o MCP é completamente open source. A Anthropic lançou o protocolo em novembro de 2024 sob uma licença permissiva. Todo o código — SDKs, servidores de referência e ferramentas — está disponível na organização modelcontextprotocol no GitHub, que reúne a comunidade em torno do protocolo.

MCP funciona com qualquer LLM ou só com Claude?

MCP foi projetado como protocolo aberto e agnóstico de modelo. Qualquer LLM pode implementar o lado cliente. Embora a Anthropic tenha criado e lançado o MCP, a especificação é neutra — empresas como Block e Replit usam o protocolo com diferentes provedores de IA, não apenas Claude.

Preciso usar Python para MCP?

Não. O MCP tem SDKs oficiais para Python, TypeScript, Java, Kotlin, C#, Go, PHP, Ruby, Rust e Swift. Você implementa servidores e clientes na linguagem do seu projeto. Python é o mais comum para prototipagem com FastMCP, mas cenários de produção em TypeScript ou Go são igualmente suportados.

MCP já está pronto para produção?

Sim. Block, Apollo, Zed, Replit e Codeium usam MCP em produção desde novembro de 2024. A especificação está estável, os SDKs estão maduros (o Python SDK tem mais de 22 mil estrelas no GitHub) e o ecossistema conta com centenas de servidores comunitários. Adoção continua crescendo com LangChain e Sourcegraph integrando o protocolo.

Qual a diferença entre MCP e plugins?

MCP é um protocolo aberto e padronizado — qualquer um pode criar servidores sem depender de SDK proprietário ou aprovação de plataforma. Plugins são integrações específicas de cada ecossistema (OpenAI, VS Code, Chrome). MCP permite descoberta dinâmica de capacidades; plugins exigem contratos de API fixos e implementação customizada por provedor.

Próximos passos

Com um servidor funcional rodando e o cliente configurado, você pode explorar cenários mais avançados: servidores com autenticação, transporte remoto via SSE e servidores compostos que agregam múltiplas fontes. O entendimento do protocolo mcp model context protocol tutorial é o primeiro passo para criar agentes que realmente interagem com o ambiente ao redor.