--- title: "Servidores MCP como Ferramentas no CrewAI" description: "Aprenda como integrar servidores MCP como ferramentas nos seus agentes CrewAI usando a biblioteca `crewai-tools`." icon: plug mode: "wide" --- ## Visão Geral O [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) fornece uma maneira padronizada para agentes de IA fornecerem contexto para LLMs comunicando-se com serviços externos, conhecidos como Servidores MCP. O CrewAI oferece **duas abordagens** para integração MCP: ### 🚀 **Novo: Integração DSL Simples** (Recomendado) Use o campo `mcps` diretamente nos agentes para integração perfeita de ferramentas MCP: ```python from crewai import Agent agent = Agent( role="Analista de Pesquisa", goal="Pesquisar e analisar informações", backstory="Pesquisador especialista com acesso a ferramentas externas", mcps=[ "https://mcp.exa.ai/mcp?api_key=sua_chave", # Servidor MCP externo "https://api.weather.com/mcp#get_forecast", # Ferramenta específica do servidor "snowflake", # MCP conectado do catálogo "stripe#list_invoices" # Ferramenta específica de MCP conectado ] ) # Ferramentas MCP agora estão automaticamente disponíveis para seu agente! ``` ### 🔧 **Avançado: MCPServerAdapter** (Para Cenários Complexos) Para casos de uso avançados que requerem gerenciamento manual de conexão, a biblioteca `crewai-tools` fornece a classe `MCPServerAdapter`. Atualmente, suportamos os seguintes mecanismos de transporte: - **HTTPS**: para servidores remotos (comunicação segura via HTTPS) - **Server-Sent Events (SSE)**: para servidores remotos (transmissão de dados unidirecional em tempo real do servidor para o cliente via HTTP) - **Streamable HTTP**: para servidores remotos (comunicação flexível e potencialmente bidirecional via HTTP, geralmente utilizando SSE para streams do servidor para o cliente) ## Tutorial em Vídeo Assista a este tutorial em vídeo para um guia abrangente sobre a integração do MCP com o CrewAI: ## Instalação Antes de começar a usar MCP com `crewai-tools`, é necessário instalar a dependência extra `mcp` do `crewai-tools` com o seguinte comando: ```shell uv pip install 'crewai-tools[mcp]' ``` ## Conceitos Chave & Primeiros Passos A classe `MCPServerAdapter` da `crewai-tools` é a principal forma de conectar-se a um servidor MCP e disponibilizar suas ferramentas aos seus agentes CrewAI. Ela suporta diferentes mecanismos de transporte e simplifica o gerenciamento de conexões. O uso de um gerenciador de contexto Python (`with`) é a **abordagem recomendada** para o `MCPServerAdapter`. Ele lida automaticamente com a abertura e o fechamento da conexão com o servidor MCP. ## Configuração de Conexão O `MCPServerAdapter` suporta várias opções de configuração para personalizar o comportamento da conexão: - **`connect_timeout`** (opcional): Tempo máximo em segundos para aguardar o estabelecimento de uma conexão com o servidor MCP. O padrão é 30 segundos se não especificado. Isso é particularmente útil para servidores remotos que podem ter tempos de resposta variáveis. ```python # Exemplo com timeout personalizado para conexão with MCPServerAdapter(server_params, connect_timeout=60) as tools: # A conexão terá timeout após 60 segundos se não estabelecida pass ``` ```python from crewai import Agent from crewai_tools import MCPServerAdapter from mcp import StdioServerParameters # Para servidor Stdio # Exemplo de server_params (escolha um baseado no seu tipo de servidor): # 1. Servidor Stdio: server_params=StdioServerParameters( command="python3", args=["servers/your_server.py"], env={"UV_PYTHON": "3.12", **os.environ}, ) # 2. Servidor SSE: server_params = { "url": "http://localhost:8000/sse", "transport": "sse" } # 3. Servidor Streamable HTTP: server_params = { "url": "http://localhost:8001/mcp", "transport": "streamable-http" } # Exemplo de uso (descomente e adapte após definir server_params): with MCPServerAdapter(server_params, connect_timeout=60) as mcp_tools: print(f"Available tools: {[tool.name for tool in mcp_tools]}") meu_agente = Agent( role="Usuário de Ferramentas MCP", goal="Utilizar ferramentas de um servidor MCP.", backstory="Posso conectar a servidores MCP e usar suas ferramentas.", tools=mcp_tools, # Passe as ferramentas carregadas para o seu agente reasoning=True, verbose=True ) # ... restante da configuração do seu crew ... ``` Este padrão geral mostra como integrar ferramentas. Para exemplos específicos para cada transporte, consulte os guias detalhados abaixo. ## Filtrando Ferramentas ```python with MCPServerAdapter(server_params, connect_timeout=60) as mcp_tools: print(f"Available tools: {[tool.name for tool in mcp_tools]}") meu_agente = Agent( role="Usuário de Ferramentas MCP", goal="Utilizar ferramentas de um servidor MCP.", backstory="Posso conectar a servidores MCP e usar suas ferramentas.", tools=mcp_tools["tool_name"], # Passe as ferramentas filtradas para o seu agente reasoning=True, verbose=True ) # ... restante da configuração do seu crew ... ``` ## Usando com CrewBase Para usar ferramentas de servidores MCP dentro de uma classe CrewBase, utilize o método `get_mcp_tools`. As configurações dos servidores devem ser fornecidas via o atributo `mcp_server_params`. Você pode passar uma configuração única ou uma lista com múltiplas configurações. ```python @CrewBase class CrewWithMCP: # ... defina o arquivo de configuração de agentes e tasks ... mcp_server_params = [ # Servidor Streamable HTTP { "url": "http://localhost:8001/mcp", "transport": "streamable-http" }, # Servidor SSE { "url": "http://localhost:8000/sse", "transport": "sse" }, # Servidor StdIO StdioServerParameters( command="python3", args=["servers/your_stdio_server.py"], env={"UV_PYTHON": "3.12", **os.environ}, ) ] @agent def your_agent(self): return Agent(config=self.agents_config["your_agent"], tools=self.get_mcp_tools()) # obter todas as ferramentas disponíveis # ... restante da configuração do seu crew ... ``` Quando uma classe é decorada com `@CrewBase`, o ciclo de vida do adaptador é controlado automaticamente: - A primeira chamada a `get_mcp_tools()` cria de forma preguiçosa um `MCPServerAdapter` compartilhado que é reutilizado por todos os agentes do crew. - Após a conclusão de `.kickoff()`, um hook pós-kickoff injetado por `@CrewBase` encerra o adaptador, dispensando qualquer limpeza manual. - Se `mcp_server_params` não estiver definido, `get_mcp_tools()` retorna uma lista vazia, permitindo manter o mesmo fluxo de código com ou sem MCP configurado. Assim, é seguro chamar `get_mcp_tools()` em vários agentes ou habilitar/desabilitar MCP dependendo do ambiente. ### Configuração de Timeout de Conexão Você pode configurar o timeout de conexão para servidores MCP definindo o atributo de classe `mcp_connect_timeout`. Se nenhum timeout for especificado, o padrão é 30 segundos. ```python @CrewBase class CrewWithMCP: mcp_server_params = [...] mcp_connect_timeout = 60 # timeout de 60 segundos para todas as conexões MCP @agent def your_agent(self): return Agent(config=self.agents_config["your_agent"], tools=self.get_mcp_tools()) ``` ```python @CrewBase class CrewWithDefaultTimeout: mcp_server_params = [...] # Nenhum mcp_connect_timeout especificado - usa padrão de 30 segundos @agent def your_agent(self): return Agent(config=self.agents_config["your_agent"], tools=self.get_mcp_tools()) ``` ### Filtragem de Ferramentas Você pode filtrar quais ferramentas estão disponíveis para seu agente passando uma lista de nomes de ferramentas para o método `get_mcp_tools`. ```python @agent def another_agent(self): return Agent( config=self.agents_config["your_agent"], tools=self.get_mcp_tools("tool_1", "tool_2") # obter ferramentas específicas ) ``` A configuração de timeout se aplica a todas as chamadas de ferramentas MCP dentro do crew: ```python @CrewBase class CrewWithCustomTimeout: mcp_server_params = [...] mcp_connect_timeout = 90 # timeout de 90 segundos para todas as conexões MCP @agent def filtered_agent(self): return Agent( config=self.agents_config["your_agent"], tools=self.get_mcp_tools("tool_1", "tool_2") # ferramentas específicas com timeout personalizado ) ``` ## Explore Integrações MCP Conecte-se a servidores MCP locais via entrada/saída padrão. Ideal para scripts e executáveis locais. Integre com servidores MCP remotos usando Server-Sent Events para streaming de dados em tempo real. Utilize HTTP Streamable para uma comunicação robusta com servidores MCP remotos. Agregue ferramentas de vários servidores MCP simultaneamente usando um único adaptador. Revise práticas importantes de segurança para integração MCP e mantenha seus agentes protegidos. Confira este repositório para demonstrações completas e exemplos de integração MCP com CrewAI! 👇 Demo MCP do CrewAI ## Segurança ao Usar MCP Sempre assegure-se de confiar no servidor MCP antes de utilizá-lo. #### Aviso de Segurança: Ataques de DNS Rebinding Transportes SSE podem ser vulneráveis a ataques de DNS rebinding se não forem devidamente protegidos. Para prevenir isso: 1. **Sempre valide os cabeçalhos Origin** das conexões SSE recebidas para garantir que venham de fontes esperadas 2. **Evite vincular servidores a todas as interfaces de rede** (0.0.0.0) quando executando localmente – faça o bind apenas para localhost (127.0.0.1) 3. **Implemente autenticação adequada** para todas as conexões SSE Sem essas proteções, invasores podem usar DNS rebinding para interagir com servidores MCP locais via sites remotos. Para mais detalhes, consulte a [documentação de Segurança de Transporte da MCP da Anthropic](https://modelcontextprotocol.io/docs/concepts/transports#security-considerations). ### Limitações - **Primitivas Suportadas**: Atualmente, o `MCPServerAdapter` suporta principalmente a adaptação de `tools` MCP. Outras primitivas MCP como `prompts` ou `resources` não são integradas diretamente como componentes CrewAI através deste adaptador por enquanto. - **Manipulação de Saída**: O adaptador normalmente processa a saída principal de texto de uma ferramenta MCP (por exemplo, `.content[0].text`). Saídas complexas ou multimodais podem exigir tratamento customizado caso não se encaixem nesse padrão.