Tavily Web Search MCP Server

# MCP + LangGraph Architecture Guide ## How It All Works Together ### 🏗️ Architecture Overview ``` User Input → LangGraph Agent → MCP Client → MCP Server → Cal.com API ↑ ↓ User Output ← LangGraph Agent ← MCP Client ← MCP Server ← API Response ``` ### 🧩 Key Components #### 1. **LangGraph Agent** (`cal_langgraph_app.py`) - **Purpose**: Orchestrates the conversation and tool usage - **Pattern**: ReAct (Reasoning + Acting) - **How it works**: - Receives user input in natural language - LLM (GPT-4o-mini) analyzes what tools are needed - Executes tool calls via MCP - Processes results and responds in natural language #### 2. **MCP Client** (`MultiServerMCPClient`) - **Purpose**: Bridge between LangChain and MCP servers - **Transport**: `stdio` (standard input/output) - **How it works**: - Starts `myserver.py` as a subprocess - Converts LangChain tool calls to MCP protocol - Handles communication via stdin/stdout #### 3. **MCP Server** (`myserver.py`) - **Purpose**: Exposes Cal.com API as MCP tools - **Tools provided**: - `cal_list_event_types()` - List your event types - `cal_list_bookings()` - Show bookings - `cal_get_availability()` - Check availability - `cal_create_booking()` - Create bookings - `cal_cancel_booking()` - Cancel bookings - Plus: `web_search()`, `roll_dice()` #### 3b. **MCP Server (safer variant)** (`improved_server.py`) - **Purpose**: Same Cal.com tools with stronger guardrails and clearer docstrings - **Notes**: Emphasizes read-only vs. destructive actions, adds defensive error handling #### 4. **Cal.com API** - **Purpose**: The actual calendar service - **Authentication**: API key in `.env` - **Operations**: HTTP requests to `api.cal.com/v1/` ### 🔄 Request Flow Example When you ask **"Show my upcoming bookings"**: 1. **LangGraph Agent**: Receives user input 2. **LLM Decision**: "I need to call cal_list_bookings tool" 3. **MCP Client**: Converts to MCP tool call 4. **MCP Server**: Receives tool call via stdio 5. **Cal.com API**: Server makes HTTP request 6. **Response Chain**: Data flows back through the chain 7. **Final Output**: "You have 3 upcoming bookings: ..." ### 🛠️ Why This Architecture? #### **Benefits of MCP**: - **Standardized**: One protocol for all external tools - **Secure**: Tools run in separate processes - **Reusable**: Same MCP server works with any MCP client - **Maintainable**: Clear separation of concerns #### **Benefits of LangGraph**: - **Intelligent**: LLM decides which tools to use - **Conversational**: Natural language interface - **Extensible**: Easy to add more tools - **Robust**: Built-in error handling and retries ### 📁 File Structure ``` MCP-Session-Code/ ├── myserver.py # MCP server with Cal.com tools ├── improved_server.py # Safer variant of the MCP server with clearer guardrails ├── cal_langgraph_app.py # Standalone LangGraph application ├── debug_agent.py # Debugging agent that logs tool calls/decisions ├── mcp-test.ipynb # Jupyter prototype ├── server.py # Original MCP server (Tavily, dice, etc.) └── .env # API keys (create this!) ``` ### 🚀 Running the Application 1. **Setup environment**: ```bash echo "OPENAI_API_KEY=your_key" > .env echo "CALCOM_API_KEY=your_key" >> .env ``` 2. **Run the application**: ```bash python cal_langgraph_app.py ``` 3. **Try queries**: - "List my event types" - "Show my bookings" - "Search for Cal.com pricing" ### 🎯 Key Learning Points 1. **MCP Protocol**: Standardizes how AI applications connect to external services 2. **LangGraph Pattern**: Agent orchestrates multiple tool calls intelligently 3. **Separation of Concerns**: Each component has a clear responsibility 4. **Async Architecture**: Everything runs asynchronously for better performance 5. **Tool Composability**: Mix different tools (Cal.com + web search + dice) seamlessly This architecture demonstrates modern AI application patterns: using LLMs for orchestration, MCP for tool integration, and LangGraph for robust agent behavior.