Integração DSL MCP

Visão Geral

A integração DSL (Domain Specific Language) MCP do CrewAI oferece a forma mais simples de conectar seus agentes aos servidores MCP (Model Context Protocol). Basta adicionar um campo mcps ao seu agente e o CrewAI cuida de toda a complexidade automaticamente.

Uso Básico

Adicione servidores MCP ao seu agente usando o campo mcps:

from crewai import Agent

agent = Agent(
    role="Assistente de Pesquisa",
    goal="Ajudar com tarefas de pesquisa e análise",
    backstory="Assistente especialista com acesso a ferramentas avançadas de pesquisa",
    mcps=[
        "https://mcp.exa.ai/mcp?api_key=sua_chave&profile=pesquisa"
    ]
)

# As ferramentas MCP agora estão automaticamente disponíveis!
# Não é necessário gerenciamento manual de conexão ou configuração de ferramentas

Formatos de Referência Suportados

Servidores MCP Remotos Externos

# Servidor HTTPS básico
"https://api.example.com/mcp"

# Servidor com autenticação
"https://mcp.exa.ai/mcp?api_key=sua_chave&profile=seu_perfil"

# Servidor com caminho personalizado
"https://services.company.com/api/v1/mcp"

Seleção de Ferramentas Específicas

Use a sintaxe # para selecionar ferramentas específicas de um servidor:

# Obter apenas a ferramenta de previsão do servidor meteorológico
"https://weather.api.com/mcp#get_forecast"

# Obter apenas a ferramenta de busca do Exa
"https://mcp.exa.ai/mcp?api_key=sua_chave#web_search_exa"

Integrações MCP Conectadas

Conecte servidores MCP do catálogo CrewAI ou traga os seus próprios. Uma vez conectados em sua conta, referencie-os pelo slug:

# MCP conectado com todas as ferramentas
"snowflake"

# Ferramenta específica de um MCP conectado
"stripe#list_invoices"

# Múltiplos MCPs conectados
mcps=[
    "snowflake",
    "stripe",
    "github"
]

Exemplo Completo

Aqui está um exemplo completo usando múltiplos servidores MCP:

from crewai import Agent, Task, Crew, Process

# Criar agente com múltiplas fontes MCP
agente_multi_fonte = Agent(
    role="Analista de Pesquisa Multi-Fonte",
    goal="Conduzir pesquisa abrangente usando múltiplas fontes de dados",
    backstory="""Pesquisador especialista com acesso a busca web, dados meteorológicos,
    informações financeiras e ferramentas de pesquisa acadêmica""",
    mcps=[
        # Servidores MCP externos
        "https://mcp.exa.ai/mcp?api_key=sua_chave_exa&profile=pesquisa",
        "https://weather.api.com/mcp#get_current_conditions",

        # MCPs conectados do catálogo
        "snowflake",
        "stripe#list_invoices",
        "github#search_repositories"
    ]
)

# Criar tarefa de pesquisa abrangente
tarefa_pesquisa = Task(
    description="""Pesquisar o impacto dos agentes de IA na produtividade empresarial.
    Incluir impactos climáticos atuais no trabalho remoto, tendências do mercado financeiro,
    e publicações acadêmicas recentes sobre frameworks de agentes de IA.""",
    expected_output="""Relatório abrangente cobrindo:
    1. Análise do impacto dos agentes de IA nos negócios
    2. Considerações climáticas para trabalho remoto
    3. Tendências do mercado financeiro relacionadas à IA
    4. Citações e insights de pesquisa acadêmica
    5. Análise do cenário competitivo""",
    agent=agente_multi_fonte
)

# Criar e executar crew
crew_pesquisa = Crew(
    agents=[agente_multi_fonte],
    tasks=[tarefa_pesquisa],
    process=Process.sequential,
    verbose=True
)

resultado = crew_pesquisa.kickoff()
print(f"Pesquisa concluída com {len(agente_multi_fonte.mcps)} fontes de dados MCP")

Recursos Principais

🔄 Descoberta Automática de Ferramentas: Ferramentas são descobertas e integradas automaticamente
🏷️ Prevenção de Colisão de Nomes: Nomes de servidor são prefixados aos nomes das ferramentas
⚡ Otimizado para Performance: Conexões sob demanda com cache de esquemas
🛡️ Resiliência a Erros: Tratamento gracioso de servidores indisponíveis
⏱️ Proteção por Timeout: Timeouts integrados previnem conexões travadas
📊 Integração Transparente: Funciona perfeitamente com recursos existentes do CrewAI

Tratamento de Erros

A integração DSL MCP é projetada para ser resiliente:

agente = Agent(
    role="Agente Resiliente",
    goal="Continuar trabalhando apesar de problemas no servidor",
    backstory="Agente que lida graciosamente com falhas",
    mcps=[
        "https://servidor-confiavel.com/mcp",        # Vai funcionar
        "https://servidor-inalcancavel.com/mcp",     # Será ignorado graciosamente
        "https://servidor-lento.com/mcp",            # Timeout gracioso
        "snowflake"                                  # MCP conectado do catálogo
    ]
)
# O agente usará ferramentas de servidores funcionais e registrará avisos para os que falharem

Recursos de Performance

Cache Automático

Esquemas de ferramentas são cacheados por 5 minutos para melhorar a performance:

# Primeira criação de agente - descobre ferramentas do servidor
agente1 = Agent(role="Primeiro", goal="Teste", backstory="Teste",
               mcps=["https://api.example.com/mcp"])

# Segunda criação de agente (dentro de 5 minutos) - usa esquemas cacheados
agente2 = Agent(role="Segundo", goal="Teste", backstory="Teste",
               mcps=["https://api.example.com/mcp"])  # Muito mais rápido!

Conexões Sob Demanda

Conexões de ferramentas são estabelecidas apenas quando as ferramentas são realmente usadas:

# Criação do agente é rápida - nenhuma conexão MCP feita ainda
agente = Agent(
    role="Agente Sob Demanda",
    goal="Usar ferramentas eficientemente",
    backstory="Agente eficiente que conecta apenas quando necessário",
    mcps=["https://api.example.com/mcp"]
)

# Conexão MCP é feita apenas quando uma ferramenta é realmente executada
# Isso minimiza o overhead de conexão e melhora a performance de inicialização

Melhores Práticas

1. Use Ferramentas Específicas Quando Possível

# Bom - obter apenas as ferramentas necessárias
mcps=["https://weather.api.com/mcp#get_forecast"]

# Menos eficiente - obter todas as ferramentas do servidor
mcps=["https://weather.api.com/mcp"]

2. Lidar com Autenticação de Forma Segura

import os

# Armazenar chaves API em variáveis de ambiente
exa_key = os.getenv("EXA_API_KEY")
exa_profile = os.getenv("EXA_PROFILE")

agente = Agent(
    role="Agente Seguro",
    goal="Usar ferramentas MCP com segurança",
    backstory="Agente consciente da segurança",
    mcps=[f"https://mcp.exa.ai/mcp?api_key={exa_key}&profile={exa_profile}"]
)

3. Planejar para Falhas de Servidor

# Sempre incluir opções de backup
mcps=[
    "https://api-principal.com/mcp",       # Escolha principal
    "https://api-backup.com/mcp",          # Opção de backup
    "snowflake"                            # Fallback MCP conectado
]