LangGraph + MCP: Construindo um Sistema Multi-Agente Supervisor

Por Que Este Padrão É Importante

A maioria dos tutoriais do LangGraph para em agentes únicos. Um único agente que faz pesquisa, escreve código e formata um relatório está equilibrando três funções — e à medida que a lista de tarefas cresce, o prompt cresce junto. O padrão de supervisor resolve isso: um LLM orquestrador não faz nada além de decidir qual especialista recebe a próxima tarefa, enquanto cada especialista opera com um prompt focado e minimalista.

Adicione o MCP (Modelo de Protocolo de Contexto) a essa imagem e você obtém um segundo nível de separação. Em vez de codificar ferramentas em cada agente, você as serve de um endpoint HTTP/SSE ao vivo. Atualize, versionar ou troque um servidor de ferramentas sem tocar no código do seu agente. Essa é a arquitetura que este guia constrói.

A Effloow Lab verificou toda a cadeia de pacotes no Python 3.12 macOS: langchain-mcp-adapters==0.2.2, langgraph-supervisor==0.0.31, mcp==1.27.0 e langgraph==1.1.10 instalados juntos sem problemas. Verificações da superfície da API confirmaram todos os caminhos de importação e assinaturas de construtores documentados aqui. Veja data/lab-runs/langgraph-mcp-poc.md para notas completas do PoC.

Conceitos Centrais

As Três Camadas

LangGraph fornece o runtime do gráfico de estado. Cada agente é um StateGraph compilado com um verificador — o estado persiste entre as etapas através de um MemorySaver (em memória) ou um armazenamento de produção como PostgreSQL.

langchain-mcp-adapters é o pacote de ponte. Ele converte esquemas de ferramentas MCP em objetos BaseTool compatíveis com langchain_core que qualquer nó do LangGraph pode chamar. MultiServerMCPClient gerencia conexões com um ou vários servidores MCP através de stdio, sse, streamable_http ou websocket transports.

langgraph-supervisor fornece create_supervisor() — uma fábrica que envolve agentes especialistas em um gráfico de roteamento. O LLM supervisor recebe uma tarefa, escolhe qual agente chamar usando uma ferramenta de transferência, e esse agente executa até retornar o controle. O ciclo se repete até que o supervisor decida que o trabalho está concluído.

Por Que MCP Em Vez de Ferramentas Codificadas?

Com ferramentas codificadas, cada mudança de ferramenta significa reimplantar seu agente. Com um servidor MCP, você implanta uma atualização de ferramenta uma vez e cada agente conectado a pega imediatamente. O pacote langchain-mcp-adapters converte o esquema de ferramenta JSON-RPC do MCP no formato BaseTool do LangChain de forma transparente — seu código de agente nunca percebe a diferença.

O livro completo de 2026 da FreeCodeCamp sobre LangGraph+MCP+A2A fixou mcp==1.26.0 e langgraph==1.1.0, sinalizando que essas famílias de versões são estáveis para builds de produção. As versões mais recentes (mcp==1.27.0, langgraph==1.1.10) são compatíveis com a API.

Pré-requisitos

Python 3.11+
pip install langchain-mcp-adapters==0.2.2 langgraph-supervisor==0.0.31
pip install langchain-openai  # ou langchain-anthropic para seu LLM

O SDK mcp (1.27.0) é instalado automaticamente como uma dependência do langchain-mcp-adapters. O pacote langgraph (1.1.10) pode já estar presente se você tiver o langchain instalado.

Você também precisará de uma chave de API da OpenAI ou Anthropic para as chamadas do LLM.

Passo 1: Crie um Servidor de Ferramentas MCP com FastMCP

O SDK MCP envia FastMCP, um construtor de servidor baseado em decoradores. Crie tool_server.py:

from mcp.server.fastmcp import FastMCP

mcp_app = FastMCP(
    "research-tools",
    host="127.0.0.1",
    port=8001,
    streamable_http_path="/mcp",
    sse_path="/sse",
)

@mcp_app.tool()
def web_search(query: str) -> str:
    """Pesquise na web e retorne um resumo dos resultados."""
    # Em produção: chame uma API de busca real (Serper, Tavily, Brave, etc.)
    return f"Resultados da pesquisa para '{query}': [conecte sua API de busca aqui]"

@mcp_app.tool()
def read_file(path: str) -> str:
    """Leia o conteúdo de um arquivo local pelo caminho absoluto."""
    try:
        with open(path) as f:
            return f.read()
    except FileNotFoundError:
        return f"Arquivo não encontrado: {path}"

if __name__ == "__main__":
    mcp_app.run(transport="streamable-http")

Inicie-o com:

python tool_server.py
# Servindo em http://127.0.0.1:8001/mcp

O FastMCP gera automaticamente o esquema JSON-RPC do MCP a partir das assinaturas e docstrings das suas funções. Nenhum código boilerplate necessário.

Passo 2: Crie Agentes Especialistas Com Ferramentas MCP

Agentes especialistas conectam-se ao servidor de ferramentas via