Timeouts MCP : diagnostiquer et corriger les réponses lentes
Solve MCP timeout errors caused by slow networks, large payloads, or rate limits. Learn pagination strategies, batching techniques, and connection optimization to speed up your MCP workflows.
Understanding Timeout Errors
A timeout occurs when an MCP operation takes longer than the client's configured timeout limit (typically 30-60 seconds). The request is cancelled and you see an error.
Common Timeout Symptoms
- Request hangs and eventually fails
- Error message: "Request timeout" or "Connection timeout"
- Operation takes longer than 30-60 seconds
- Works for small queries but fails for large ones
Common Causes
1. Large Result Sets
Querying too many tasks at once overwhelms the connection:
Problem
Running list_tasks without filters returns 1000+ tasks, causing timeout.
Solution: Use Pagination
Limit results per request and page through them:
// Instead of fetching all tasks at once
list_tasks(limit=50, page=1) // First 50 tasks
list_tasks(limit=50, page=2) // Next 50 tasks2. Slow Network Connection
Poor internet connectivity causes delays:
Diagnostic Steps
- Test network speed: Run speed test to check connection
- Check latency: Ping api.corcava.com to measure delay
- Try smaller queries: If small queries work but large ones fail, it's likely network bandwidth
Solutions
- Use WiFi over VPN: VPNs add latency - try direct connection
- Reduce result size: Use filters and pagination
- Retry with backoff: Implement exponential backoff for retries
3. Rate Limiting
Making too many requests too quickly can trigger rate limits:
Symptoms
- Requests start fast but slow down over time
- 429 Rate Limited errors appear
- First few requests succeed, then timeout
Solution
See Rate Limit Troubleshooting for detailed fixes.
4. Complex Queries
Operations that involve heavy processing take longer:
Slow Operations
- Cross-project queries: Searching tasks across 10+ projects
- Date range queries: Fetching tasks from last 2 years
- Unfiltered lists: Getting all tasks with no filters
Optimization Tips
- Add filters: status, project_id, assignee to narrow results
- Use smaller date ranges: Last 30 days instead of all time
- Query one project at a time instead of all projects
- Use pagination: Limit to 50-100 results per request
Solutions and Best Practices
1. Implement Pagination
Pagination Pattern
Break large queries into smaller pages:
// Fetch tasks in batches of 50
page = 1
all_tasks = []
while True:
batch = list_tasks(limit=50, page=page)
if batch is empty:
break
all_tasks.extend(batch)
page += 12. Use Filters Aggressively
Filter Examples
// Instead of:
list_tasks() // Returns all tasks
// Use filters:
list_tasks(
status="in_progress",
project_id=123,
assigned_to="[email protected]",
created_after="2026-01-01"
)3. Batch Read Operations
Batching Strategy
If you need details for multiple tasks, batch the requests:
- Get task IDs with list_tasks (lightweight)
- Batch get_task calls in groups of 10-20
- Add small delay between batches (100-200ms)
See Batching Guide for details.
4. Increase Client Timeout
Configure Longer Timeouts
Some clients allow timeout configuration:
- Cursor: Check settings for timeout override
- Continue: Configure in config.json
- Custom clients: Set timeout to 90-120 seconds
Note: Increasing timeout is a workaround. Better to optimize queries.
Debugging Checklist
- Measure query size: How many results are you fetching?
- Add filters: Can you narrow the query with status, project, or date filters?
- Test pagination: Does fetching 50 results work while 500 fails?
- Check network: Test with speed test and ping to api.corcava.com
- Try simpler query: Does get_task (single task) work?
- Monitor rate limits: Are you seeing 429 errors?