feat: add MCP (Model Context Protocol) support

Add comprehensive MCP integration using langchain-mcp-adapters to enable
pluggable external tools from MCP servers.

Features:
- MCP server configuration via mcp_config.json
- Automatic lazy initialization for seamless use in both FastAPI and LangGraph Studio
- Support for multiple MCP servers (filesystem, postgres, github, brave-search, etc.)
- Environment variable resolution in configuration
- Tool caching mechanism for optimal performance
- Complete documentation and setup guide

Implementation:
- Add src/mcp module with client, tools, and cache components
- Integrate MCP config loading in AppConfig
- Update tool system to include MCP tools automatically
- Add eager initialization in FastAPI lifespan handler
- Add lazy initialization fallback for LangGraph Studio

Dependencies:
- Add langchain-mcp-adapters>=0.1.0

Documentation:
- Add MCP_SETUP.md with comprehensive setup guide
- Update CLAUDE.md with MCP system architecture
- Update config.example.yaml with MCP configuration notes
- Update README.md with MCP setup instructions

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

backend/src/mcp/__init__.py

@@ -0,0 +1,14 @@
+"""MCP (Model Context Protocol) integration using langchain-mcp-adapters."""
+
+from .cache import get_cached_mcp_tools, initialize_mcp_tools, reset_mcp_tools_cache
+from .client import build_server_params, build_servers_config
+from .tools import get_mcp_tools
+
+__all__ = [
+    "build_server_params",
+    "build_servers_config",
+    "get_mcp_tools",
+    "initialize_mcp_tools",
+    "get_cached_mcp_tools",
+    "reset_mcp_tools_cache",
+]

backend/src/mcp/cache.py

@@ -0,0 +1,85 @@
+"""Cache for MCP tools to avoid repeated loading."""
+
+import asyncio
+import logging
+
+from langchain_core.tools import BaseTool
+
+logger = logging.getLogger(__name__)
+
+_mcp_tools_cache: list[BaseTool] | None = None
+_cache_initialized = False
+_initialization_lock = asyncio.Lock()
+
+
+async def initialize_mcp_tools() -> list[BaseTool]:
+    """Initialize and cache MCP tools.
+
+    This should be called once at application startup.
+
+    Returns:
+        List of LangChain tools from all enabled MCP servers.
+    """
+    global _mcp_tools_cache, _cache_initialized
+
+    async with _initialization_lock:
+        if _cache_initialized:
+            logger.info("MCP tools already initialized")
+            return _mcp_tools_cache or []
+
+        from src.mcp.tools import get_mcp_tools
+
+        logger.info("Initializing MCP tools...")
+        _mcp_tools_cache = await get_mcp_tools()
+        _cache_initialized = True
+        logger.info(f"MCP tools initialized: {len(_mcp_tools_cache)} tool(s) loaded")
+
+        return _mcp_tools_cache
+
+
+def get_cached_mcp_tools() -> list[BaseTool]:
+    """Get cached MCP tools with lazy initialization.
+
+    If tools are not initialized, automatically initializes them.
+    This ensures MCP tools work in both FastAPI and LangGraph Studio contexts.
+
+    Returns:
+        List of cached MCP tools.
+    """
+    global _cache_initialized
+
+    if not _cache_initialized:
+        logger.info("MCP tools not initialized, performing lazy initialization...")
+        try:
+            # Try to initialize in the current event loop
+            loop = asyncio.get_event_loop()
+            if loop.is_running():
+                # If loop is already running (e.g., in LangGraph Studio),
+                # we need to create a new loop in a thread
+                import concurrent.futures
+
+                with concurrent.futures.ThreadPoolExecutor() as executor:
+                    future = executor.submit(asyncio.run, initialize_mcp_tools())
+                    future.result()
+            else:
+                # If no loop is running, we can use the current loop
+                loop.run_until_complete(initialize_mcp_tools())
+        except RuntimeError:
+            # No event loop exists, create one
+            asyncio.run(initialize_mcp_tools())
+        except Exception as e:
+            logger.error(f"Failed to lazy-initialize MCP tools: {e}")
+            return []
+
+    return _mcp_tools_cache or []
+
+
+def reset_mcp_tools_cache() -> None:
+    """Reset the MCP tools cache.
+
+    This is useful for testing or when you want to reload MCP tools.
+    """
+    global _mcp_tools_cache, _cache_initialized
+    _mcp_tools_cache = None
+    _cache_initialized = False
+    logger.info("MCP tools cache reset")

backend/src/mcp/client.py

@@ -0,0 +1,57 @@
+"""MCP client using langchain-mcp-adapters."""
+
+import logging
+from typing import Any
+
+from src.config.mcp_config import McpConfig, McpServerConfig
+
+logger = logging.getLogger(__name__)
+
+
+def build_server_params(server_name: str, config: McpServerConfig) -> dict[str, Any]:
+    """Build server parameters for MultiServerMCPClient.
+
+    Args:
+        server_name: Name of the MCP server.
+        config: Configuration for the MCP server.
+
+    Returns:
+        Dictionary of server parameters for langchain-mcp-adapters.
+    """
+    params: dict[str, Any] = {
+        "command": config.command,
+        "args": config.args,
+        "transport": "stdio",  # Default to stdio transport
+    }
+
+    # Add environment variables if present
+    if config.env:
+        params["env"] = config.env
+
+    return params
+
+
+def build_servers_config(mcp_config: McpConfig) -> dict[str, dict[str, Any]]:
+    """Build servers configuration for MultiServerMCPClient.
+
+    Args:
+        mcp_config: MCP configuration containing all servers.
+
+    Returns:
+        Dictionary mapping server names to their parameters.
+    """
+    enabled_servers = mcp_config.get_enabled_servers()
+
+    if not enabled_servers:
+        logger.info("No enabled MCP servers found")
+        return {}
+
+    servers_config = {}
+    for server_name, server_config in enabled_servers.items():
+        try:
+            servers_config[server_name] = build_server_params(server_name, server_config)
+            logger.info(f"Configured MCP server: {server_name}")
+        except Exception as e:
+            logger.error(f"Failed to configure MCP server '{server_name}': {e}")
+
+    return servers_config

backend/src/mcp/tools.py

@@ -0,0 +1,45 @@
+"""Load MCP tools using langchain-mcp-adapters."""
+
+import logging
+
+from langchain_core.tools import BaseTool
+
+from src.config.mcp_config import get_mcp_config
+from src.mcp.client import build_servers_config
+
+logger = logging.getLogger(__name__)
+
+
+async def get_mcp_tools() -> list[BaseTool]:
+    """Get all tools from enabled MCP servers.
+
+    Returns:
+        List of LangChain tools from all enabled MCP servers.
+    """
+    try:
+        from langchain_mcp_adapters.client import MultiServerMCPClient
+    except ImportError:
+        logger.warning("langchain-mcp-adapters not installed. Install it to enable MCP tools: pip install langchain-mcp-adapters")
+        return []
+
+    mcp_config = get_mcp_config()
+    servers_config = build_servers_config(mcp_config)
+
+    if not servers_config:
+        logger.info("No enabled MCP servers configured")
+        return []
+
+    try:
+        # Create the multi-server MCP client
+        logger.info(f"Initializing MCP client with {len(servers_config)} server(s)")
+        client = MultiServerMCPClient(servers_config)
+
+        # Get all tools from all servers
+        tools = await client.get_tools()
+        logger.info(f"Successfully loaded {len(tools)} tool(s) from MCP servers")
+
+        return tools
+
+    except Exception as e:
+        logger.error(f"Failed to load MCP tools: {e}", exc_info=True)
+        return []