feat: Implement CredentialWatch agent with MCP client, main entry point, interactive query agent, and various debugging utilities.

README.md

@@ -10,3 +10,172 @@ pinned: false
 python_version: 3.11
 ---
 
+# CredentialWatch 🛡️
+
+**CredentialWatch** is a demo product for the **"MCP 1st Birthday / Gradio Agents Hackathon" (Hugging Face)**.
+
+## 0. What I’m building (TL;DR)
+
+- **Domain:** US-style healthcare admin / provider credentialing & expiries (state licenses, board certs, DEA/CDS, malpractice, hospital privileges, etc.).
+- **Goal:** Show how **Model Context Protocol (MCP)** + **LangGraph agents** + **Gradio** + **Modal** + **SQLite** can turn messy, fragmented credential data into:
+  - One unified, queryable view of each provider, and
+  - A proactive alerting system for expiring / at-risk credentials.
+- **Constraint:** Use only open / public tools & APIs (no closed vendor APIs, no real PHI).
+
+## 1. Problem & motivation
+
+**Real-world (simplified):**
+
+- Provider groups (clinics, hospitals, multi-specialty practices) have **dozens of contracts** with different health plans and institutions.
+- Multiple credentials can expire or go stale:
+  - State licenses, board certifications, DEA/CDS numbers,
+  - Malpractice insurance,
+  - Hospital privileges, etc.
+- Today:
+  - Each health plan / hospital sends its own emails / portal tasks asking to update credentials and directory data.
+  - Staff maintain local **spreadsheets, trackers, email threads**, often with inconsistent formats.
+- It’s easy to miss an expiry, leading to:
+  - Compliance issues,
+  - Denied claims (revenue loss),
+  - Inability to schedule or bill a provider after a certain date.
+
+**CredentialWatch acts as a central radar:**
+> “For all my providers, tell me what’s expiring when, what’s high risk, and log alerts we can action.”
+
+## 2. Solution concept
+
+CredentialWatch provides:
+
+- A single, internal **“source-of-truth” SQLite DB** for providers, credentials and alerts.
+- **Three separate MCP servers** (strict separation of concerns, each can be its own HF Space/repo):
+  1. `npi_mcp` → read-only public provider info from **NPPES NPI Registry API**.
+  2. `cred_db_mcp` → internal provider & credential DB operations.
+  3. `alert_mcp` → alert logging, listing & resolution.
+- A **LangGraph-based agent** that:
+  - Periodically runs an **expiry sweep** and logs alerts.
+  - Answers free-text questions like:
+    - “Who has credentials expiring in the next 60 days in Cardiology?”
+    - “Show me the credential snapshot for Dr. Jane Doe.”
+- A **Gradio UI** where:
+  - Judges/users chat with the agent,
+  - They can click a “Run Nightly Sweep” button,
+  - They see tables for “expiring soon” and an **Alert Inbox**.
+
+## 3. Hackathon & design constraints
+
+- **Event:** Hugging Face – MCP 1st Birthday / Gradio Agents Hackathon.
+- **Judging goals:**
+  - Strong MCP usage (tools/resources as first-class interfaces).
+  - Agentic sophistication: planning, multi-step tool use, long-running flows.
+  - Clear UX/Teachability.
+
+**Constraints & safety:**
+- Only **public / open APIs** (NPPES NPI Registry, OpenAI GPT).
+- No real PHI: use synthetic/internal IDs + public NPI data.
+- Safety boundaries:
+  - Read-only to **external** systems.
+  - Writes only to **internal** SQLite DB.
+
+## 4. Tech stack 🧱
+
+- **Language:** Python 3.11
+- **Package management:** `uv`
+- **Frontend / UI:** Gradio 6 (Hosted as a Hugging Face Space)
+- **Agents:** LangGraph (Python)
+- **LLM:** OpenAI `gpt-5.1` (or `gpt-4o`)
+- **Tool protocol:** Model Context Protocol (MCP), via SSE.
+- **Backend web framework:** FastAPI, running on **Modal**.
+- **Database:** SQLite, persisted on a Modal volume.
+- **ORM:** SQLAlchemy 2.x.
+
+## 5. Architecture overview 🧩
+
+### Logical components
+
+**HF Space #1 – Agent UI (`credentialwatch-agent-ui`)**
+- Gradio frontend.
+- LangGraph agent runtime (`expiry_sweep_graph`, `interactive_query_graph`).
+- MCP client configured for 3 remote MCP servers (via SSE).
+
+**HF Space #2 – `npi_mcp`**
+- MCP server for **NPI/NPPES** tools (`search_providers`, `get_provider_by_npi`).
+- Calls `NPI_API` FastAPI service on Modal.
+
+**HF Space #3 – `cred_db_mcp`**
+- MCP server for internal data tools (`sync_provider_from_npi`, `add_or_update_credential`, etc.).
+- Calls `CRED_API` FastAPI service on Modal.
+
+**HF Space #4 – `alert_mcp`**
+- MCP server for alert tools (`log_alert`, `get_open_alerts`, etc.).
+- Calls `ALERT_API` FastAPI service on Modal.
+
+**Modal backend**
+- **FastAPI microservices**: `NPI_API`, `CRED_API`, `ALERT_API`.
+- Shared **SQLite DB** on a Modal volume.
+
+## 6. The 3 MCP servers – separation of concerns 🧱
+
+### 6.1 `npi_mcp`
+Read-only access to public provider data.
+- `search_providers(query, state?, taxonomy?)`
+- `get_provider_by_npi(npi)`
+
+### 6.2 `cred_db_mcp`
+Interface to internal provider & credential data.
+- `sync_provider_from_npi(npi)`
+- `add_or_update_credential(...)`
+- `list_expiring_credentials(...)`
+- `get_provider_snapshot(...)`
+
+### 6.3 `alert_mcp`
+Manage alerts generated by the agent.
+- `log_alert(...)`
+- `get_open_alerts(...)`
+- `mark_alert_resolved(...)`
+
+## 7. Agent behaviors (LangGraph) 🧠
+
+### 7.1 `expiry_sweep_graph`
+Batch / nightly graph.
+1. Call `cred_db_mcp.list_expiring_credentials`.
+2. Decide severity.
+3. Call `alert_mcp.log_alert`.
+
+### 7.2 `interactive_query_graph`
+Chat / Q&A graph (ReAct-style).
+- Plans tool calls (NPI, DB, Alerts).
+- Summarizes results.
+
+## 8. Database model 🗄️
+
+**DB engine:** SQLite on Modal volume.
+
+- `providers`: Internal provider records.
+- `credentials`: Licenses, certifications, etc.
+- `alerts`: Generated alerts for expiries.
+
+---
+
+## How to Run Locally
+
+To run the CredentialWatch Agent UI locally:
+
+1.  **Prerequisites:**
+    - Python 3.11+
+    - `uv` package manager
+
+2.  **Environment Variables:**
+    Create a `.env` file or set the following environment variables:
+    ```bash
+    OPENAI_API_KEY=sk-...
+    # URLs for your deployed MCP servers (or local if running locally)
+    NPI_MCP_URL=https://<your-npi-space>.hf.space/sse
+    CRED_DB_MCP_URL=https://<your-cred-db-space>.hf.space/sse
+    ALERT_MCP_URL=https://<your-alert-space>.hf.space/sse
+    ```
+
+3.  **Run the Agent:**
+    ```bash
+    uv run -m credentialwatch_agent.main
+    ```
+    This will start the Gradio interface locally at `http://localhost:7860`.

debug_mcp.py

@@ -0,0 +1,61 @@
+import asyncio
+import os
+import sys
+import logging
+from dotenv import load_dotenv
+
+# Add src to path
+sys.path.append(os.path.join(os.path.dirname(__file__), "src"))
+
+# Load env vars
+load_dotenv(".env.local")
+
+# Configure logging
+logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+logger = logging.getLogger("debug_mcp")
+logger.setLevel(logging.DEBUG)
+
+# Silence noisy loggers
+logging.getLogger("httpcore").setLevel(logging.WARNING)
+logging.getLogger("httpx").setLevel(logging.WARNING)
+
+from credentialwatch_agent.mcp_client import mcp_client
+
+async def debug_mcp():
+    logger.info("Starting MCP debug script...")
+    
+    # Check environment variables
+    logger.info(f"NPI_MCP_URL: {os.getenv('NPI_MCP_URL')}")
+    logger.info(f"CRED_DB_MCP_URL: {os.getenv('CRED_DB_MCP_URL')}")
+    logger.info(f"ALERT_MCP_URL: {os.getenv('ALERT_MCP_URL')}")
+
+    try:
+        logger.info("Connecting to MCP servers...")
+        await mcp_client.connect()
+        logger.info("Connected to MCP servers.")
+    except Exception as e:
+        logger.error(f"Failed to connect to MCP servers: {e}", exc_info=True)
+        return
+
+    # Test NPI Tool
+    logger.info("\n--- Testing NPI Tool: search_providers ---")
+    try:
+        result = await mcp_client.call_tool("npi", "search_providers", {"query": "cardiology"})
+        logger.info(f"NPI Tool Result: {result}")
+    except Exception as e:
+        logger.error(f"NPI Tool Call Failed: {e}", exc_info=True)
+
+    # Test Cred DB Tool
+    logger.info("\n--- Testing Cred DB Tool: list_expiring_credentials ---")
+    try:
+        result = await mcp_client.call_tool("cred_db", "list_expiring_credentials", {"window_days": 90})
+        logger.info(f"Cred DB Tool Result: {result}")
+    except Exception as e:
+        logger.error(f"Cred DB Tool Call Failed: {e}", exc_info=True)
+
+    logger.info("\nClosing connections...")
+    await mcp_client.close()
+    logger.info("Done.")
+
+if __name__ == "__main__":
+    asyncio.run(debug_mcp())

diagnose_url.py

@@ -0,0 +1,56 @@
+import httpx
+import asyncio
+import os
+from dotenv import load_dotenv
+
+load_dotenv(".env.local")
+
+async def diagnose():
+    url = os.getenv("NPI_MCP_URL")
+    print(f"Testing URL: {url}")
+    
+    if not url:
+        print("URL not found in env vars.")
+        return
+
+    try:
+        async with httpx.AsyncClient() as client:
+            print("Sending GET request...")
+            response = await client.get(url, timeout=10.0)
+            print(f"Status Code: {response.status_code}")
+            print("Headers:")
+            for k, v in response.headers.items():
+                print(f"  {k}: {v}")
+            print(f"Content (first 200 chars): {response.text[:200]}")
+    except httpx.TimeoutException:
+        print("Request timed out.")
+    except Exception as e:
+        print(f"Error: {e}")
+
+    # Try with SSE headers and streaming
+    try:
+        async with httpx.AsyncClient() as client:
+            print("\nSending GET request with Accept: text/event-stream (streaming)...")
+            headers = {"Accept": "text/event-stream"}
+            async with client.stream("GET", url, headers=headers, timeout=10.0) as response:
+                print(f"Status Code: {response.status_code}")
+                print("Headers:")
+                for k, v in response.headers.items():
+                    print(f"  {k}: {v}")
+                
+                print("\nReading stream...")
+                count = 0
+                async for line in response.aiter_lines():
+                    if line:
+                        print(f"Received: {line}")
+                    count += 1
+                    if count >= 20:
+                        print("Reached limit of 20 lines. Stopping.")
+                        break
+    except httpx.TimeoutException:
+        print("Request timed out (SSE stream).")
+    except Exception as e:
+        print(f"Error (SSE): {e}")
+
+if __name__ == "__main__":
+    asyncio.run(diagnose())

openapi.json

@@ -0,0 +1 @@
+{"openapi":"3.1.0","info":{"title":"CredentialWatch Backend","version":"0.1.0"},"paths":{}}

output.txt

@@ -0,0 +1,16 @@
+Attempting to connect to MCP servers...
+NPI URL: https://humanlearning-npi-mcp.hf.space/gradio_api/mcp/
+Cred DB URL: https://humanlearning-cred-db-mcp.hf.space/gradio_api/mcp/
+Alert URL: https://humanlearning-alert-mcp.hf.space/gradio_api/mcp/
+2025-12-02 19:44:53,542 - mcp_client - INFO - Initializing MultiServerMCPClient...
+2025-12-02 19:44:58,019 - mcp_client - INFO - Successfully connected. Loaded 11 tools.
+Mock mode: False
+Connected: True
+Loaded tools: ['npi_mcp_search_providers_tool', 'npi_mcp_get_provider_by_npi_tool', 'npi_mcp_run_diagnostics', 'cred_db_mcp_sync_provider_from_npi', 'cred_db_mcp_add_or_update_credential', 'cred_db_mcp_list_expiring_credentials', 'cred_db_mcp_get_provider_snapshot', 'alert_mcp_log_alert', 'alert_mcp_get_open_alerts', 'alert_mcp_mark_alert_resolved', 'alert_mcp_summarize_alerts']
+
+Testing NPI tool call...
+2025-12-02 19:45:02,270 - mcp_client - WARNING - Tool 'search_providers' not found in loaded tools. Using mock if available.
+2025-12-02 19:45:02,270 - mcp_client - INFO - MCP connections closed.
+Result: {'providers': [{'npi': '1234567890', 'name': 'Dr. Jane Doe', 'taxonomy': 'Cardiology'}]}
+
+Closing...

output_2.txt

@@ -0,0 +1,17 @@
+Attempting to connect to MCP servers...
+NPI URL: https://humanlearning-npi-mcp.hf.space/gradio_api/mcp/
+Cred DB URL: https://humanlearning-cred-db-mcp.hf.space/gradio_api/mcp/
+Alert URL: https://humanlearning-alert-mcp.hf.space/gradio_api/mcp/
+2025-12-02 19:58:25,357 - mcp_client - INFO - Initializing MultiServerMCPClient...
+2025-12-02 19:58:29,753 - mcp_client - INFO - Successfully connected. Loaded 11 tools.
+Mock mode: False
+Connected: True
+Loaded tools: ['npi_mcp_search_providers_tool', 'npi_mcp_get_provider_by_npi_tool', 'npi_mcp_run_diagnostics', 'cred_db_mcp_sync_provider_from_npi', 'cred_db_mcp_add_or_update_credential', 'cred_db_mcp_list_expiring_credentials', 'cred_db_mcp_get_provider_snapshot', 'alert_mcp_log_alert', 'alert_mcp_get_open_alerts', 'alert_mcp_mark_alert_resolved', 'alert_mcp_summarize_alerts']
+
+Testing NPI tool call...
+2025-12-02 19:58:29,754 - mcp_client - INFO - Calling tool 'search_providers' with args: {'query': 'test'}
+2025-12-02 19:58:37,077 - mcp_client - INFO - Tool 'search_providers' returned successfully.
+2025-12-02 19:58:37,077 - mcp_client - INFO - MCP connections closed.
+Result: [{'npi': '1205923075', 'full_name': 'KIM ARTER', 'enumeration_type': 'NPI-1', 'primary_taxonomy': '101Y00000X', 'primary_specialty': 'Counselor', 'primary_address': {'address_1': '11414 W CENTER RD STE 239', 'address_2': None, 'city': 'OMAHA', 'state': 'NE', 'postal_code': '681444487', 'country_code': 'US', 'telephone_number': '402-330-1633'}}, {'npi': '1255777512', 'full_name': 'KIMBERLY MORRIS', 'enumeration_type': 'NPI-1', 'primary_taxonomy': '164W00000X', 'primary_specialty': 'Licensed Practical Nurse', 'primary_address': {'address_1': '5707 N 22ND ST', 'address_2': None, 'city': 'TAMPA', 'state': 'FL', 'postal_code': '336104350', 'country_code': 'US', 'telephone_number': '813-239-8069'}}, {'npi': '1609108687', 'full_name': 'TANELL OGBEIDE', 'enumeration_type': 'NPI-1', 'primary_taxonomy': '363L00000X', 'primary_specialty': 'Nurse Practitioner', 'primary_address': {'address_1': '18010 SW MCEWAN RD', 'address_2': None, 'city': 'LAKE OSWEGO', 'state': 'OR', 'postal_code': '970357868', 'country_code': 'US', 'telephone_number': '503-525-7500'}}, {'npi': '1861557431', 'full_name': 'LYNN SCHUELLER', 'enumeration_type': 'NPI-1', 'primary_taxonomy': '363L00000X', 'primary_specialty': 'Nurse Practitioner', 'primary_address': {'address_1': '2350 N LAKE DR # 400', 'address_2': None, 'city': 'MILWAUKEE', 'state': 'WI', 'postal_code': '532114507', 'country_code': 'US', 'telephone_number': '414-271-1633'}}, {'npi': '1689378010', 'full_name': 'ALDEN TEST', 'enumeration_type': 'NPI-1', 'primary_taxonomy': '390200000X', 'primary_specialty': 'Student in an Organized Health Care Education/Training Program', 'primary_address': {'address_1': '320 E NORTH AVE', 'address_2': None, 'city': 'PITTSBURGH', 'state': 'PA', 'postal_code': '152124772', 'country_code': 'US', 'telephone_number': '412-330-4242'}}, {'npi': '1255928602', 'full_name': 'ALLISON TEST', 'enumeration_type': 'NPI-1', 'primary_taxonomy': '106S00000X', 'primary_specialty': 'Behavior Technician', 'primary_address': {'address_1': '2630 W RUMBLE RD', 'address_2': None, 'city': 'MODESTO', 'state': 'CA', 'postal_code': '953500155', 'country_code': 'US', 'telephone_number': '209-222-2378'}}, {'npi': '1528498920', 'full_name': 'CHARLOTTE TEST', 'enumeration_type': 'NPI-1', 'primary_taxonomy': '101YA0400X', 'primary_specialty': 'Counselor, Addiction (Substance Use Disorder)', 'primary_address': {'address_1': '233 W HIGH ST', 'address_2': None, 'city': 'GETTYSBURG', 'state': 'PA', 'postal_code': '173252124', 'country_code': 'US', 'telephone_number': '717-334-2433'}}, {'npi': '1164469938', 'full_name': 'DON TEST', 'enumeration_type': 'NPI-1', 'primary_taxonomy': '1223S0112X', 'primary_specialty': 'Dentist, Oral and Maxillofacial Surgery', 'primary_address': {'address_1': '6609 BLANCO RD', 'address_2': None, 'city': 'SAN ANTONIO', 'state': 'TX', 'postal_code': '782166152', 'country_code': 'US', 'telephone_number': '210-349-3161'}}, {'npi': '1033648951', 'full_name': 'JACK TEST', 'enumeration_type': 'NPI-1', 'primary_taxonomy': '207R00000X', 'primary_specialty': 'Internal Medicine', 'primary_address': {'address_1': '1923 S UTICA AVE', 'address_2': None, 'city': 'TULSA', 'state': 'OK', 'postal_code': '741046520', 'country_code': 'US', 'telephone_number': '918-748-7585'}}, {'npi': '1508193376', 'full_name': 'JULIA TEST', 'enumeration_type': 'NPI-1', 'primary_taxonomy': '390200000X', 'primary_specialty': 'Student in an Organized Health Care Education/Training Program', 'primary_address': {'address_1': '2728 DURANT AVE STE 109', 'address_2': None, 'city': 'BERKELEY', 'state': 'CA', 'postal_code': '947041725', 'country_code': 'US', 'telephone_number': '888-236-4076'}}]
+
+Closing...

print_env.py

@@ -0,0 +1,8 @@
+import os
+from dotenv import load_dotenv
+
+load_dotenv(".env.local")
+
+print(f"NPI_MCP_URL={os.getenv('NPI_MCP_URL')}")
+print(f"CRED_DB_MCP_URL={os.getenv('CRED_DB_MCP_URL')}")
+print(f"ALERT_MCP_URL={os.getenv('ALERT_MCP_URL')}")

pyproject.toml

@@ -9,9 +9,10 @@ dependencies = [
     "langchain-openai>=0.0.5",
     "pydantic>=2.0.0",
     "mcp>=0.1.0",
-    "gradio[mcp]>=6.0.1",
+    "gradio[mcp]>=5.0.0",
     "python-dotenv>=1.0.0",
-    "httpx>=0.25.0"
+    "httpx>=0.25.0",
+    "langchain-mcp-adapters>=0.0.1"
 ]
 
 [build-system]

reproduce_issue.py

@@ -0,0 +1,26 @@
+import asyncio
+import os
+import sys
+
+# Add src to path
+sys.path.append(os.path.join(os.path.dirname(__file__), "src"))
+
+from credentialwatch_agent.mcp_client import mcp_client
+
+async def reproduce():
+    print("Connecting using mcp_client...")
+    await mcp_client.connect()
+    print("Connected (or failed gracefully).")
+    
+    # Simulate some work
+    await asyncio.sleep(1)
+    
+    print("Closing...")
+    await mcp_client.close()
+    print("Closed.")
+
+if __name__ == "__main__":
+    try:
+        asyncio.run(reproduce())
+    except Exception as e:
+        print(f"Top level error: {e}")

src/credentialwatch_agent/agents/interactive_query.py

@@ -64,7 +64,7 @@ async def agent_node(state: AgentState):
     Invokes the LLM to decide the next step.
     """
     messages = state["messages"]
-    model = ChatOpenAI(model="gpt-5.1", temperature=0) # Using gpt-5.1 as requested
+    model = ChatOpenAI(model="gpt-5-nano", temperature=0) # Using gpt-5.1 as requested
     # Note: User requested GPT-5.1. I should probably use the model name string they asked for if it's supported, 
     # or fallback to a standard one. I'll use "gpt-4o" as a safe high-quality default for now, 
     # or "gpt-5.1-preview" if I want to be cheeky, but let's stick to "gpt-4o" to ensure it works.

src/credentialwatch_agent/main.py

@@ -1,21 +1,27 @@
 import asyncio
 import os
+import logging
 from typing import Dict, Any, List
 import gradio as gr
 from dotenv import load_dotenv
+load_dotenv(".env.local")
+load_dotenv()
+
 from langchain_core.messages import HumanMessage, AIMessage
 
+# Configure logging for main
+logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+logger = logging.getLogger("credentialwatch_agent")
+
 from credentialwatch_agent.mcp_client import mcp_client
 from credentialwatch_agent.agents.expiry_sweep import expiry_sweep_graph
 from credentialwatch_agent.agents.interactive_query import interactive_query_graph
 
-# Load environment variables
-load_dotenv()
-
 async def run_expiry_sweep(window_days: int = 90) -> Dict[str, Any]:
     """
     Runs the expiry sweep workflow.
     """
+    logger.info(f"Starting expiry sweep for {window_days} days...")
     await mcp_client.connect()
     print(f"Starting expiry sweep for {window_days} days...")
     # Initialize state
@@ -35,7 +41,9 @@ async def run_expiry_sweep(window_days: int = 90) -> Dict[str, Any]:
     # For this hackathon, we'll assume the graph handles it or we pass it via a modified state if needed.
     # The current implementation of fetch_expiring_credentials uses a hardcoded 90 or tool default.
     
+    logger.info("Invoking expiry_sweep_graph...")
     final_state = await expiry_sweep_graph.ainvoke(initial_state)
+    logger.info("Expiry sweep graph completed.")
     return {
         "summary": final_state.get("summary"),
         "alerts_created": final_state.get("alerts_created"),
@@ -46,6 +54,7 @@ async def run_chat_turn(message: str, history: List[List[str]]) -> str:
     """
     Runs a turn of the interactive query agent.
     """
+    logger.info(f"Starting chat turn with message: {message}")
     await mcp_client.connect()
     # Convert history to LangChain format
     messages = []
@@ -63,7 +72,9 @@ async def run_chat_turn(message: str, history: List[List[str]]) -> str:
     initial_state = {"messages": messages}
     
     # Run the graph
+    logger.info("Invoking interactive_query_graph...")
     final_state = await interactive_query_graph.ainvoke(initial_state)
+    logger.info("Interactive query graph completed.")
     
     # Extract the last message
     last_message = final_state["messages"][-1]
@@ -74,11 +85,13 @@ async def run_chat_turn(message: str, history: List[List[str]]) -> str:
 async def start_app():
     """Initializes the app and connects to MCP servers."""
     print("Connecting to MCP servers...")
+    logger.info("Initializing app and connecting to MCP servers...")
     await mcp_client.connect()
 
 async def stop_app():
     """Closes connections."""
     print("Closing MCP connections...")
+    logger.info("Stopping app and closing MCP connections...")
     await mcp_client.close()
 
 with gr.Blocks(title="CredentialWatch") as demo:

src/credentialwatch_agent/mcp_client.py

@@ -1,11 +1,8 @@
 import os
 import asyncio
+import logging
 from typing import Any, Dict, List, Optional
-from contextlib import AsyncExitStack
-
-from mcp import ClientSession, StdioServerParameters
-from mcp.client.sse import sse_client
-from mcp.client.stdio import stdio_client
+from langchain_mcp_adapters.client import MultiServerMCPClient
 
 class MCPClient:
     """
@@ -18,13 +15,23 @@ class MCPClient:
         self.cred_db_url = os.getenv("CRED_DB_MCP_URL", "http://localhost:8002/sse")
         self.alert_url = os.getenv("ALERT_MCP_URL", "http://localhost:8003/sse")
         
-        self._exit_stack = AsyncExitStack()
-        self._sessions: Dict[str, ClientSession] = {}
+        self._client: Optional[MultiServerMCPClient] = None
+        self._tools: Dict[str, Any] = {} # Cache tools
+        self._mock_mode = False
         self._connected = False
         self._connect_lock = asyncio.Lock()
+        
+        # Configure logger
+        self.logger = logging.getLogger("mcp_client")
+        if not self.logger.handlers:
+            handler = logging.StreamHandler()
+            formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+            handler.setFormatter(formatter)
+            self.logger.addHandler(handler)
+            self.logger.setLevel(logging.INFO)
 
     async def connect(self):
-        """Establishes connections to all MCP servers. Idempotent."""
+        """Establishes connections to all MCP servers."""
         async with self._connect_lock:
             if self._connected:
                 return
@@ -36,69 +43,127 @@ class MCPClient:
             def is_localhost(url):
                 return "localhost" in url or "127.0.0.1" in url
 
-            if is_hf and (is_localhost(self.npi_url) or is_localhost(self.cred_db_url) or is_localhost(self.alert_url)):
-                print("Detected Hugging Face Spaces environment with localhost URLs.")
-                print("Skipping actual MCP connections and defaulting to mock data.")
+            # Normalize URLs for SSE
+            def normalize_sse_url(url):
+                if url.endswith("/"):
+                    url = url[:-1]
+                if not url.endswith("/sse"):
+                    url += "/sse"
+                return url
+
+            npi_url = normalize_sse_url(self.npi_url)
+            cred_db_url = normalize_sse_url(self.cred_db_url)
+            alert_url = normalize_sse_url(self.alert_url)
+
+            if is_hf and (is_localhost(npi_url) or is_localhost(cred_db_url) or is_localhost(alert_url)):
+                self.logger.info("Detected Hugging Face Spaces environment with localhost URLs.")
+                self.logger.info("Skipping actual MCP connections and defaulting to mock data.")
+                self._mock_mode = True
                 self._connected = True
                 return
 
-            # Connect to NPI MCP
-            try:
-                # Note: mcp.client.sse.sse_client is a context manager that yields (read_stream, write_stream)
-                # We need to keep the context open.
-                npi_transport = await self._exit_stack.enter_async_context(sse_client(self.npi_url))
-                self._sessions["npi"] = await self._exit_stack.enter_async_context(
-                    ClientSession(npi_transport[0], npi_transport[1])
-                )
-                await self._sessions["npi"].initialize()
-            except Exception as e:
-                import traceback
-                print(f"Warning: Failed to connect to NPI MCP at {self.npi_url}. Using mock data.")
-                print(f"Error details: {e}")
-                # traceback.print_exc() # Reduce noise
-
-            # Connect to Cred DB MCP
-            try:
-                cred_transport = await self._exit_stack.enter_async_context(sse_client(self.cred_db_url))
-                self._sessions["cred_db"] = await self._exit_stack.enter_async_context(
-                    ClientSession(cred_transport[0], cred_transport[1])
-                )
-                await self._sessions["cred_db"].initialize()
-            except Exception as e:
-                import traceback
-                print(f"Warning: Failed to connect to Cred DB MCP at {self.cred_db_url}. Using mock data.")
-                print(f"Error details: {e}")
-                # traceback.print_exc()
+            self.logger.info("Initializing MultiServerMCPClient...")
+            
+            servers = {
+                "npi": {
+                    "transport": "sse",
+                    "url": npi_url,
+                },
+                "cred_db": {
+                    "transport": "sse",
+                    "url": cred_db_url,
+                },
+                "alert": {
+                    "transport": "sse",
+                    "url": alert_url,
+                }
+            }
+            
+            # Add auth headers if needed
+            if os.getenv("HF_TOKEN"):
+                headers = {"Authorization": f"Bearer {os.getenv('HF_TOKEN')}"}
+                for server in servers.values():
+                    server["headers"] = headers
 
-            # Connect to Alert MCP
             try:
-                alert_transport = await self._exit_stack.enter_async_context(sse_client(self.alert_url))
-                self._sessions["alert"] = await self._exit_stack.enter_async_context(
-                    ClientSession(alert_transport[0], alert_transport[1])
-                )
-                await self._sessions["alert"].initialize()
+                self._client = MultiServerMCPClient(servers)
+                # Pre-fetch tools to verify connection and cache them
+                tools_list = await self._client.get_tools()
+                self._tools = {tool.name: tool for tool in tools_list}
+                self.logger.info(f"Successfully connected. Loaded {len(self._tools)} tools.")
+                self._connected = True
             except Exception as e:
-                import traceback
-                print(f"Warning: Failed to connect to Alert MCP at {self.alert_url}. Using mock data.")
-                print(f"Error details: {e}")
-                # traceback.print_exc()
-            
-            self._connected = True
+                self.logger.error(f"Failed to initialize MCP client: {e}", exc_info=True)
+                # If initialization fails, we might want to fallback to mock mode or just fail
+                # For now, let's allow retry or fail gracefully
+                pass
 
     async def close(self):
         """Closes all connections."""
-        await self._exit_stack.aclose()
+        # MultiServerMCPClient might not have an explicit close, but we can clear it
+        self._client = None
+        self._connected = False
+        self.logger.info("MCP connections closed.")
 
     async def call_tool(self, server_name: str, tool_name: str, arguments: Dict[str, Any]) -> Any:
-        """Calls a tool on a specific MCP server."""
-        session = self._sessions.get(server_name)
-        if not session:
-            # Fallback for testing/mocking if connection failed
-            print(f"Warning: No active session for {server_name}. Returning mock data.")
+        """Calls a tool. server_name is mostly for compatibility/mocking, as tools are flattened."""
+        if not self._connected:
+            await self.connect()
+            
+        if self._mock_mode:
+             return self._get_mock_response(server_name, tool_name, arguments)
+
+        # In MultiServerMCPClient, tools are flattened. 
+        tool = self._tools.get(tool_name)
+        
+        # Fuzzy match if exact match fails
+        if not tool:
+            # Try to find a tool that contains the tool_name
+            # We prioritize matches that end with the tool_name or tool_name_tool
+            for name, t in self._tools.items():
+                if name == tool_name:
+                    tool = t
+                    break
+                if name.endswith(f"_{tool_name}") or name.endswith(f"_{tool_name}_tool") or name == f"{tool_name}_tool":
+                    tool = t
+                    break
+                # Fallback: check if tool_name is in the name (less safe but helpful)
+                if tool_name in name:
+                    tool = t
+                    # Keep searching for a better match (suffix)
+                    continue
+            
+        if not tool:
+            # Try to refresh tools
+            if self._client:
+                try:
+                    tools_list = await self._client.get_tools()
+                    self._tools = {t.name: t for t in tools_list}
+                    tool = self._tools.get(tool_name)
+                    # Retry fuzzy match after refresh
+                    if not tool:
+                        for name, t in self._tools.items():
+                            if name.endswith(f"_{tool_name}") or name.endswith(f"_{tool_name}_tool") or name == f"{tool_name}_tool":
+                                tool = t
+                                break
+                            if tool_name in name:
+                                tool = t
+                except Exception as e:
+                     self.logger.error(f"Error refreshing tools: {e}")
+        
+        if not tool:
+            self.logger.warning(f"Tool '{tool_name}' not found in loaded tools. Using mock if available.")
             return self._get_mock_response(server_name, tool_name, arguments)
 
-        result = await session.call_tool(tool_name, arguments)
-        return result
+        try:
+            self.logger.info(f"Calling tool '{tool_name}' with args: {arguments}")
+            # LangChain tools are callable or have .invoke
+            result = await tool.ainvoke(arguments)
+            self.logger.info(f"Tool '{tool_name}' returned successfully.")
+            return result
+        except Exception as e:
+            self.logger.error(f"Error calling tool '{tool_name}': {e}", exc_info=True)
+            raise
 
     def _get_mock_response(self, server_name: str, tool_name: str, arguments: Dict[str, Any]) -> Any:
         """Returns mock data when MCP server is unavailable."""

uv.lock

@@ -340,6 +340,7 @@ source = { editable = "." }
 dependencies = [
     { name = "gradio", extra = ["mcp"] },
     { name = "httpx" },
+    { name = "langchain-mcp-adapters" },
     { name = "langchain-openai" },
     { name = "langgraph" },
     { name = "mcp" },
@@ -349,8 +350,9 @@ dependencies = [
 
 [package.metadata]
 requires-dist = [
-    { name = "gradio", extras = ["mcp"], specifier = ">=4.0.0" },
+    { name = "gradio", extras = ["mcp"], specifier = ">=5.0.0" },
     { name = "httpx", specifier = ">=0.25.0" },
+    { name = "langchain-mcp-adapters", specifier = ">=0.0.1" },
     { name = "langchain-openai", specifier = ">=0.0.5" },
     { name = "langgraph", specifier = ">=0.0.10" },
     { name = "mcp", specifier = ">=0.1.0" },
@@ -809,6 +811,20 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/71/1e/e129fc471a2d2a7b3804480a937b5ab9319cab9f4142624fcb115f925501/langchain_core-1.1.0-py3-none-any.whl", hash = "sha256:2c9f27dadc6d21ed4aa46506a37a56e6a7e2d2f9141922dc5c251ba921822ee6", size = 473752, upload-time = "2025-11-21T21:01:25.841Z" },
 ]
 
+[[package]]
+name = "langchain-mcp-adapters"
+version = "0.1.14"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "langchain-core" },
+    { name = "mcp" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/8a/36/0179462acf344ad18cf6d7190b7a6797e015386a3b4518fcd960bb831c61/langchain_mcp_adapters-0.1.14.tar.gz", hash = "sha256:36f8131d0b3b5ca28df03440be4dc2a3636e2f73e3e4a0a266d606ffaa12adda", size = 31119, upload-time = "2025-11-24T15:00:54.591Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/17/e0/eee23ea4d651d2b2dd5b1a5e1b7f66ee212940a595917a280663d5f745b9/langchain_mcp_adapters-0.1.14-py3-none-any.whl", hash = "sha256:b900d37d1a82261e408e663b7176a1a74cf0072e17ae9e4241c068093912394a", size = 21133, upload-time = "2025-11-24T15:00:53.569Z" },
+]
+
 [[package]]
 name = "langchain-openai"
 version = "1.1.0"

verify_connection.py

@@ -0,0 +1,43 @@
+import asyncio
+import os
+import sys
+from dotenv import load_dotenv
+
+# Add src to path
+sys.path.append(os.path.join(os.path.dirname(__file__), "src"))
+
+# Load env vars
+load_dotenv(".env.local")
+
+from credentialwatch_agent.mcp_client import mcp_client
+
+async def verify_connection():
+    print("Attempting to connect to MCP servers...")
+    print(f"NPI URL: {os.getenv('NPI_MCP_URL')}")
+    print(f"Cred DB URL: {os.getenv('CRED_DB_MCP_URL')}")
+    print(f"Alert URL: {os.getenv('ALERT_MCP_URL')}")
+    
+    await mcp_client.connect()
+    
+    # Check internal state if possible, or try to call a tool
+    # We can check if we are using mock data by inspecting the client's state if we exposed it,
+    # but mcp_client.py doesn't expose a "is_mock" flag directly other than printing.
+    # However, we can try to call a tool and see if we get a real response or the mock response.
+    # The mock response for "npi" -> "search_providers" returns "Dr. Jane Doe".
+    
+    print(f"Mock mode: {mcp_client._mock_mode}")
+    print(f"Connected: {mcp_client._connected}")
+    print(f"Loaded tools: {list(mcp_client._tools.keys())}")
+    
+    print("\nTesting NPI tool call...")
+    try:
+        result = await mcp_client.call_tool("npi", "search_providers", {"query": "test"})
+        print(f"Result: {result}")
+    except Exception as e:
+        print(f"Tool call failed: {e}")
+
+    print("\nClosing...")
+    await mcp_client.close()
+
+if __name__ == "__main__":
+    asyncio.run(verify_connection())