# Fixing MCP Timeouts in AI Agents: The Async HandleId Pattern If you're building AI agents with the Model Context Protocol (MCP), you've probably hit this frustrating wall: your agent calls a tool that talks to a slow external API, the request times out, and you get a cryptic 424 error. The agent freezes. Your workflow breaks. The culprit? MCP's synchronous tool execution model doesn't play well with long-running operations. When your tool needs to wait for a third-party API that takes 30+ seconds to respond, the entire agent conversation blocks. The good news: there's a clean architectural pattern that solves this—the **async handleId pattern**. This tutorial walks through why MCP timeouts happen and how to implement the async handleId pattern to eliminate blocking operations in your AI agent tools. ## Why MCP Tools Timeout The Model Context Protocol expects tools to return results immediately. When you register a tool like `fetchWeatherData` or `runDatabaseQuery`, MCP assumes the response arrives in seconds—not minutes. Here's what happens with a naive implementation: ```python @mcp.tool() async def analyze_repository(repo_url: str): # This blocks for 45+ seconds result = await github_api.run_full_analysis(repo_url) return result ``` When the AI agent calls `analyze_repository`, the entire conversation halts. If GitHub's analysis API takes longer than your MCP server's timeout threshold (typically 30 seconds), you get a 424 Failed Dependency error. The agent can't proceed, can't retry intelligently, and the user sees a broken experience. This isn't just a GitHub problem—any integration with CI/CD pipelines, data processing jobs, or ML inference APIs hits the same bottleneck. ## The Async HandleId Pattern The solution is to separate *starting* a job from *getting* its results. Instead of one blocking tool, you create two non-blocking tools: 1. **Start tool**: Kicks off the long-running operation and immediately returns a job ID 2. **Poll tool**: Checks the status of a job ID and returns results when ready Here's the architecture: ```python import uuid from datetime import datetime # In-memory job store (use Redis/DB in production) jobs = {} @mcp.tool() async def start_repository_analysis(repo_url: str) -> dict: """Start analyzing a repository. Returns immediately with a job ID.""" job_id = str(uuid.uuid4()) jobs[job_id] = { "status": "running", "started_at": datetime.now().isoformat(), "result": None } # Kick off async background task asyncio.create_task(run_analysis(job_id, repo_url)) return { "job_id": job_id, "status": "started", "message": "Analysis started. Use get_analysis_result to check status." } @mcp.tool() async def get_analysis_result(job_id: str) -> dict: """Poll for analysis results by job ID.""" if job_id not in jobs: return {"error": "Job ID not found"} job = jobs[job_id] if job["status"] == "running": return { "status": "running", "message": "Analysis still in progress. Try again in 10 seconds." } return { "status": "completed", "result": job["result"] } async def run_analysis(job_id: str, repo_url: str): """Background worker that updates job status.""" try: result = await github_api.run_full_analysis(repo_url) jobs[job_id]["status"] = "completed" jobs[job_id]["result"] = result except Exception as e: jobs[job_id]["status"] = "failed" jobs[job_id]["error"] = str(e) ``` ## How the Agent Uses It When the AI agent needs repository analysis, it now follows a two-step dance: 1. **Call start_repository_analysis** → Gets back `{"job_id": "abc-123", "status": "started"}` 2. **Call get_analysis_result** periodically → Either gets `"running"` (poll again) or `"completed"` with results The beauty: both tool calls return instantly. No blocking. No timeouts. The agent can even do other work between polls—answer user questions, run other tools, or process multiple jobs in parallel. Modern AI models like Claude Opus 4.7 and GPT-4 handle this pattern naturally. They understand the polling contract from the tool descriptions and will retry `get_analysis_result` until the job completes. ## Production Considerations **Job Storage**: The example uses an in-memory dictionary. In production, use Redis with TTL expiration or a database table with a cleanup job. Jobs should expire after 1-24 hours depending on your use case. **Status Enrichment**: Include progress indicators when possible: ```python return { "status": "running", "progress": "Step 2/5: Analyzing dependencies", "estimated_completion": "2026-05-01T14:35:00Z" } ``` **Error Handling**: Distinguish between transient failures (retry) and permanent failures (abort): ```python if job["status"] == "failed": return { "status": "failed", "error": job["error"], "retryable": job.get("retryable", False) } ``` **Webhooks (Advanced)**: For very long jobs (hours), combine handleId polling with webhook notifications. Start the job with a callback URL, and let your backend notify the agent when results are ready. ## The Takeaway MCP's synchronous execution model is a feature, not a bug—it keeps most tool calls fast and predictable. But when you need to integrate slow external services, the async handleId pattern gives you the best of both worlds: non-blocking tools that never timeout, plus the flexibility for agents to manage long-running operations intelligently. Implement this pattern once, and every slow API integration becomes agent-friendly. Your 424 errors disappear, and your AI agents can finally orchestrate complex, real-world workflows without freezing. Next time you're tempted to increase MCP timeout limits, reach for the async handleId pattern instead. Your agents—and your users—will thank you.