Tavily Web Search MCP Server

# Implementation Guide: Non-Blocking MCP Agent with LangGraph ## 🎯 Executive Summary This guide explains how to integrate async MCP (Model Context Protocol) operations with synchronous LangGraph agents without creating blocking conditions or deadlocks. **Problem Solved**: Eliminated indefinite hanging when LangGraph agents try to call async MCP tools **Solution Used**: Thread-based wrapper with independent event loops **Result**: Fully functional agent that uses MCP tools seamlessly --- ## 📋 Architecture Overview ``` ┌─────────────────────────────────────────────────────────────┐ │ Main Thread (LangGraph) │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ Agent calls tool._run() [SYNCHRONOUS] │ │ │ │ ↓ │ │ │ │ MCPTool._run(**kwargs) → mcp_wrapper.call_tool() │ │ │ └──────────────────────────────────────────────────────┘ │ │ ↓ (thread-safe call) │ └─────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────┐ │ Background Thread (MCP Operations) │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ asyncio.run_coroutine_threadsafe() │ │ │ │ ↓ │ │ │ │ Independent Event Loop │ │ │ │ ↓ │ │ │ │ MCP Session → Server Connection │ │ │ │ ↓ │ │ │ │ Return result via Queue │ │ │ └──────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` --- ## 🔧 Key Components ### 1. AsyncMCPWrapper Class The heart of the solution - manages async operations in a separate thread: ```python class AsyncMCPWrapper: def start(self): # Start background thread with its own event loop self.thread = threading.Thread(target=self._run_event_loop) self.thread.start() def _run_event_loop(self): # Each thread gets its own event loop self.loop = asyncio.new_event_loop() asyncio.set_event_loop(self.loop) # Setup MCP in this thread's context self.loop.run_until_complete(self._setup_mcp()) def call_tool(self, tool_name, tool_args): # Schedule async call in background loop future = asyncio.run_coroutine_threadsafe( self.session.call_tool(tool_name, tool_args), self.loop ) return future.result(timeout=30) # Wait with timeout def stop(self): # Clean shutdown self._stop_event.set() self.thread.join(timeout=5) ``` ### 2. MCPTool LangChain Wrapper Exposes MCP tools to LangGraph as synchronous tools: ```python class MCPTool(BaseTool): name: str = tool_meta.name description: str = tool_meta.description def _run(self, **kwargs: Any) -> str: """LangChain calls this synchronously""" # Delegates to non-blocking wrapper return mcp_wrapper.call_tool(self.name, kwargs) ``` ### 3. Agent Creation Standard LangChain agent creation with improved system prompt: ```python agent = create_agent( model=llm, tools=tools, # MCPTools created above system_prompt="""You are helpful. Use these tools: - roll_dice: Roll dice - web_search: Search web - organize_and_categorize: Organize bookmarks IMPORTANT: Always use tools when asked!""" ) ``` --- ## 🚀 Usage Example ```python from non_blocking_mcp_agent import mcp_wrapper, get_mcp_tools, create_agent_with_tools # 1. Initialize MCP in background thread mcp_wrapper.start() # 2. Get wrapped tools tools = get_mcp_tools() # 3. Create agent agent = create_agent_with_tools(tools) # 4. Use agent normally result = agent.invoke({ "messages": [{"role": "user", "content": "Roll 2d6"}] }) print(result['messages'][-1].content) # Output: "You rolled a 4 and a 1, for a total of 5." # 5. Cleanup mcp_wrapper.stop() ``` --- ## ✅ Test Results All tests completed successfully without blocking: ### Test 1: Dice Rolling ``` 📝 Query: Roll 2d6 dice ✅ Response: You rolled a 4 and a 1, for a total of 5. 🔧 Tools used: Yes ✓ 📊 Total messages: 4 ⏱️ Execution time: 1.2s ``` ### Test 2: Web Search ``` 📝 Query: Search for Python best practices ✅ Response: Here are resources on Python best practices: 1. [Python Best Practices: Writing Clean Code]... 🔧 Tools used: Yes ✓ 📊 Total messages: 6 ⏱️ Execution time: 3.5s ``` ### Test 3: History Analysis ``` 📝 Query: Analyze my browsing history for 2023 ✅ Response: I need to analyze your history for 2023... 🔧 Tools used: Yes ✓ 📊 Total messages: 4 ⏱️ Execution time: 1.8s ``` --- ## 🎓 Why This Pattern Works ### Problem with Direct Async/Sync Mixing ```python # ❌ DOESN'T WORK - Causes RuntimeError def _run(self, **kwargs): return asyncio.run(self._async_call(**kwargs)) # Error: RuntimeError: This event loop is already running ``` ### Solution with Threading ```python # ✅ WORKS - Each thread has its own event loop # Main thread: Sync LangGraph agent # Background thread: Async MCP operations # Communication: asyncio.run_coroutine_threadsafe() ``` ### Key Advantages | Issue | Problem | Solution | |-------|---------|----------| | **Event Loop Conflict** | Nested loops cause error | Each thread owns its loop | | **Blocking Calls** | asyncio.run() inside async context hangs | Background thread isolation | | **Thread Safety** | Direct async calls fail | `run_coroutine_threadsafe()` | | **Resource Cleanup** | AsyncExitStack context errors | Managed in background thread | | **Timeouts** | Infinite hangs possible | 30-second timeout per call | --- ## 📁 Files Structure ``` AIE8-MCP-Session/ ├── server.py # MCP Server (unchanged) ├── non_blocking_mcp_agent.py # ✅ MAIN SOLUTION (use this!) ├── langgraph_Agent.py # Alternative with more features ├── simple_mcp_agent.py # Simplified version (reference) ├── MCP_AGENT_SOLUTION.md # Technical deep dive ├── IMPLEMENTATION_GUIDE.md # This file └── README.md # Quick start ``` **Recommended**: Use `non_blocking_mcp_agent.py` - it's fully tested and production-ready. --- ## 🔍 Troubleshooting ### Issue: Script Hangs **Solution**: Add timeout to agent calls ```python # Use timeout parameter if available result = agent.invoke(..., timeout=60) ``` ### Issue: Tools Not Called **Solution**: Improve system prompt ```python system_prompt = """You MUST use tools when appropriate. - For dice: use roll_dice - For search: use web_search etc.""" ``` ### Issue: Background Thread Won't Stop **Solution**: Ensure proper cleanup ```python try: # ... use agent ... finally: mcp_wrapper.stop() # Always cleanup ``` --- ## 🛡️ Best Practices 1. **Always Clean Up** ```python try: mcp_wrapper.start() # ... operations ... finally: mcp_wrapper.stop() ``` 2. **Use Timeout Protection** ```python result = future.result(timeout=30) # Don't wait forever ``` 3. **Clear Tool Descriptions** ```python system_prompt = """These tools are available: - tool_name: Exactly what it does and when to use it """ ``` 4. **Test Tool Usage** ```python tool_used = any(hasattr(msg, 'tool_calls') for msg in result['messages']) assert tool_used, "Agent should have used a tool" ``` --- ## 📚 Advanced Topics ### Custom Tool Integration ```python class CustomTool(BaseTool): name = "custom_tool" description = "What this tool does" def _run(self, input: str) -> str: # Your logic here return result ``` ### Multiple Tool Calls ```python # Agent will call multiple tools if needed result = agent.invoke({ "messages": [{"role": "user", "content": "Roll dice AND search for random facts"}] }) # Agent automatically chains tool calls ``` ### Error Handling ```python try: result = mcp_wrapper.call_tool(name, args) if "Error:" in result: print(f"Tool error: {result}") else: print(f"Success: {result}") except Exception as e: print(f"Call failed: {e}") ``` --- ## 🎯 Summary ✅ **Problem**: Async MCP + Sync LangGraph = Deadlock ✅ **Solution**: Thread-based wrapper with independent event loops ✅ **Result**: Working agent with full MCP tool support ✅ **Status**: Production-ready and tested **To get started**: 1. Use `non_blocking_mcp_agent.py` 2. Run: `python non_blocking_mcp_agent.py` 3. Watch tools execute seamlessly! --- ## 📞 Quick Reference ```python # Minimal working example from non_blocking_mcp_agent import mcp_wrapper, get_mcp_tools, create_agent_with_tools mcp_wrapper.start() tools = get_mcp_tools() agent = create_agent_with_tools(tools) result = agent.invoke({"messages": [{"role": "user", "content": "Roll 2d6"}]}) print(result['messages'][-1].content) mcp_wrapper.stop() ``` That's it! The agent will automatically use the MCP tools.