mirror of
https://github.com/crewAIInc/crewAI.git
synced 2025-12-16 04:18:35 +00:00
345 lines
9.5 KiB
Plaintext
345 lines
9.5 KiB
Plaintext
---
|
|
title: MCP DSL Integration
|
|
description: Learn how to use CrewAI's simple DSL syntax to integrate MCP servers directly with your agents using the mcps field.
|
|
icon: code
|
|
mode: "wide"
|
|
---
|
|
|
|
## Overview
|
|
|
|
CrewAI's MCP DSL (Domain Specific Language) integration provides the **simplest way** to connect your agents to MCP (Model Context Protocol) servers. Just add an `mcps` field to your agent and CrewAI handles all the complexity automatically.
|
|
|
|
<Info>
|
|
This is the **recommended approach** for most MCP use cases. For advanced scenarios requiring manual connection management, see [MCPServerAdapter](/en/mcp/overview#advanced-mcpserveradapter).
|
|
</Info>
|
|
|
|
## Basic Usage
|
|
|
|
Add MCP servers to your agent using the `mcps` field:
|
|
|
|
```python
|
|
from crewai import Agent
|
|
|
|
agent = Agent(
|
|
role="Research Assistant",
|
|
goal="Help with research and analysis tasks",
|
|
backstory="Expert assistant with access to advanced research tools",
|
|
mcps=[
|
|
"https://mcp.exa.ai/mcp?api_key=your_key&profile=research"
|
|
]
|
|
)
|
|
|
|
# MCP tools are now automatically available!
|
|
# No need for manual connection management or tool configuration
|
|
```
|
|
|
|
## Supported Reference Formats
|
|
|
|
### External MCP Remote Servers
|
|
|
|
```python
|
|
# Basic HTTPS server
|
|
"https://api.example.com/mcp"
|
|
|
|
# Server with authentication
|
|
"https://mcp.exa.ai/mcp?api_key=your_key&profile=your_profile"
|
|
|
|
# Server with custom path
|
|
"https://services.company.com/api/v1/mcp"
|
|
```
|
|
|
|
### Specific Tool Selection
|
|
|
|
Use the `#` syntax to select specific tools from a server:
|
|
|
|
```python
|
|
# Get only the forecast tool from weather server
|
|
"https://weather.api.com/mcp#get_forecast"
|
|
|
|
# Get only the search tool from Exa
|
|
"https://mcp.exa.ai/mcp?api_key=your_key#web_search_exa"
|
|
```
|
|
|
|
### CrewAI AOP Marketplace
|
|
|
|
Access tools from the CrewAI AOP marketplace:
|
|
|
|
```python
|
|
# Full service with all tools
|
|
"crewai-amp:financial-data"
|
|
|
|
# Specific tool from AMP service
|
|
"crewai-amp:research-tools#pubmed_search"
|
|
|
|
# Multiple AMP services
|
|
mcps=[
|
|
"crewai-amp:weather-insights",
|
|
"crewai-amp:market-analysis",
|
|
"crewai-amp:social-media-monitoring"
|
|
]
|
|
```
|
|
|
|
## Complete Example
|
|
|
|
Here's a complete example using multiple MCP servers:
|
|
|
|
```python
|
|
from crewai import Agent, Task, Crew, Process
|
|
|
|
# Create agent with multiple MCP sources
|
|
multi_source_agent = Agent(
|
|
role="Multi-Source Research Analyst",
|
|
goal="Conduct comprehensive research using multiple data sources",
|
|
backstory="""Expert researcher with access to web search, weather data,
|
|
financial information, and academic research tools""",
|
|
mcps=[
|
|
# External MCP servers
|
|
"https://mcp.exa.ai/mcp?api_key=your_exa_key&profile=research",
|
|
"https://weather.api.com/mcp#get_current_conditions",
|
|
|
|
# CrewAI AOP marketplace
|
|
"crewai-amp:financial-insights",
|
|
"crewai-amp:academic-research#pubmed_search",
|
|
"crewai-amp:market-intelligence#competitor_analysis"
|
|
]
|
|
)
|
|
|
|
# Create comprehensive research task
|
|
research_task = Task(
|
|
description="""Research the impact of AI agents on business productivity.
|
|
Include current weather impacts on remote work, financial market trends,
|
|
and recent academic publications on AI agent frameworks.""",
|
|
expected_output="""Comprehensive report covering:
|
|
1. AI agent business impact analysis
|
|
2. Weather considerations for remote work
|
|
3. Financial market trends related to AI
|
|
4. Academic research citations and insights
|
|
5. Competitive landscape analysis""",
|
|
agent=multi_source_agent
|
|
)
|
|
|
|
# Create and execute crew
|
|
research_crew = Crew(
|
|
agents=[multi_source_agent],
|
|
tasks=[research_task],
|
|
process=Process.sequential,
|
|
verbose=True
|
|
)
|
|
|
|
result = research_crew.kickoff()
|
|
print(f"Research completed with {len(multi_source_agent.mcps)} MCP data sources")
|
|
```
|
|
|
|
## Tool Naming and Organization
|
|
|
|
CrewAI automatically handles tool naming to prevent conflicts:
|
|
|
|
```python
|
|
# Original MCP server has tools: "search", "analyze"
|
|
# CrewAI creates tools: "mcp_exa_ai_search", "mcp_exa_ai_analyze"
|
|
|
|
agent = Agent(
|
|
role="Tool Organization Demo",
|
|
goal="Show how tool naming works",
|
|
backstory="Demonstrates automatic tool organization",
|
|
mcps=[
|
|
"https://mcp.exa.ai/mcp?api_key=key", # Tools: mcp_exa_ai_*
|
|
"https://weather.service.com/mcp", # Tools: weather_service_com_*
|
|
"crewai-amp:financial-data" # Tools: financial_data_*
|
|
]
|
|
)
|
|
|
|
# Each server's tools get unique prefixes based on the server name
|
|
# This prevents naming conflicts between different MCP servers
|
|
```
|
|
|
|
## Error Handling and Resilience
|
|
|
|
The MCP DSL is designed to be robust and user-friendly:
|
|
|
|
### Graceful Server Failures
|
|
|
|
```python
|
|
agent = Agent(
|
|
role="Resilient Researcher",
|
|
goal="Research despite server issues",
|
|
backstory="Experienced researcher who adapts to available tools",
|
|
mcps=[
|
|
"https://primary-server.com/mcp", # Primary data source
|
|
"https://backup-server.com/mcp", # Backup if primary fails
|
|
"https://unreachable-server.com/mcp", # Will be skipped with warning
|
|
"crewai-amp:reliable-service" # Reliable AMP service
|
|
]
|
|
)
|
|
|
|
# Agent will:
|
|
# 1. Successfully connect to working servers
|
|
# 2. Log warnings for failing servers
|
|
# 3. Continue with available tools
|
|
# 4. Not crash or hang on server failures
|
|
```
|
|
|
|
### Timeout Protection
|
|
|
|
All MCP operations have built-in timeouts:
|
|
|
|
- **Connection timeout**: 10 seconds
|
|
- **Tool execution timeout**: 30 seconds
|
|
- **Discovery timeout**: 15 seconds
|
|
|
|
```python
|
|
# These servers will timeout gracefully if unresponsive
|
|
mcps=[
|
|
"https://slow-server.com/mcp", # Will timeout after 10s if unresponsive
|
|
"https://overloaded-api.com/mcp" # Will timeout if discovery takes > 15s
|
|
]
|
|
```
|
|
|
|
## Performance Features
|
|
|
|
### Automatic Caching
|
|
|
|
Tool schemas are cached for 5 minutes to improve performance:
|
|
|
|
```python
|
|
# First agent creation - discovers tools from server
|
|
agent1 = Agent(role="First", goal="Test", backstory="Test",
|
|
mcps=["https://api.example.com/mcp"])
|
|
|
|
# Second agent creation (within 5 minutes) - uses cached tool schemas
|
|
agent2 = Agent(role="Second", goal="Test", backstory="Test",
|
|
mcps=["https://api.example.com/mcp"]) # Much faster!
|
|
```
|
|
|
|
### On-Demand Connections
|
|
|
|
Tool connections are established only when tools are actually used:
|
|
|
|
```python
|
|
# Agent creation is fast - no MCP connections made yet
|
|
agent = Agent(
|
|
role="On-Demand Agent",
|
|
goal="Use tools efficiently",
|
|
backstory="Efficient agent that connects only when needed",
|
|
mcps=["https://api.example.com/mcp"]
|
|
)
|
|
|
|
# MCP connection is made only when a tool is actually executed
|
|
# This minimizes connection overhead and improves startup performance
|
|
```
|
|
|
|
## Integration with Existing Features
|
|
|
|
MCP tools work seamlessly with other CrewAI features:
|
|
|
|
```python
|
|
from crewai.tools import BaseTool
|
|
|
|
class CustomTool(BaseTool):
|
|
name: str = "custom_analysis"
|
|
description: str = "Custom analysis tool"
|
|
|
|
def _run(self, **kwargs):
|
|
return "Custom analysis result"
|
|
|
|
agent = Agent(
|
|
role="Full-Featured Agent",
|
|
goal="Use all available tool types",
|
|
backstory="Agent with comprehensive tool access",
|
|
|
|
# All tool types work together
|
|
tools=[CustomTool()], # Custom tools
|
|
apps=["gmail", "slack"], # Platform integrations
|
|
mcps=[ # MCP servers
|
|
"https://mcp.exa.ai/mcp?api_key=key",
|
|
"crewai-amp:research-tools"
|
|
],
|
|
|
|
verbose=True,
|
|
max_iter=15
|
|
)
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
### 1. Use Specific Tools When Possible
|
|
|
|
```python
|
|
# Good - only get the tools you need
|
|
mcps=["https://weather.api.com/mcp#get_forecast"]
|
|
|
|
# Less efficient - gets all tools from server
|
|
mcps=["https://weather.api.com/mcp"]
|
|
```
|
|
|
|
### 2. Handle Authentication Securely
|
|
|
|
```python
|
|
import os
|
|
|
|
# Store API keys in environment variables
|
|
exa_key = os.getenv("EXA_API_KEY")
|
|
exa_profile = os.getenv("EXA_PROFILE")
|
|
|
|
agent = Agent(
|
|
role="Secure Agent",
|
|
goal="Use MCP tools securely",
|
|
backstory="Security-conscious agent",
|
|
mcps=[f"https://mcp.exa.ai/mcp?api_key={exa_key}&profile={exa_profile}"]
|
|
)
|
|
```
|
|
|
|
### 3. Plan for Server Failures
|
|
|
|
```python
|
|
# Always include backup options
|
|
mcps=[
|
|
"https://primary-api.com/mcp", # Primary choice
|
|
"https://backup-api.com/mcp", # Backup option
|
|
"crewai-amp:reliable-service" # AMP fallback
|
|
]
|
|
```
|
|
|
|
### 4. Use Descriptive Agent Roles
|
|
|
|
```python
|
|
agent = Agent(
|
|
role="Weather-Enhanced Market Analyst",
|
|
goal="Analyze markets considering weather impacts",
|
|
backstory="Financial analyst with access to weather data for agricultural market insights",
|
|
mcps=[
|
|
"https://weather.service.com/mcp#get_forecast",
|
|
"crewai-amp:financial-data#stock_analysis"
|
|
]
|
|
)
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
**No tools discovered:**
|
|
```python
|
|
# Check your MCP server URL and authentication
|
|
# Verify the server is running and accessible
|
|
mcps=["https://mcp.example.com/mcp?api_key=valid_key"]
|
|
```
|
|
|
|
**Connection timeouts:**
|
|
```python
|
|
# Server may be slow or overloaded
|
|
# CrewAI will log warnings and continue with other servers
|
|
# Check server status or try backup servers
|
|
```
|
|
|
|
**Authentication failures:**
|
|
```python
|
|
# Verify API keys and credentials
|
|
# Check server documentation for required parameters
|
|
# Ensure query parameters are properly URL encoded
|
|
```
|
|
|
|
## Advanced: MCPServerAdapter
|
|
|
|
For complex scenarios requiring manual connection management, use the `MCPServerAdapter` class from `crewai-tools`. Using a Python context manager (`with` statement) is the recommended approach as it automatically handles starting and stopping the connection to the MCP server.
|