mirror of
https://github.com/crewAIInc/crewAI.git
synced 2026-01-10 16:48:30 +00:00
Add pt-BR docs translation (#3039)
* docs: add pt-br translations Powered by a CrewAI Flow https://github.com/danielfsbarreto/docs_translator * Update mcp/overview.mdx brazilian docs Its en-US counterpart was updated after I did a pass, so now it includes the new section about @CrewBase
This commit is contained in:
Daniel Barreto
64
docs/pt-BR/mcp/multiple-servers.mdx
Normal file
64
docs/pt-BR/mcp/multiple-servers.mdx
Normal file
@@ -0,0 +1,64 @@
|
||||
---
|
||||
title: Conectando a Múltiplos Servidores MCP
|
||||
description: Saiba como usar o MCPServerAdapter no CrewAI para conectar-se simultaneamente a múltiplos servidores MCP e agregar suas ferramentas.
|
||||
icon: layer-group
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
O `MCPServerAdapter` em `crewai-tools` permite que você conecte-se a vários servidores MCP simultaneamente. Isso é útil quando seus agentes precisam acessar ferramentas distribuídas entre diferentes serviços ou ambientes. O adaptador agrega as ferramentas de todos os servidores especificados, tornando-as disponíveis para seus agentes CrewAI.
|
||||
|
||||
## Configuração
|
||||
|
||||
Para conectar-se a múltiplos servidores, você fornece uma lista de dicionários de parâmetros de servidor para o `MCPServerAdapter`. Cada dicionário na lista deve definir os parâmetros para um servidor MCP.
|
||||
|
||||
Os tipos de transporte suportados para cada servidor na lista incluem `stdio`, `sse` e `streamable-http`.
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew, Process
|
||||
from crewai_tools import MCPServerAdapter
|
||||
from mcp import StdioServerParameters # Needed for Stdio example
|
||||
|
||||
# Define parameters for multiple MCP servers
|
||||
server_params_list = [
|
||||
# Streamable HTTP Server
|
||||
{
|
||||
"url": "http://localhost:8001/mcp",
|
||||
"transport": "streamable-http"
|
||||
},
|
||||
# SSE Server
|
||||
{
|
||||
"url": "http://localhost:8000/sse",
|
||||
"transport": "sse"
|
||||
},
|
||||
# StdIO Server
|
||||
StdioServerParameters(
|
||||
command="python3",
|
||||
args=["servers/your_stdio_server.py"],
|
||||
env={"UV_PYTHON": "3.12", **os.environ},
|
||||
)
|
||||
]
|
||||
|
||||
try:
|
||||
with MCPServerAdapter(server_params_list) as aggregated_tools:
|
||||
print(f"Available aggregated tools: {[tool.name for tool in aggregated_tools]}")
|
||||
|
||||
multi_server_agent = Agent(
|
||||
role="Versatile Assistant",
|
||||
goal="Utilize tools from local Stdio, remote SSE, and remote HTTP MCP servers.",
|
||||
backstory="An AI agent capable of leveraging a diverse set of tools from multiple sources.",
|
||||
tools=aggregated_tools, # All tools are available here
|
||||
verbose=True,
|
||||
)
|
||||
|
||||
... # Your other agent, tasks, and crew code here
|
||||
|
||||
except Exception as e:
|
||||
print(f"Error connecting to or using multiple MCP servers (Managed): {e}")
|
||||
print("Ensure all MCP servers are running and accessible with correct configurations.")
|
||||
|
||||
```
|
||||
|
||||
## Gerenciamento de Conexão
|
||||
|
||||
Ao utilizar o gerenciador de contexto (`with` statement), o `MCPServerAdapter` gerencia o ciclo de vida (início e término) de todas as conexões aos servidores MCP configurados. Isso simplifica o gerenciamento de recursos e garante que todas as conexões sejam devidamente fechadas ao sair do contexto.
|
||||
215
docs/pt-BR/mcp/overview.mdx
Normal file
215
docs/pt-BR/mcp/overview.mdx
Normal file
@@ -0,0 +1,215 @@
|
||||
---
|
||||
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
|
||||
---
|
||||
|
||||
## 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.
|
||||
A biblioteca `crewai-tools` expande as capacidades do CrewAI permitindo que você integre facilmente ferramentas desses servidores MCP em seus agentes.
|
||||
Isso oferece às suas crews acesso a um vasto ecossistema de funcionalidades.
|
||||
|
||||
Atualmente, suportamos os seguintes mecanismos de transporte:
|
||||
|
||||
- **Stdio**: para servidores locais (comunicação via entrada/saída padrão entre processos na mesma máquina)
|
||||
- **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:
|
||||
|
||||
<iframe
|
||||
width="100%"
|
||||
height="400"
|
||||
src="https://www.youtube.com/embed/TpQ45lAZh48"
|
||||
title="CrewAI MCP Integration Guide"
|
||||
frameborder="0"
|
||||
style={{ borderRadius: '10px' }}
|
||||
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
|
||||
allowfullscreen
|
||||
></iframe>
|
||||
|
||||
## 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.
|
||||
|
||||
```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) as mcp_tools:
|
||||
print(f"Available tools: {[tool.name for tool in mcp_tools]}")
|
||||
|
||||
my_agent = Agent(
|
||||
role="MCP Tool User",
|
||||
goal="Utilize tools from an MCP server.",
|
||||
backstory="I can connect to MCP servers and use their tools.",
|
||||
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) as mcp_tools:
|
||||
print(f"Available tools: {[tool.name for tool in mcp_tools]}")
|
||||
|
||||
my_agent = Agent(
|
||||
role="MCP Tool User",
|
||||
goal="Utilize tools from an MCP server.",
|
||||
backstory="I can connect to MCP servers and use their tools.",
|
||||
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 `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()) # você também pode filtrar quais ferramentas estarão disponíveis
|
||||
|
||||
# ... restante da configuração do seu crew ...
|
||||
```
|
||||
## Explore Integrações MCP
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card
|
||||
title="Transporte Stdio"
|
||||
icon="server"
|
||||
href="/pt-BR/mcp/stdio"
|
||||
color="#3B82F6"
|
||||
>
|
||||
Conecte-se a servidores MCP locais via entrada/saída padrão. Ideal para scripts e executáveis locais.
|
||||
</Card>
|
||||
<Card
|
||||
title="Transporte SSE"
|
||||
icon="wifi"
|
||||
href="/pt-BR/mcp/sse"
|
||||
color="#10B981"
|
||||
>
|
||||
Integre com servidores MCP remotos usando Server-Sent Events para streaming de dados em tempo real.
|
||||
</Card>
|
||||
<Card
|
||||
title="Transporte HTTP Streamable"
|
||||
icon="globe"
|
||||
href="/pt-BR/mcp/streamable-http"
|
||||
color="#F59E0B"
|
||||
>
|
||||
Utilize HTTP Streamable para uma comunicação robusta com servidores MCP remotos.
|
||||
</Card>
|
||||
<Card
|
||||
title="Conectando a Múltiplos Servidores"
|
||||
icon="layer-group"
|
||||
href="/pt-BR/mcp/multiple-servers"
|
||||
color="#8B5CF6"
|
||||
>
|
||||
Agregue ferramentas de vários servidores MCP simultaneamente usando um único adaptador.
|
||||
</Card>
|
||||
<Card
|
||||
title="Considerações de Segurança"
|
||||
icon="lock"
|
||||
href="/pt-BR/mcp/security"
|
||||
color="#EF4444"
|
||||
>
|
||||
Revise práticas importantes de segurança para integração MCP e mantenha seus agentes protegidos.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
Confira este repositório para demonstrações completas e exemplos de integração MCP com CrewAI! 👇
|
||||
|
||||
<Card
|
||||
title="Repositório GitHub"
|
||||
icon="github"
|
||||
href="https://github.com/tonykipkemboi/crewai-mcp-demo"
|
||||
target="_blank"
|
||||
>
|
||||
Demo MCP do CrewAI
|
||||
</Card>
|
||||
|
||||
## Segurança ao Usar MCP
|
||||
<Warning>
|
||||
Sempre assegure-se de confiar no servidor MCP antes de utilizá-lo.
|
||||
</Warning>
|
||||
|
||||
#### 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.
|
||||
165
docs/pt-BR/mcp/security.mdx
Normal file
165
docs/pt-BR/mcp/security.mdx
Normal file
@@ -0,0 +1,165 @@
|
||||
---
|
||||
title: Considerações de Segurança MCP
|
||||
description: Saiba mais sobre as principais melhores práticas de segurança ao integrar servidores MCP com seus agentes CrewAI.
|
||||
icon: lock
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
<Warning>
|
||||
O aspecto mais crítico da segurança MCP é a **confiança**. Você deve **apenas** conectar seus agentes CrewAI a servidores MCP nos quais confie plenamente.
|
||||
</Warning>
|
||||
|
||||
Ao integrar serviços externos como servidores MCP (Model Context Protocol) aos seus agentes CrewAI, a segurança é fundamental.
|
||||
Servidores MCP podem executar código, acessar dados ou interagir com outros sistemas com base nas ferramentas que expõem.
|
||||
É crucial compreender as implicações e seguir as melhores práticas para proteger suas aplicações e dados.
|
||||
|
||||
### Riscos
|
||||
|
||||
- Executar código arbitrário na máquina onde o agente está rodando (especialmente com o transporte `Stdio` se o servidor puder controlar o comando executado).
|
||||
- Expor dados sensíveis do seu agente ou do seu ambiente.
|
||||
- Manipular o comportamento do seu agente de maneiras não intencionais, incluindo realizar chamadas de API não autorizadas em seu nome.
|
||||
- Sequestrar o processo de raciocínio do agente através de técnicas sofisticadas de prompt injection (veja abaixo).
|
||||
|
||||
### 1. Confiando em Servidores MCP
|
||||
|
||||
<Warning>
|
||||
**Somente conecte-se a servidores MCP em que confie.**
|
||||
</Warning>
|
||||
|
||||
Antes de configurar o `MCPServerAdapter` para conectar a um servidor MCP, certifique-se de saber:
|
||||
- **Quem opera o servidor?** É um serviço conhecido, de reputação confiável, ou um servidor interno sob o seu controle?
|
||||
- **Quais ferramentas ele expõe?** Entenda as capacidades das ferramentas. Elas poderiam ser mal utilizadas caso um invasor obtenha controle ou se o próprio servidor for malicioso?
|
||||
- **Quais dados ele acessa ou processa?** Saiba se há informações sensíveis que possam ser enviadas ou manipuladas pelo servidor MCP.
|
||||
|
||||
Evite conectar-se a servidores MCP desconhecidos ou não verificados, especialmente se seus agentes lidam com tarefas ou dados sensíveis.
|
||||
|
||||
### 2. Prompt Injection Seguro via Metadados de Ferramentas: O Risco do "Model Control Protocol"
|
||||
|
||||
Um risco significativo e sutil é o potencial para prompt injection através dos metadados das ferramentas. Veja como funciona:
|
||||
|
||||
1. Quando seu agente CrewAI se conecta a um servidor MCP, ele normalmente solicita uma lista de ferramentas disponíveis.
|
||||
2. O servidor MCP responde com metadados para cada ferramenta, incluindo nome, descrição e descrições de parâmetros.
|
||||
3. O LLM (Modelo de Linguagem) subjacente do seu agente usa esses metadados para entender como e quando usar as ferramentas. Muitas vezes esses metadados são incorporados no system prompt ou contexto do LLM.
|
||||
4. Um servidor MCP malicioso pode construir seus metadados (nomes, descrições) para incluir instruções ocultas ou explícitas. Essas instruções podem atuar como prompt injection, efetivamente fazendo o LLM se comportar de determinada maneira, revelar informações sensíveis ou executar ações maliciosas.
|
||||
|
||||
**Crucialmente, esse ataque pode ocorrer simplesmente ao conectar-se a um servidor malicioso e listar suas ferramentas, mesmo que seu agente nunca decida *usar* essas ferramentas.** A mera exposição aos metadados maliciosos pode ser suficiente para comprometer o comportamento do agente.
|
||||
|
||||
**Mitigação:**
|
||||
|
||||
* **Extrema Cautela com Servidores Não Confiáveis:** Reitere: *Não conecte-se a servidores MCP nos quais você não confie totalmente.* O risco de injection de metadados torna isso fundamental.
|
||||
|
||||
### Segurança do Transporte Stdio
|
||||
|
||||
O transporte Stdio (Entrada/Saída Padrão) é tipicamente usado para servidores MCP locais, rodando na mesma máquina que sua aplicação CrewAI.
|
||||
|
||||
- **Isolamento de Processo**: Embora geralmente seja mais seguro pois não envolve exposição de rede por padrão, assegure-se de que o script ou comando executado pelo `StdioServerParameters` é de uma fonte confiável e possui permissões de sistema de arquivos adequadas. Um script Stdio servidor malicioso pode ainda prejudicar seu sistema local.
|
||||
- **Saneamento de Entrada**: Se o seu script de servidor Stdio recebe entradas complexas derivadas das interações do agente, garanta que o script saneie essas entradas para evitar injection de comandos ou outras vulnerabilidades na lógica do script.
|
||||
- **Limite de Recursos**: Esteja atento ao fato de que o processo servidor Stdio consome recursos locais (CPU, memória). Assegure-se de que seja bem comportado, evitando esgotar os recursos do sistema.
|
||||
|
||||
### Ataques de Confused Deputy
|
||||
|
||||
O [Problema do Confused Deputy](https://en.wikipedia.org/wiki/Confused_deputy_problem) é uma vulnerabilidade clássica de segurança que pode se manifestar em integrações MCP, especialmente quando um servidor MCP atua como proxy para outros serviços de terceiros (ex: Google Calendar, GitHub) que usam OAuth 2.0 para autorização.
|
||||
|
||||
**Cenário:**
|
||||
|
||||
1. Um servidor MCP (vamos chamá-lo de `MCP-Proxy`) permite que seu agente interaja com o `ThirdPartyAPI`.
|
||||
2. O `MCP-Proxy` usa seu próprio `client_id` estático ao comunicar-se com o servidor de autorização do `ThirdPartyAPI`.
|
||||
3. Você, como usuário, autoriza legitimamente o `MCP-Proxy` a acessar o `ThirdPartyAPI` em seu nome. Durante esse processo, o servidor de autenticação pode definir um cookie no seu navegador indicando seu consentimento para o `client_id` do `MCP-Proxy`.
|
||||
4. Um invasor cria um link malicioso. Esse link inicia um fluxo OAuth com o `MCP-Proxy`, mas é projetado para enganar o servidor de autenticação do `ThirdPartyAPI`.
|
||||
5. Se você clicar nesse link e o servidor de autenticação do `ThirdPartyAPI` encontrar seu cookie de consentimento existente para o `client_id` do `MCP-Proxy`, pode *deixar de* pedir seu consentimento novamente.
|
||||
6. O `MCP-Proxy` pode, então, ser enganado a encaminhar um código de autorização (para o `ThirdPartyAPI`) para o atacante, ou um código de autorização MCP que o atacante possa usar para se passar por você perante o `MCP-Proxy`.
|
||||
|
||||
**Mitigação (Principalmente para Desenvolvedores de Servidores MCP):**
|
||||
|
||||
* Servidores proxy MCP usando IDs de cliente estáticos para serviços downstream **devem** obter consentimento explícito do usuário para *cada aplicação cliente ou agente* conectando-se a eles *antes* de iniciar um fluxo OAuth com o serviço de terceiros. Isso significa que o `MCP-Proxy` deve exibir uma tela de consentimento.
|
||||
|
||||
**Implicação para Usuários CrewAI:**
|
||||
|
||||
* Fique atento se um servidor MCP redireciona você para múltiplas autenticações OAuth, especialmente se isso for inesperado ou se as permissões solicitadas forem muito amplas.
|
||||
* Prefira servidores MCP que deixem clara sua própria identidade e a identidade dos serviços de terceiros que possam fazer proxy.
|
||||
|
||||
### Segurança no Transporte Remoto (SSE & HTTP Transmitível)
|
||||
|
||||
Ao conectar-se a servidores MCP remotos via Server-Sent Events (SSE) ou HTTP transmitível, práticas padrão de segurança web são essenciais.
|
||||
|
||||
### Considerações de Segurança SSE
|
||||
|
||||
### a. Ataques de DNS Rebinding (Especialmente para SSE)
|
||||
|
||||
<Critical>
|
||||
**Proteja-se contra ataques de DNS Rebinding.**
|
||||
</Critical>
|
||||
|
||||
DNS rebinding permite que um site controlado por atacante contorne a política de mesma origem e faça requisições para servidores na rede local do usuário (ex: `localhost`) ou intranet. Isso é particularmente arriscado se você roda um servidor MCP localmente (ex: para desenvolvimento) e um agente em um ambiente do tipo navegador (embora menos comum no backend CrewAI) ou se o servidor MCP está em uma rede interna.
|
||||
|
||||
**Estratégias de Mitigação para Implementadores de Servidores MCP:**
|
||||
- **Valide os Headers `Origin` e `Host`**: Servidores MCP (especialmente com SSE) devem validar os headers HTTP `Origin` e/ou `Host` para garantir que as requisições venham dos domínios/clientes esperados.
|
||||
- **Ligue em `localhost` (127.0.0.1)**: Ao rodar servidores MCP localmente para desenvolvimento, conecte-se a `127.0.0.1` em vez de `0.0.0.0`. Isso impede que sejam acessíveis por outras máquinas na rede.
|
||||
- **Autenticação**: Exija autenticação para todas as conexões ao seu servidor MCP caso não seja destinado a acesso público anônimo.
|
||||
|
||||
### b. Use HTTPS
|
||||
|
||||
- **Criptografe Dados em Trânsito**: Sempre use HTTPS (HTTP Seguro) para URLs de servidores MCP remotos. Isso criptografa a comunicação entre sua aplicação CrewAI e o servidor MCP, protegendo contra escuta e ataques Man-in-the-Middle (MitM). O `MCPServerAdapter` respeitará o esquema (`http` ou `https`) fornecido na URL.
|
||||
|
||||
### c. Token Passthrough (Anti-Padrão)
|
||||
|
||||
Isso é uma preocupação principalmente para desenvolvedores de servidores MCP, mas entender o conceito ajuda a escolher servidores seguros.
|
||||
|
||||
"Token passthrough" é quando um servidor MCP aceita um token de acesso do seu agente CrewAI (que pode ser um token para um serviço *diferente*, por exemplo, `ServiceA`) e simplesmente o repassa para outra API ( `ServiceB`) downstream sem validação adequada. Especificamente, `ServiceB` (ou o próprio servidor MCP) só deveria aceitar tokens explicitamente emitidos *para eles* (ou seja, o claim 'audience' no token deve corresponder ao servidor/serviço).
|
||||
|
||||
**Riscos:**
|
||||
|
||||
* Burlar controles de segurança (como limites de taxa ou permissões granulares) no servidor MCP ou na API downstream.
|
||||
* Quebra trilhas de auditoria e responsabilização.
|
||||
* Permite uso indevido de tokens roubados.
|
||||
|
||||
**Mitigação (Para Desenvolvedores de Servidores MCP):**
|
||||
|
||||
* Servidores MCP **NÃO DEVEM** aceitar tokens que não foram explicitamente emitidos para eles. Devem validar o claim de audiência dos tokens.
|
||||
|
||||
**Implicação para Usuários CrewAI:**
|
||||
|
||||
* Embora isso não seja diretamente controlável pelo usuário, destaca a importância de conectar-se a servidores MCP bem projetados e que sigam as melhores práticas de segurança.
|
||||
|
||||
#### Autenticação e Autorização
|
||||
|
||||
- **Verifique a Identidade**: Se o servidor MCP fornece ferramentas sensíveis ou acesso a dados privados, ele DEVE implementar mecanismos de autenticação robustos para verificar a identidade do cliente (sua aplicação CrewAI). Isso pode envolver chaves de API, tokens OAuth ou outros métodos padrão.
|
||||
- **Princípio do Menor Privilégio**: Certifique-se de que as credenciais usadas pelo `MCPServerAdapter` (se houver) tenham apenas as permissões necessárias para acessar as ferramentas requeridas.
|
||||
|
||||
### d. Validação e Saneamento de Entrada
|
||||
|
||||
- **Validação de Entrada é Crítica**: Servidores MCP **devem** validar rigorosamente todas as entradas recebidas de agentes *antes* de processá-las ou passá-las para as ferramentas. Esta é a principal defesa contra diversas vulnerabilidades comuns:
|
||||
- **Injection de Comando:** Caso uma ferramenta construa comandos de shell, queries SQL ou outras instruções de linguagens interpretadas a partir da entrada, o servidor deve sanitizar cuidadosamente esta entrada para evitar que comandos maliciosos sejam injetados e executados.
|
||||
- **Path Traversal:** Se uma ferramenta acessa arquivos com base em parâmetros de entrada, o servidor deve validar e sanitizar esses caminhos para evitar acesso a arquivos ou diretórios não autorizados (por exemplo, bloqueando sequências `../`).
|
||||
- **Verificações de Tipo e Faixa de Dados:** Servidores devem garantir que os dados de entrada estejam nos tipos esperados (ex: string, número, booleano) e dentro de faixas aceitáveis ou em formatos definidos (ex: regex para URLs).
|
||||
- **Validação de Schema JSON:** Todos os parâmetros das ferramentas devem ser validados estritamente com seus esquemas JSON definidos. Isso ajuda a capturar requisições mal formatadas precocemente.
|
||||
- **Atenção do Lado do Cliente**: Embora a validação no servidor seja fundamental, como usuário CrewAI, fique atento aos dados que seus agentes são configurados para enviar a ferramentas MCP, especialmente ao interagir com servidores MCP novos ou menos confiáveis.
|
||||
|
||||
### e. Limite de Taxa e Gerenciamento de Recursos
|
||||
|
||||
- **Previna Abusos**: Servidores MCP devem implementar limite de taxa para prevenir abusos, seja intencional (ataques de negação de serviço) ou não intencional (ex: um agente mal configurado fazendo muitas requisições).
|
||||
- **Re-tentativas do Lado do Cliente**: Implemente lógica de repetição sensata em suas tarefas CrewAI se problemas de rede transitórios ou limites de taxa do servidor forem esperados, mas evite re-tentativas agressivas que possam aumentar a carga do servidor.
|
||||
|
||||
## 4. Conselhos para Implementação de Servidor MCP Seguro (Para Desenvolvedores)
|
||||
|
||||
Se você está desenvolvendo um servidor MCP ao qual agentes CrewAI possam se conectar, considere estas melhores práticas além dos pontos acima:
|
||||
|
||||
- **Siga Práticas de Código Seguro**: Adote princípios padrão de programação segura para sua linguagem e framework escolhidos (ex: OWASP Top 10).
|
||||
- **Princípio do Menor Privilégio**: Certifique-se de que o processo que executa o servidor MCP (especialmente para `Stdio`) tenha apenas as permissões mínimas necessárias. As próprias ferramentas também devem operar com o mínimo de privilégio necessário para executar sua função.
|
||||
- **Gerenciamento de Dependências**: Mantenha todas as dependências do lado do servidor, incluindo pacotes do sistema operacional, runtimes de linguagem e bibliotecas de terceiros, sempre atualizadas para corrigir vulnerabilidades conhecidas. Use ferramentas para escanear por dependências vulneráveis.
|
||||
- **Padrões Seguros por Padrão**: Projete seu servidor e suas ferramentas para serem seguros por padrão. Por exemplo, recursos potencialmente arriscados devem ser desabilitados por padrão ou requerer ativação explícita, com avisos claros.
|
||||
- **Controle de Acesso para Ferramentas**: Implemente mecanismos robustos para controlar quais agentes ou usuários autenticados e autorizados podem acessar ferramentas específicas, especialmente as que são poderosas, sensíveis ou incorram em custos.
|
||||
- **Tratamento Seguro de Erros**: Servidores não devem expor mensagens detalhadas de erro interno, traces de stack ou informações de debug para o cliente, pois estas podem revelar detalhes internos ou potenciais vulnerabilidades. Logue os erros de forma abrangente no lado do servidor para diagnóstico.
|
||||
- **Log e Monitoramento Abrangentes**: Implemente um log detalhado de eventos relevantes para segurança (ex: tentativas de autenticação, invocações de ferramenta, erros, mudanças de autorização). Monitore esses logs em busca de atividades suspeitas ou padrões de abuso.
|
||||
- **Aderência à Especificação de Autorização MCP**: Caso implemente autenticação e autorização, siga estritamente a [especificação de autorização MCP](https://modelcontextprotocol.io/specification/draft/basic/authorization) e as [melhores práticas de segurança OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc9700) relevantes.
|
||||
- **Auditorias de Segurança Regulares**: Caso seu servidor MCP manipule dados sensíveis, realize operações críticas ou seja exposto publicamente, considere auditorias de segurança periódicas conduzidas por profissionais qualificados.
|
||||
|
||||
## 5. Leituras Adicionais
|
||||
|
||||
Para informações mais detalhadas sobre segurança MCP, consulte a documentação oficial:
|
||||
- **[Segurança de Transporte MCP](https://modelcontextprotocol.io/docs/concepts/transports#security-considerations)**
|
||||
|
||||
Ao entender essas considerações de segurança e implementar as melhores práticas, você pode aproveitar com segurança o poder dos servidores MCP em seus projetos CrewAI.
|
||||
Estes pontos não esgotam o assunto, mas cobrem as questões de segurança mais comuns e críticas.
|
||||
As ameaças continuarão a evoluir, por isso é importante se manter informado e adaptar suas medidas de segurança de acordo.
|
||||
150
docs/pt-BR/mcp/sse.mdx
Normal file
150
docs/pt-BR/mcp/sse.mdx
Normal file
@@ -0,0 +1,150 @@
|
||||
---
|
||||
title: Transporte SSE
|
||||
description: Saiba como conectar o CrewAI a servidores MCP remotos usando Server-Sent Events (SSE) para comunicação em tempo real.
|
||||
icon: wifi
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
Server-Sent Events (SSE) fornecem uma forma padrão para um servidor web enviar atualizações a um cliente através de uma única conexão HTTP de longa duração. No contexto do MCP, SSE é utilizado para que servidores remotos transmitam dados (como respostas de ferramentas) para sua aplicação CrewAI em tempo real.
|
||||
|
||||
## Conceitos-Chave
|
||||
|
||||
- **Servidores Remotos**: SSE é adequado para servidores MCP hospedados remotamente.
|
||||
- **Fluxo Unidirecional**: Normalmente, SSE é um canal de comunicação de mão única, do servidor para o cliente.
|
||||
- **Configuração do `MCPServerAdapter`**: Para SSE, você fornecerá a URL do servidor e especificará o tipo de transporte.
|
||||
|
||||
## Conectando via SSE
|
||||
|
||||
Você pode se conectar a um servidor MCP baseado em SSE usando duas abordagens principais para gerenciar o ciclo de vida da conexão:
|
||||
|
||||
### 1. Conexão Totalmente Gerenciada (Recomendado)
|
||||
|
||||
Utilizar um gerenciador de contexto Python (`with` statement) é a abordagem recomendada. Ele lida automaticamente com o estabelecimento e o encerramento da conexão com o servidor MCP SSE.
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew, Process
|
||||
from crewai_tools import MCPServerAdapter
|
||||
|
||||
server_params = {
|
||||
"url": "http://localhost:8000/sse", # Replace with your actual SSE server URL
|
||||
"transport": "sse"
|
||||
}
|
||||
|
||||
# Using MCPServerAdapter with a context manager
|
||||
try:
|
||||
with MCPServerAdapter(server_params) as tools:
|
||||
print(f"Available tools from SSE MCP server: {[tool.name for tool in tools]}")
|
||||
|
||||
# Example: Using a tool from the SSE MCP server
|
||||
sse_agent = Agent(
|
||||
role="Remote Service User",
|
||||
goal="Utilize a tool provided by a remote SSE MCP server.",
|
||||
backstory="An AI agent that connects to external services via SSE.",
|
||||
tools=tools,
|
||||
reasoning=True,
|
||||
verbose=True,
|
||||
)
|
||||
|
||||
sse_task = Task(
|
||||
description="Fetch real-time stock updates for 'AAPL' using an SSE tool.",
|
||||
expected_output="The latest stock price for AAPL.",
|
||||
agent=sse_agent,
|
||||
markdown=True
|
||||
)
|
||||
|
||||
sse_crew = Crew(
|
||||
agents=[sse_agent],
|
||||
tasks=[sse_task],
|
||||
verbose=True,
|
||||
process=Process.sequential
|
||||
)
|
||||
|
||||
if tools: # Only kickoff if tools were loaded
|
||||
result = sse_crew.kickoff() # Add inputs={'stock_symbol': 'AAPL'} if tool requires it
|
||||
print("\nCrew Task Result (SSE - Managed):\n", result)
|
||||
else:
|
||||
print("Skipping crew kickoff as tools were not loaded (check server connection).")
|
||||
|
||||
except Exception as e:
|
||||
print(f"Error connecting to or using SSE MCP server (Managed): {e}")
|
||||
print("Ensure the SSE MCP server is running and accessible at the specified URL.")
|
||||
|
||||
```
|
||||
|
||||
<Note>
|
||||
Substitua `"http://localhost:8000/sse"` pela URL real do seu servidor MCP SSE.
|
||||
</Note>
|
||||
|
||||
### 2. Ciclo de Vida Manual da Conexão
|
||||
|
||||
Caso precise de um controle mais detalhado, você pode gerenciar manualmente o ciclo de vida da conexão do `MCPServerAdapter`.
|
||||
|
||||
<Info>
|
||||
Você **DEVE** chamar `mcp_server_adapter.stop()` para garantir que a conexão seja encerrada e os recursos liberados. O uso de um bloco `try...finally` é altamente recomendado.
|
||||
</Info>
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew, Process
|
||||
from crewai_tools import MCPServerAdapter
|
||||
|
||||
server_params = {
|
||||
"url": "http://localhost:8000/sse", # Replace with your actual SSE server URL
|
||||
"transport": "sse"
|
||||
}
|
||||
|
||||
mcp_server_adapter = None
|
||||
try:
|
||||
mcp_server_adapter = MCPServerAdapter(server_params)
|
||||
mcp_server_adapter.start()
|
||||
tools = mcp_server_adapter.tools
|
||||
print(f"Available tools (manual SSE): {[tool.name for tool in tools]}")
|
||||
|
||||
manual_sse_agent = Agent(
|
||||
role="Remote Data Analyst",
|
||||
goal="Analyze data fetched from a remote SSE MCP server using manual connection management.",
|
||||
backstory="An AI skilled in handling SSE connections explicitly.",
|
||||
tools=tools,
|
||||
verbose=True
|
||||
)
|
||||
|
||||
analysis_task = Task(
|
||||
description="Fetch and analyze the latest user activity trends from the SSE server.",
|
||||
expected_output="A summary report of user activity trends.",
|
||||
agent=manual_sse_agent
|
||||
)
|
||||
|
||||
analysis_crew = Crew(
|
||||
agents=[manual_sse_agent],
|
||||
tasks=[analysis_task],
|
||||
verbose=True,
|
||||
process=Process.sequential
|
||||
)
|
||||
|
||||
result = analysis_crew.kickoff()
|
||||
print("\nCrew Task Result (SSE - Manual):\n", result)
|
||||
|
||||
except Exception as e:
|
||||
print(f"An error occurred during manual SSE MCP integration: {e}")
|
||||
print("Ensure the SSE MCP server is running and accessible.")
|
||||
finally:
|
||||
if mcp_server_adapter and mcp_server_adapter.is_connected:
|
||||
print("Stopping SSE MCP server connection (manual)...")
|
||||
mcp_server_adapter.stop() # **Crucial: Ensure stop is called**
|
||||
elif mcp_server_adapter:
|
||||
print("SSE MCP server adapter was not connected. No stop needed or start failed.")
|
||||
|
||||
```
|
||||
|
||||
## Considerações de Segurança para SSE
|
||||
|
||||
<Warning>
|
||||
**Ataques de DNS Rebinding**: Transportes SSE podem ser vulneráveis a ataques de DNS rebinding se o servidor MCP não estiver devidamente protegido. Isso pode permitir que sites maliciosos interajam com servidores MCP locais ou da intranet.
|
||||
</Warning>
|
||||
|
||||
Para mitigar esse risco:
|
||||
- As implementações do servidor MCP devem **validar os cabeçalhos `Origin`** em conexões SSE recebidas.
|
||||
- Ao rodar servidores MCP SSE locais para desenvolvimento, **faça o bind apenas em `localhost` (`127.0.0.1`)** ao invés de todas as interfaces de rede (`0.0.0.0`).
|
||||
- Implemente **autenticação adequada** para todas as conexões SSE caso exponham ferramentas ou dados sensíveis.
|
||||
|
||||
Para uma visão abrangente das melhores práticas de segurança, consulte nossa página de [Considerações de Segurança](./security.mdx) e a documentação oficial [MCP Transport Security](https://modelcontextprotocol.io/docs/concepts/transports#security-considerations).
|
||||
133
docs/pt-BR/mcp/stdio.mdx
Normal file
133
docs/pt-BR/mcp/stdio.mdx
Normal file
@@ -0,0 +1,133 @@
|
||||
---
|
||||
title: Transporte Stdio
|
||||
description: Aprenda como conectar o CrewAI a servidores MCP locais usando o mecanismo de transporte Stdio (Entrada/Saída Padrão).
|
||||
icon: server
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
O transporte Stdio (Entrada/Saída Padrão) é projetado para conectar o `MCPServerAdapter` a servidores MCP locais que se comunicam por meio de seus fluxos de entrada e saída padrão. Isso é normalmente utilizado quando o servidor MCP é um script ou executável rodando na mesma máquina da sua aplicação CrewAI.
|
||||
|
||||
## Conceitos-Chave
|
||||
|
||||
- **Execução Local**: O transporte Stdio gerencia um processo localmente em execução para o servidor MCP.
|
||||
- **`StdioServerParameters`**: Esta classe da biblioteca `mcp` é usada para configurar o comando, argumentos e variáveis de ambiente para iniciar o servidor Stdio.
|
||||
|
||||
## Conectando via Stdio
|
||||
|
||||
Você pode se conectar a um servidor MCP baseado em Stdio usando duas abordagens principais para gerenciar o ciclo de vida da conexão:
|
||||
|
||||
### 1. Conexão Totalmente Gerenciada (Recomendado)
|
||||
|
||||
Usar um context manager do Python (declaração `with`) é a abordagem recomendada. Ela lida automaticamente com o início do processo do servidor MCP e sua finalização quando o contexto é encerrado.
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew, Process
|
||||
from crewai_tools import MCPServerAdapter
|
||||
from mcp import StdioServerParameters
|
||||
import os
|
||||
|
||||
# Criar um objeto StdioServerParameters
|
||||
server_params=StdioServerParameters(
|
||||
command="python3",
|
||||
args=["servers/your_stdio_server.py"],
|
||||
env={"UV_PYTHON": "3.12", **os.environ},
|
||||
)
|
||||
|
||||
with MCPServerAdapter(server_params) as tools:
|
||||
print(f"Available tools from Stdio MCP server: {[tool.name for tool in tools]}")
|
||||
|
||||
# Exemplo: Usando as ferramentas do servidor MCP Stdio em um Agente CrewAI
|
||||
research_agent = Agent(
|
||||
role="Local Data Processor",
|
||||
goal="Process data using a local Stdio-based tool.",
|
||||
backstory="An AI that leverages local scripts via MCP for specialized tasks.",
|
||||
tools=tools,
|
||||
reasoning=True,
|
||||
verbose=True,
|
||||
)
|
||||
|
||||
processing_task = Task(
|
||||
description="Process the input data file 'data.txt' and summarize its contents.",
|
||||
expected_output="A summary of the processed data.",
|
||||
agent=research_agent,
|
||||
markdown=True
|
||||
)
|
||||
|
||||
data_crew = Crew(
|
||||
agents=[research_agent],
|
||||
tasks=[processing_task],
|
||||
verbose=True,
|
||||
process=Process.sequential
|
||||
)
|
||||
|
||||
result = data_crew.kickoff()
|
||||
print("\nCrew Task Result (Stdio - Managed):\n", result)
|
||||
|
||||
```
|
||||
|
||||
### 2. Ciclo de Vida Manual da Conexão
|
||||
|
||||
Se você precisa de um controle mais refinado sobre quando o processo do servidor MCP Stdio é iniciado e finalizado, pode gerenciar o ciclo de vida do `MCPServerAdapter` manualmente.
|
||||
|
||||
<Info>
|
||||
Você **DEVE** chamar `mcp_server_adapter.stop()` para garantir que o processo do servidor seja finalizado e os recursos, liberados. Recomenda-se fortemente o uso de um bloco `try...finally`.
|
||||
</Info>
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew, Process
|
||||
from crewai_tools import MCPServerAdapter
|
||||
from mcp import StdioServerParameters
|
||||
import os
|
||||
|
||||
# Criar um objeto StdioServerParameters
|
||||
stdio_params=StdioServerParameters(
|
||||
command="python3",
|
||||
args=["servers/your_stdio_server.py"],
|
||||
env={"UV_PYTHON": "3.12", **os.environ},
|
||||
)
|
||||
|
||||
mcp_server_adapter = MCPServerAdapter(server_params=stdio_params)
|
||||
try:
|
||||
mcp_server_adapter.start() # Inicia manualmente a conexão e o processo do servidor
|
||||
tools = mcp_server_adapter.tools
|
||||
print(f"Available tools (manual Stdio): {[tool.name for tool in tools]}")
|
||||
|
||||
# Exemplo: Usando as ferramentas com sua configuração de Agent, Task, Crew
|
||||
manual_agent = Agent(
|
||||
role="Local Task Executor",
|
||||
goal="Execute a specific local task using a manually managed Stdio tool.",
|
||||
backstory="An AI proficient in controlling local processes via MCP.",
|
||||
tools=tools,
|
||||
verbose=True
|
||||
)
|
||||
|
||||
manual_task = Task(
|
||||
description="Execute the 'perform_analysis' command via the Stdio tool.",
|
||||
expected_output="Results of the analysis.",
|
||||
agent=manual_agent
|
||||
)
|
||||
|
||||
manual_crew = Crew(
|
||||
agents=[manual_agent],
|
||||
tasks=[manual_task],
|
||||
verbose=True,
|
||||
process=Process.sequential
|
||||
)
|
||||
|
||||
|
||||
result = manual_crew.kickoff() # As entradas reais dependem da sua ferramenta
|
||||
print("\nCrew Task Result (Stdio - Manual):\n", result)
|
||||
|
||||
except Exception as e:
|
||||
print(f"An error occurred during manual Stdio MCP integration: {e}")
|
||||
finally:
|
||||
if mcp_server_adapter and mcp_server_adapter.is_connected: # Verifica se está conectado antes de parar
|
||||
print("Stopping Stdio MCP server connection (manual)...")
|
||||
mcp_server_adapter.stop() # **Crucial: Assegure que stop seja chamado**
|
||||
elif mcp_server_adapter: # Se o adaptador existe mas não está conectado (ex.: start falhou)
|
||||
print("Stdio MCP server adapter was not connected. No stop needed or start failed.")
|
||||
|
||||
```
|
||||
|
||||
Lembre-se de substituir caminhos e comandos de exemplo pelos detalhes reais do seu servidor Stdio. O parâmetro `env` em `StdioServerParameters` pode ser usado para definir variáveis de ambiente para o processo do servidor, o que pode ser útil para configurar seu comportamento ou fornecer caminhos necessários (como `PYTHONPATH`).
|
||||
135
docs/pt-BR/mcp/streamable-http.mdx
Normal file
135
docs/pt-BR/mcp/streamable-http.mdx
Normal file
@@ -0,0 +1,135 @@
|
||||
---
|
||||
title: Transporte HTTP Streamable
|
||||
description: Saiba como conectar o CrewAI a servidores MCP remotos usando o transporte HTTP Streamable flexível.
|
||||
icon: globe
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
O transporte HTTP Streamable oferece uma maneira flexível de se conectar a servidores MCP remotos. Ele é frequentemente baseado em HTTP e pode suportar vários padrões de comunicação, incluindo requisição-resposta e streaming, às vezes utilizando Server-Sent Events (SSE) para fluxos do servidor para o cliente dentro de uma interação HTTP mais ampla.
|
||||
|
||||
## Conceitos-Chave
|
||||
|
||||
- **Servidores Remotos**: Projetado para servidores MCP hospedados remotamente.
|
||||
- **Flexibilidade**: Pode suportar padrões de interação mais complexos do que SSE puro, potencialmente incluindo comunicação bidirecional se o servidor implementá-la.
|
||||
- **Configuração do `MCPServerAdapter`**: Você precisará fornecer a URL base do servidor para comunicação MCP e especificar `"streamable-http"` como o tipo de transporte.
|
||||
|
||||
## Conectando via HTTP Streamable
|
||||
|
||||
Você tem dois métodos principais para gerenciar o ciclo de vida da conexão com um servidor MCP HTTP Streamable:
|
||||
|
||||
### 1. Conexão Totalmente Gerenciada (Recomendado)
|
||||
|
||||
A abordagem recomendada é usar um gerenciador de contexto Python (`with` statement), que lida automaticamente com a configuração e encerramento da conexão.
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew, Process
|
||||
from crewai_tools import MCPServerAdapter
|
||||
|
||||
server_params = {
|
||||
"url": "http://localhost:8001/mcp", # Replace with your actual Streamable HTTP server URL
|
||||
"transport": "streamable-http"
|
||||
}
|
||||
|
||||
try:
|
||||
with MCPServerAdapter(server_params) as tools:
|
||||
print(f"Available tools from Streamable HTTP MCP server: {[tool.name for tool in tools]}")
|
||||
|
||||
http_agent = Agent(
|
||||
role="HTTP Service Integrator",
|
||||
goal="Utilize tools from a remote MCP server via Streamable HTTP.",
|
||||
backstory="An AI agent adept at interacting with complex web services.",
|
||||
tools=tools,
|
||||
verbose=True,
|
||||
)
|
||||
|
||||
http_task = Task(
|
||||
description="Perform a complex data query using a tool from the Streamable HTTP server.",
|
||||
expected_output="The result of the complex data query.",
|
||||
agent=http_agent,
|
||||
)
|
||||
|
||||
http_crew = Crew(
|
||||
agents=[http_agent],
|
||||
tasks=[http_task],
|
||||
verbose=True,
|
||||
process=Process.sequential
|
||||
)
|
||||
|
||||
result = http_crew.kickoff()
|
||||
print("\nCrew Task Result (Streamable HTTP - Managed):\n", result)
|
||||
|
||||
except Exception as e:
|
||||
print(f"Error connecting to or using Streamable HTTP MCP server (Managed): {e}")
|
||||
print("Ensure the Streamable HTTP MCP server is running and accessible at the specified URL.")
|
||||
|
||||
```
|
||||
**Nota:** Substitua `"http://localhost:8001/mcp"` pela URL real do seu servidor MCP HTTP Streamable.
|
||||
|
||||
### 2. Ciclo de Vida da Conexão Manual
|
||||
|
||||
Para cenários que exigem controle mais explícito, você pode gerenciar a conexão do `MCPServerAdapter` manualmente.
|
||||
|
||||
<Info>
|
||||
É **crítico** chamar `mcp_server_adapter.stop()` quando terminar para fechar a conexão e liberar recursos. Usar um bloco `try...finally` é a forma mais segura de garantir isso.
|
||||
</Info>
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew, Process
|
||||
from crewai_tools import MCPServerAdapter
|
||||
|
||||
server_params = {
|
||||
"url": "http://localhost:8001/mcp", # Replace with your actual Streamable HTTP server URL
|
||||
"transport": "streamable-http"
|
||||
}
|
||||
|
||||
mcp_server_adapter = None
|
||||
try:
|
||||
mcp_server_adapter = MCPServerAdapter(server_params)
|
||||
mcp_server_adapter.start()
|
||||
tools = mcp_server_adapter.tools
|
||||
print(f"Available tools (manual Streamable HTTP): {[tool.name for tool in tools]}")
|
||||
|
||||
manual_http_agent = Agent(
|
||||
role="Advanced Web Service User",
|
||||
goal="Interact with an MCP server using manually managed Streamable HTTP connections.",
|
||||
backstory="An AI specialist in fine-tuning HTTP-based service integrations.",
|
||||
tools=tools,
|
||||
verbose=True
|
||||
)
|
||||
|
||||
data_processing_task = Task(
|
||||
description="Submit data for processing and retrieve results via Streamable HTTP.",
|
||||
expected_output="Processed data or confirmation.",
|
||||
agent=manual_http_agent
|
||||
)
|
||||
|
||||
data_crew = Crew(
|
||||
agents=[manual_http_agent],
|
||||
tasks=[data_processing_task],
|
||||
verbose=True,
|
||||
process=Process.sequential
|
||||
)
|
||||
|
||||
result = data_crew.kickoff()
|
||||
print("\nCrew Task Result (Streamable HTTP - Manual):\n", result)
|
||||
|
||||
except Exception as e:
|
||||
print(f"An error occurred during manual Streamable HTTP MCP integration: {e}")
|
||||
print("Ensure the Streamable HTTP MCP server is running and accessible.")
|
||||
finally:
|
||||
if mcp_server_adapter and mcp_server_adapter.is_connected:
|
||||
print("Stopping Streamable HTTP MCP server connection (manual)...")
|
||||
mcp_server_adapter.stop() # **Crucial: Ensure stop is called**
|
||||
elif mcp_server_adapter:
|
||||
print("Streamable HTTP MCP server adapter was not connected. No stop needed or start failed.")
|
||||
```
|
||||
|
||||
## Considerações de Segurança
|
||||
|
||||
Ao utilizar o transporte HTTP Streamable, as melhores práticas gerais de segurança web são fundamentais:
|
||||
- **Use HTTPS**: Sempre prefira HTTPS (HTTP Seguro) para as URLs do seu servidor MCP para criptografar os dados em trânsito.
|
||||
- **Autenticação**: Implemente mecanismos robustos de autenticação se seu servidor MCP expuser ferramentas ou dados sensíveis.
|
||||
- **Validação de Entrada**: Garanta que seu servidor MCP valide todas as requisições e parâmetros recebidos.
|
||||
|
||||
Para um guia abrangente sobre como proteger suas integrações MCP, consulte nossa página de [Considerações de Segurança](./security.mdx) e a documentação oficial de [Segurança em Transportes MCP](https://modelcontextprotocol.io/docs/concepts/transports#security-considerations).
|
||||
Reference in New Issue
Block a user