Authorization Successful!
76 |OAuth flow completed successfully.
77 |You can close this window and return to the terminal.
78 | 79 | 80 | 81 | """) 82 | elif "error" in query_params: 83 | self.callback_data["error"] = query_params["error"][0] 84 | self.send_response(400) 85 | self.send_header("Content-type", "text/html") 86 | self.end_headers() 87 | self.wfile.write( 88 | f""" 89 | 90 | 91 |Authorization Failed
92 |Error: {query_params['error'][0]}
93 |You can close this window and return to the terminal.
94 | 95 | 96 | """.encode() 97 | ) 98 | else: 99 | self.send_response(404) 100 | self.end_headers() 101 | 102 | def log_message(self, format, *args): 103 | """Suppress default logging.""" 104 | pass 105 | 106 | class CallbackServer: 107 | """Simple server to handle OAuth callbacks.""" 108 | 109 | def __init__(self, port=3000): 110 | self.port = port 111 | self.server = None 112 | self.thread = None 113 | self.callback_data = {"authorization_code": None, "state": None, "error": None} 114 | 115 | def _create_handler_with_data(self): 116 | """Create a handler class with access to callback data.""" 117 | callback_data = self.callback_data 118 | 119 | class DataCallbackHandler(CallbackHandler): 120 | def __init__(self, request, client_address, server): 121 | super().__init__(request, client_address, server, callback_data) 122 | 123 | return DataCallbackHandler 124 | 125 | def start(self): 126 | """Start the callback server in a background thread.""" 127 | handler_class = self._create_handler_with_data() 128 | self.server = HTTPServer(("localhost", self.port), handler_class) 129 | self.thread = threading.Thread(target=self.server.serve_forever, daemon=True) 130 | self.thread.start() 131 | print(f"🖥️ Started OAuth callback server on http://localhost:{self.port}") 132 | 133 | def stop(self): 134 | """Stop the callback server.""" 135 | if self.server: 136 | self.server.shutdown() 137 | self.server.server_close() 138 | if self.thread: 139 | self.thread.join(timeout=1) 140 | 141 | def wait_for_callback(self, timeout=300): 142 | """Wait for OAuth callback with timeout.""" 143 | start_time = time.time() 144 | while time.time() - start_time < timeout: 145 | if self.callback_data["authorization_code"]: 146 | return self.callback_data["authorization_code"] 147 | elif self.callback_data["error"]: 148 | raise Exception(f"OAuth error: {self.callback_data['error']}") 149 | time.sleep(0.1) 150 | raise Exception("Timeout waiting for OAuth callback") 151 | 152 | def get_state(self): 153 | """Get the received state parameter.""" 154 | return self.callback_data["state"] 155 | 156 | async def test_oauth_authentication(): 157 | """Test OAuth 2.1-compliant authentication with your library.""" 158 | print("🔐 Testing OAuth 2.1-Compliant Authentication with langchain-mcp-tools") 159 | print("=" * 70) 160 | 161 | # Set up callback server 162 | callback_server = CallbackServer(port=3000) 163 | callback_server.start() 164 | 165 | try: 166 | async def callback_handler() -> tuple[str, str | None]: 167 | """Wait for OAuth callback and return auth code and state.""" 168 | print("⏳ Waiting for OAuth authorization callback...") 169 | try: 170 | auth_code = callback_server.wait_for_callback(timeout=300) 171 | return auth_code, callback_server.get_state() 172 | finally: 173 | pass # Don't stop server here, let finally block handle it 174 | 175 | async def redirect_handler(authorization_url: str) -> None: 176 | """Redirect handler that opens the URL in a browser.""" 177 | print(f"🌐 Opening browser for OAuth authorization...") 178 | print(f" URL: {authorization_url}") 179 | webbrowser.open(authorization_url) 180 | 181 | # Create OAuth client metadata 182 | client_metadata = OAuthClientMetadata( 183 | client_name="Test MCP Client", 184 | redirect_uris=["http://localhost:3000/callback"], 185 | grant_types=["authorization_code", "refresh_token"], 186 | response_types=["code"], 187 | token_endpoint_auth_method="client_secret_post", 188 | ) 189 | 190 | # Create OAuth authentication provider 191 | oauth_auth = OAuthClientProvider( 192 | server_url="http://localhost:8003", 193 | client_metadata=client_metadata, 194 | storage=InMemoryTokenStorage(), 195 | redirect_handler=redirect_handler, 196 | callback_handler=callback_handler, 197 | ) 198 | 199 | # Test configuration with OAuth auth 200 | oauth_config = { 201 | "oauth-server": { 202 | "url": "http://127.0.0.1:8003/mcp", 203 | "auth": oauth_auth, # This should be supported by your library 204 | "timeout": 30.0 205 | } 206 | } 207 | 208 | print("\n🚀 Starting OAuth flow...") 209 | print("💡 A browser window will open for authorization") 210 | print("💡 Complete the OAuth flow in the browser") 211 | 212 | tools, cleanup = await convert_mcp_to_langchain_tools(oauth_config) 213 | 214 | print(f"\n✅ OAuth authentication successful!") 215 | print(f"🛠️ Connected with {len(tools)} tools available") 216 | 217 | # List available tools 218 | print("\n🔧 Available Tools:") 219 | for tool in tools: 220 | print(f" • {tool.name}: {tool.description}") 221 | 222 | # Test a tool 223 | if tools: 224 | print("\n🧪 Testing tool execution...") 225 | user_tool = next((t for t in tools if 'current_user' in t.name), None) 226 | if user_tool: 227 | result = await user_tool.ainvoke({}) 228 | print(f"🔧 Tool result: {result}") 229 | 230 | # Test another tool with parameters 231 | create_tool = next((t for t in tools if 'create_document' in t.name), None) 232 | if create_tool: 233 | result = await create_tool.ainvoke({ 234 | "title": "OAuth Test Document", 235 | "content": "This document was created via OAuth-authenticated MCP tool call!" 236 | }) 237 | print(f"🔧 Create tool result: {result}") 238 | 239 | await cleanup() 240 | print("\n✅ OAuth test completed successfully!") 241 | 242 | except Exception as e: 243 | print(f"\n❌ OAuth test failed: {e}") 244 | import traceback 245 | traceback.print_exc() 246 | finally: 247 | callback_server.stop() 248 | 249 | async def test_oauth_error_scenarios(): 250 | """Test OAuth error scenarios.""" 251 | print("\n⚠️ Testing OAuth Error Scenarios") 252 | print("=" * 50) 253 | 254 | # Test 1: Invalid server URL 255 | print("\n🧪 Test 1: Invalid OAuth server URL") 256 | try: 257 | oauth_auth = OAuthClientProvider( 258 | server_url="http://localhost:9999", # Non-existent server 259 | client_metadata=OAuthClientMetadata( 260 | client_name="Test Client", 261 | redirect_uris=["http://localhost:3000/callback"], 262 | grant_types=["authorization_code"], 263 | response_types=["code"], 264 | ), 265 | storage=InMemoryTokenStorage(), 266 | redirect_handler=lambda url: None, 267 | callback_handler=lambda: ("invalid", None), 268 | ) 269 | 270 | config = { 271 | "invalid-oauth": { 272 | "url": "http://127.0.0.1:9999/mcp", 273 | "auth": oauth_auth, 274 | "timeout": 5.0 275 | } 276 | } 277 | 278 | tools, cleanup = await convert_mcp_to_langchain_tools(config) 279 | print(f"❌ Unexpected success: {len(tools)} tools (should have failed)") 280 | await cleanup() 281 | 282 | except Exception as e: 283 | print(f"✅ Expected failure: {str(e)[:100]}...") 284 | 285 | async def test_mixed_auth_with_oauth(): 286 | """Test mixed authentication including OAuth.""" 287 | print("\n🔀 Testing Mixed Authentication (OAuth + Headers)") 288 | print("=" * 60) 289 | 290 | # This test would require multiple servers running 291 | # For now, just test the configuration structure 292 | print("💡 This test demonstrates configuration structure for mixed auth:") 293 | 294 | example_config = { 295 | # OAuth server (would need OAuth flow) 296 | "oauth-server": { 297 | "url": "http://127.0.0.1:8003/mcp", 298 | # "auth": oauth_auth, # Commented out to avoid triggering OAuth flow 299 | "timeout": 30.0 300 | }, 301 | # Bearer token server 302 | "bearer-server": { 303 | "url": "http://127.0.0.1:8001/mcp", 304 | "headers": {"Authorization": "Bearer valid-token-123"}, 305 | "timeout": 10.0 306 | }, 307 | # API key server 308 | "api-key-server": { 309 | "url": "http://127.0.0.1:8002/mcp", 310 | "headers": {"X-API-Key": "sk-test-key-123"}, 311 | "timeout": 10.0 312 | } 313 | } 314 | 315 | print("✅ Mixed auth configuration structure validated") 316 | print("📋 This shows your library should support:") 317 | print(" • OAuth via 'auth' parameter") 318 | print(" • Bearer tokens via 'headers'") 319 | print(" • API keys via 'headers'") 320 | print(" • Multiple auth methods in one config") 321 | 322 | async def main(): 323 | """Run all OAuth 2.1-compliant tests.""" 324 | print("🧪 OAuth 2.1-Compliant Authentication Tests for langchain-mcp-tools") 325 | print("=" * 80) 326 | print("Prerequisites:") 327 | print(" • simple_oauth_server.py (OAuth 2.1-compliant) running on port 8003") 328 | print("=" * 80) 329 | 330 | await test_oauth_authentication() 331 | await test_oauth_error_scenarios() 332 | await test_mixed_auth_with_oauth() 333 | 334 | print("\n🎉 All OAuth Tests Completed!") 335 | print("\n📊 Summary of what was tested:") 336 | print(" ✅ OAuth 2.1-compliant authorization code flow with PKCE") 337 | print(" ✅ OAuth client provider integration") 338 | print(" ✅ Browser-based authorization flow") 339 | print(" ✅ Access token usage for MCP requests") 340 | print(" ✅ Tool execution with OAuth authentication") 341 | print(" ✅ Error handling for invalid OAuth configs") 342 | print("\n💡 Key validation points:") 343 | print(" • 'auth' parameter accepts OAuthClientProvider") 344 | print(" • OAuth flow completes successfully") 345 | print(" • Access tokens are used for MCP requests") 346 | print(" • OAuth works alongside other auth methods") 347 | print(" • Error scenarios are handled gracefully") 348 | 349 | if __name__ == "__main__": 350 | asyncio.run(main()) 351 | -------------------------------------------------------------------------------- /testfiles/streamable_http_oauth_test_server.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python3 2 | """ 3 | Simple OAuth MCP Test Server 4 | 5 | This server implements a minimal OAuth 2.1-compliant authorization server for testing 6 | your langchain-mcp-tools library's auth parameter support. 7 | 8 | This implementation follows OAuth 2.1 security best practices including: 9 | - PKCE (Proof Key for Code Exchange) support 10 | - Short-lived access tokens with refresh tokens 11 | - Secure authorization code flow only 12 | - No deprecated grant types (implicit, password) 13 | 14 | This is a simplified version that focuses on testing the OAuth flow 15 | rather than implementing a production-ready OAuth server. 16 | 17 | Usage: 18 | python simple_oauth_server.py 19 | 20 | Test with: 21 | python test_oauth_client.py 22 | """ 23 | 24 | import secrets 25 | import time 26 | import uvicorn 27 | from typing import Any, Dict 28 | from fastapi import FastAPI, Request, HTTPException, Form 29 | from fastapi.responses import RedirectResponse, JSONResponse, HTMLResponse 30 | from urllib.parse import urlencode, parse_qs 31 | from mcp.server.fastmcp import FastMCP 32 | 33 | # In-memory storage for simplicity (production would use a database) 34 | clients: Dict[str, Dict[str, Any]] = {} 35 | authorization_codes: Dict[str, Dict[str, Any]] = {} 36 | access_tokens: Dict[str, Dict[str, Any]] = {} 37 | 38 | # Pre-register a test client 39 | TEST_CLIENT = { 40 | "client_id": "test-mcp-client-123", 41 | "client_secret": "secret-456", 42 | "redirect_uris": ["http://localhost:3000/callback"], 43 | "grant_types": ["authorization_code", "refresh_token"], 44 | "response_types": ["code"], 45 | "scopes": ["read", "write"] 46 | } 47 | clients[TEST_CLIENT["client_id"]] = TEST_CLIENT 48 | 49 | # Create FastAPI app 50 | app = FastAPI(title="Simple OAuth MCP Test Server") 51 | 52 | # Create MCP server (stateless) 53 | mcp = FastMCP( 54 | name="OAuthTestServer", 55 | stateless_http=True, 56 | json_response=True 57 | ) 58 | 59 | @mcp.tool(description="Get authenticated user information") 60 | def get_current_user() -> str: 61 | """Get information about the currently authenticated user.""" 62 | return "Authenticated user: test-user@example.com (OAuth verified)" 63 | 64 | @mcp.tool(description="List user's documents") 65 | def list_user_documents() -> str: 66 | """List documents accessible to the authenticated user.""" 67 | return "User documents: document1.pdf, document2.txt, report.xlsx (OAuth authenticated)" 68 | 69 | @mcp.tool(description="Create a new document") 70 | def create_document(title: str, content: str) -> str: 71 | """Create a new document for the authenticated user.""" 72 | return f"Created document '{title}' with content: {content[:50]}... (OAuth authenticated)" 73 | 74 | @mcp.resource("user://profile") 75 | def get_user_profile() -> str: 76 | """Get user profile information.""" 77 | return "User profile: John Doe, john@example.com, Premium Account (OAuth authenticated)" 78 | 79 | # OAuth 2.1-Compliant Authorization Server Endpoints 80 | 81 | @app.get("/.well-known/oauth-authorization-server") 82 | async def authorization_server_metadata(): 83 | """OAuth 2.1-compliant Authorization Server Metadata (RFC 8414). 84 | 85 | This metadata indicates OAuth 2.1 compliance through: 86 | - PKCE support (code_challenge_methods_supported: S256) 87 | - Secure grant types only (no implicit, password grants) 88 | - Authorization code flow with refresh tokens 89 | - Dynamic client registration (RFC 7591) 90 | """ 91 | return { 92 | "issuer": "http://localhost:8003", 93 | "authorization_endpoint": "http://localhost:8003/authorize", 94 | "token_endpoint": "http://localhost:8003/token", 95 | "registration_endpoint": "http://localhost:8003/register", # RFC 7591: Dynamic Client Registration 96 | "response_types_supported": ["code"], # OAuth 2.1: code flow only 97 | "grant_types_supported": ["authorization_code", "refresh_token"], # OAuth 2.1: secure grants only 98 | "code_challenge_methods_supported": ["S256"], # OAuth 2.1: PKCE support 99 | "scopes_supported": ["read", "write"], 100 | "token_endpoint_auth_methods_supported": ["client_secret_post"] 101 | } 102 | 103 | @app.get("/authorize") 104 | async def authorize( 105 | response_type: str, 106 | client_id: str, 107 | redirect_uri: str, 108 | scope: str = "", 109 | state: str = "", 110 | code_challenge: str = "", 111 | code_challenge_method: str = "" 112 | ): 113 | """OAuth authorization endpoint.""" 114 | # Validate client 115 | client = clients.get(client_id) 116 | if not client: 117 | raise HTTPException(status_code=400, detail="Invalid client_id") 118 | 119 | # Validate redirect URI 120 | if redirect_uri not in client["redirect_uris"]: 121 | raise HTTPException(status_code=400, detail="Invalid redirect_uri") 122 | 123 | # For testing, auto-approve the authorization 124 | # In production, this would show a consent screen 125 | auth_code = f"code_{secrets.token_hex(16)}" 126 | 127 | # Store authorization code 128 | authorization_codes[auth_code] = { 129 | "client_id": client_id, 130 | "redirect_uri": redirect_uri, 131 | "scope": scope, 132 | "code_challenge": code_challenge, 133 | "code_challenge_method": code_challenge_method, 134 | "expires_at": time.time() + 600, # 10 minutes 135 | "used": False 136 | } 137 | 138 | # Redirect back to client with code 139 | params = {"code": auth_code} 140 | if state: 141 | params["state"] = state 142 | 143 | redirect_url = f"{redirect_uri}?{urlencode(params)}" 144 | return RedirectResponse(url=redirect_url) 145 | 146 | @app.post("/register") 147 | async def register_client(request: Request): 148 | """OAuth 2.0 Dynamic Client Registration (RFC 7591). 149 | 150 | This endpoint allows OAuth clients to register themselves dynamically 151 | without requiring pre-configuration. This is commonly used by OAuth 152 | client libraries like the MCP Python SDK. 153 | """ 154 | try: 155 | data = await request.json() 156 | 157 | # Generate unique client credentials 158 | client_id = f"dynamic-client-{secrets.token_hex(8)}" 159 | client_secret = secrets.token_urlsafe(32) 160 | 161 | # Validate required fields 162 | redirect_uris = data.get("redirect_uris", []) 163 | if not redirect_uris: 164 | raise HTTPException(status_code=400, detail="redirect_uris is required") 165 | 166 | # Create client configuration 167 | client_info = { 168 | "client_id": client_id, 169 | "client_secret": client_secret, 170 | "redirect_uris": redirect_uris, 171 | "grant_types": data.get("grant_types", ["authorization_code"]), 172 | "response_types": data.get("response_types", ["code"]), 173 | "scopes": data.get("scope", "read write").split() if isinstance(data.get("scope"), str) else data.get("scope", ["read", "write"]), 174 | "client_name": data.get("client_name", "Dynamic MCP Client"), 175 | "token_endpoint_auth_method": data.get("token_endpoint_auth_method", "client_secret_post") 176 | } 177 | 178 | # Store the dynamically registered client 179 | clients[client_id] = client_info 180 | 181 | print(f"🔧 Dynamically registered new client: {client_id}") 182 | print(f" Name: {client_info['client_name']}") 183 | print(f" Redirect URIs: {redirect_uris}") 184 | 185 | # Return client registration response (RFC 7591) 186 | return { 187 | "client_id": client_id, 188 | "client_secret": client_secret, 189 | "redirect_uris": client_info["redirect_uris"], 190 | "grant_types": client_info["grant_types"], 191 | "response_types": client_info["response_types"], 192 | "scope": " ".join(client_info["scopes"]), 193 | "token_endpoint_auth_method": client_info["token_endpoint_auth_method"], 194 | "client_name": client_info["client_name"] 195 | } 196 | 197 | except ValueError as e: 198 | raise HTTPException(status_code=400, detail=f"Invalid JSON: {e}") 199 | except Exception as e: 200 | print(f"❌ Client registration error: {e}") 201 | raise HTTPException(status_code=400, detail=f"Registration failed: {e}") 202 | 203 | @app.post("/token") 204 | async def token_endpoint( 205 | grant_type: str = Form(...), 206 | client_id: str = Form(...), 207 | client_secret: str = Form(...), 208 | code: str = Form(None), 209 | redirect_uri: str = Form(None), 210 | code_verifier: str = Form(None) 211 | ): 212 | """OAuth token endpoint.""" 213 | # Validate client credentials 214 | client = clients.get(client_id) 215 | if not client or client["client_secret"] != client_secret: 216 | raise HTTPException(status_code=401, detail="Invalid client credentials") 217 | 218 | if grant_type == "authorization_code": 219 | # Validate authorization code 220 | auth_code_data = authorization_codes.get(code) 221 | if not auth_code_data: 222 | raise HTTPException(status_code=400, detail="Invalid authorization code") 223 | 224 | if auth_code_data["used"]: 225 | raise HTTPException(status_code=400, detail="Authorization code already used") 226 | 227 | if auth_code_data["expires_at"] < time.time(): 228 | raise HTTPException(status_code=400, detail="Authorization code expired") 229 | 230 | if auth_code_data["client_id"] != client_id: 231 | raise HTTPException(status_code=400, detail="Client mismatch") 232 | 233 | # Mark code as used 234 | auth_code_data["used"] = True 235 | 236 | # Generate access token 237 | access_token = f"token_{secrets.token_hex(32)}" 238 | refresh_token = f"refresh_{secrets.token_hex(32)}" 239 | 240 | # Store tokens 241 | access_tokens[access_token] = { 242 | "client_id": client_id, 243 | "scope": auth_code_data["scope"], 244 | "expires_at": time.time() + 3600, # 1 hour 245 | "token_type": "Bearer" 246 | } 247 | 248 | return { 249 | "access_token": access_token, 250 | "token_type": "Bearer", 251 | "expires_in": 3600, 252 | "refresh_token": refresh_token, 253 | "scope": auth_code_data["scope"] 254 | } 255 | 256 | else: 257 | raise HTTPException(status_code=400, detail="Unsupported grant type") 258 | 259 | # Authentication middleware for MCP endpoints 260 | @app.middleware("http") 261 | async def oauth_auth_middleware(request: Request, call_next): 262 | """Apply OAuth authentication to MCP endpoints.""" 263 | if request.url.path.startswith("/mcp"): 264 | # Check for Authorization header 265 | auth_header = request.headers.get("authorization") 266 | if not auth_header or not auth_header.startswith("Bearer "): 267 | return JSONResponse( 268 | status_code=401, 269 | content={"error": "invalid_token", "error_description": "Missing or invalid access token"}, 270 | headers={"WWW-Authenticate": "Bearer"}, 271 | ) 272 | 273 | # Extract and validate token 274 | token = auth_header.replace("Bearer ", "") 275 | token_data = access_tokens.get(token) 276 | if not token_data: 277 | return JSONResponse( 278 | status_code=401, 279 | content={"error": "invalid_token", "error_description": "Invalid access token"}, 280 | headers={"WWW-Authenticate": "Bearer"}, 281 | ) 282 | 283 | # Check if token expired 284 | if token_data["expires_at"] < time.time(): 285 | return JSONResponse( 286 | status_code=401, 287 | content={"error": "invalid_token", "error_description": "Access token expired"}, 288 | headers={"WWW-Authenticate": "Bearer"}, 289 | ) 290 | 291 | response = await call_next(request) 292 | return response 293 | 294 | # Mount the MCP app 295 | app.mount("/mcp", mcp.streamable_http_app()) 296 | 297 | # Info endpoints 298 | @app.get("/") 299 | async def root(): 300 | """Server information.""" 301 | return { 302 | "name": "OAuth 2.1-compliant MCP Test Server", 303 | "oauth_endpoints": { 304 | "authorization": "/authorize", 305 | "token": "/token", 306 | "registration": "/register", 307 | "metadata": "/.well-known/oauth-authorization-server" 308 | }, 309 | "mcp_endpoint": "/mcp", 310 | "test_client": { 311 | "client_id": TEST_CLIENT["client_id"], 312 | "client_secret": TEST_CLIENT["client_secret"], 313 | "redirect_uris": TEST_CLIENT["redirect_uris"] 314 | } 315 | } 316 | 317 | @app.get("/health") 318 | async def health_check(): 319 | """Health check endpoint.""" 320 | return {"status": "healthy", "auth": "oauth2"} 321 | 322 | if __name__ == "__main__": 323 | print("🚀 Starting OAuth 2.1-Compliant MCP Test Server") 324 | print("🔐 Authentication: OAuth 2.1-compliant (OAuth 2.0 + PKCE)") 325 | print("🔒 Security Features: PKCE required, secure grants only, short-lived tokens") 326 | print("🔗 MCP Endpoint: http://localhost:8003/mcp") 327 | print("🔑 OAuth Endpoints:") 328 | print(" • Authorization: http://localhost:8003/authorize") 329 | print(" • Token: http://localhost:8003/token") 330 | print(" • Registration: http://localhost:8003/register (Dynamic Client Registration)") 331 | print(" • Metadata: http://localhost:8003/.well-known/oauth-authorization-server") 332 | print("-" * 70) 333 | print("🧪 Test Client Credentials:") 334 | print(f" • Client ID: {TEST_CLIENT['client_id']}") 335 | print(f" • Client Secret: {TEST_CLIENT['client_secret']}") 336 | print(f" • Redirect URI: {TEST_CLIENT['redirect_uris'][0]}") 337 | print("-" * 70) 338 | print("🛠️ Tools available: get_current_user, list_user_documents, create_document") 339 | print("📦 Resources available: user://profile") 340 | print("💡 Use Ctrl+C to stop the server") 341 | print("-" * 70) 342 | 343 | uvicorn.run( 344 | app, 345 | host="127.0.0.1", 346 | port=8003, 347 | log_level="info" 348 | ) 349 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # MCP to LangChain Tools Conversion Library / Python [](https://github.com/hideya/langchain-mcp-tools-py/blob/main/LICENSE) [](https://pypi.org/project/langchain-mcp-tools/) [](https://dependents.info/hideya/langchain-mcp-tools-py) 2 | 3 | A simple, lightweight library to use 4 | [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 5 | server tools from LangChain. 6 | 7 |
8 |
9 | Its simplicity and extra features for local MCP servers can make it useful as a basis for your own customizations.
10 | However, it only supports text results of tool calls and does not support MCP features other than tools.
11 |
12 | [LangChain's **official LangChain MCP Adapters** library](https://pypi.org/project/langchain-mcp-adapters/),
13 | which supports comprehensive integration with LangChain, has been released.
14 | You may want to consider using it if you don't have specific needs for this library.
15 |
16 | ## Prerequisites
17 |
18 | - Python 3.11+
19 |
20 | ## Installation
21 |
22 | ```bash
23 | pip install langchain-mcp-tools
24 | ```
25 |
26 | ## Quick Start
27 |
28 | `convert_mcp_to_langchain_tools()` utility function accepts MCP server configurations
29 | that follow the same structure as
30 | [Claude for Desktop](https://modelcontextprotocol.io/quickstart/user),
31 | but only the contents of the `mcpServers` property,
32 | and is expressed as a `dict`, e.g.:
33 |
34 | ```python
35 | mcp_servers = {
36 | "filesystem": {
37 | "command": "npx",
38 | "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
39 | },
40 | "fetch": {
41 | "command": "uvx",
42 | "args": ["mcp-server-fetch"]
43 | },
44 | "github": {
45 | "type": "http",
46 | "url": "https://api.githubcopilot.com/mcp/",
47 | "headers": {
48 | "Authorization": f"Bearer {os.environ.get('GITHUB_PERSONAL_ACCESS_TOKEN')}"
49 | }
50 | },
51 | "notion": { # For MCP servers that require OAuth, consider using "mcp-remote"
52 | "command": "npx",
53 | "args": ["-y", "mcp-remote", "https://mcp.notion.com/mcp"],
54 | },
55 | }
56 |
57 | tools, cleanup = await convert_mcp_to_langchain_tools(
58 | mcp_servers
59 | )
60 | ```
61 |
62 | This utility function initializes all specified MCP servers in parallel,
63 | and returns LangChain Tools
64 | ([`tools: list[BaseTool]`](https://python.langchain.com/api_reference/core/tools/langchain_core.tools.base.BaseTool.html#langchain_core.tools.base.BaseTool))
65 | by gathering available MCP tools from the servers,
66 | and by wrapping them into LangChain tools.
67 | It also returns an async callback function (`cleanup: McpServerCleanupFn`)
68 | to be invoked to close all MCP server sessions when finished.
69 |
70 | The returned tools can be used with LangChain, e.g.:
71 |
72 | ```python
73 | # from langchain.chat_models import init_chat_model
74 | llm = init_chat_model("google_genai:gemini-2.5-flash")
75 |
76 | # from langgraph.prebuilt import create_react_agent
77 | agent = create_react_agent(
78 | llm,
79 | tools
80 | )
81 | ```
82 |
83 | The returned `cleanup` function properly handles resource cleanup:
84 |
85 | - Closes all MCP server connections concurrently and logs any cleanup failures
86 | - Continues cleanup of remaining servers even if some fail
87 | - Should always be called when done using the tools
88 |
89 | It is typically invoked in a finally block:
90 |
91 | ```python
92 | try:
93 | tools, cleanup = await convert_mcp_to_langchain_tools(mcp_servers)
94 |
95 | # Use tools with your LLM
96 |
97 | finally:
98 | # cleanup can be undefined when an exeption occurs during initialization
99 | if "cleanup" in locals():
100 | await cleanup()
101 | ```
102 |
103 | A minimal but complete working usage example can be found
104 | [in this example in the langchain-mcp-tools-py-usage repo](https://github.com/hideya/langchain-mcp-tools-py-usage/blob/main/src/example.py)
105 |
106 | For hands-on experimentation with MCP server integration,
107 | try [this MCP Client CLI tool built with this library](https://pypi.org/project/mcp-chat/)
108 |
109 | A TypeScript equivalent of this utility is available
110 | [here](https://www.npmjs.com/package/@h1deya/langchain-mcp-tools)
111 |
112 | ## Introduction
113 |
114 | This package is intended to simplify the use of
115 | [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)
116 | server tools with LangChain / Python.
117 |
118 | [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is the de facto industry standard
119 | that dramatically expands the scope of LLMs by enabling the integration of external tools and resources,
120 | including DBs, Cloud Storages, GitHub, Docker, Slack, and more.
121 | There are quite a few useful MCP servers already available.
122 | See [MCP Server Listing on the Official Site](https://github.com/modelcontextprotocol/servers?tab=readme-ov-file#model-context-protocol-servers).
123 |
124 | This utility's goal is to make these numerous MCP servers easily accessible from LangChain.
125 | It contains a utility function `convert_mcp_to_langchain_tools()`.
126 | This async function handles parallel initialization of specified multiple MCP servers
127 | and converts their available tools into a list of LangChain-compatible tools.
128 |
129 | For detailed information on how to use this library, please refer to the following document:
130 | ["Supercharging LangChain: Integrating 2000+ MCP with ReAct"](https://medium.com/@h1deya/supercharging-langchain-integrating-450-mcp-with-react-d4e467cbf41a).
131 |
132 | ## MCP Protocol Support
133 |
134 | This library supports **MCP Protocol version 2025-03-26** and maintains backwards compatibility with version 2024-11-05.
135 | It follows the [official MCP specification](https://modelcontextprotocol.io/specification/2025-03-26/) for transport selection and backwards compatibility.
136 |
137 | ### Limitations
138 |
139 | - **Tool Return Types**: Currently, only text results of tool calls are supported.
140 | The library uses LangChain's `response_format: 'content'` (the default), which only supports text strings.
141 | While MCP tools can return multiple content types (text, images, etc.), this library currently filters and uses only text content.
142 | - **MCP Features**: Only MCP [Tools](https://modelcontextprotocol.io/docs/concepts/tools) are supported. Other MCP features like Resources, Prompts, and Sampling are not implemented.
143 |
144 | ### Note
145 |
146 | - **Passing PATH Env Variable**: The library automatically adds the `PATH` environment variable to stdio server configrations if not explicitly provided to ensure servers can find required executables.
147 |
148 | ## Features
149 |
150 | ### stderr Redirection for Local MCP Server
151 |
152 | A new key `"errlog"` has been introduced to specify a file-like object
153 | to which local (stdio) MCP server's stderr is redirected.
154 |
155 | ```python
156 | log_path = f"mcp-server-{server_name}.log"
157 | log_file = open(log_path, "w")
158 | mcp_servers[server_name]["errlog"] = log_file
159 | ```
160 |
161 | A usage example can be found [here](https://github.com/hideya/langchain-mcp-tools-py-usage/blob/3bd35d9fb49f4b631fe3d0cc8491d43cbf69693b/src/example.py#L88-L108).
162 | The key name `errlog` is derived from
163 | [`stdio_client()`'s argument `errlog`](https://github.com/modelcontextprotocol/python-sdk/blob/babb477dffa33f46cdc886bc885eb1d521151430/src/mcp/client/stdio/__init__.py#L96).
164 |
165 | ### Working Directory Configuration for Local MCP Servers
166 |
167 | The working directory that is used when spawning a local (stdio) MCP server
168 | can be specified with the `"cwd"` key as follows:
169 |
170 | ```python
171 | "local-server-name": {
172 | "command": "...",
173 | "args": [...],
174 | "cwd": "/working/directory" # the working dir to be use by the server
175 | },
176 | ```
177 |
178 | The key name `cwd` is derived from
179 | Python SDK's [`StdioServerParameters`](https://github.com/modelcontextprotocol/python-sdk/blob/babb477dffa33f46cdc886bc885eb1d521151430/src/mcp/client/stdio/__init__.py#L76-L77).
180 |
181 | ### Transport Selection Priority
182 |
183 | The library selects transports using the following priority order:
184 |
185 | 1. **Explicit transport/type field** (must match URL protocol if URL provided)
186 | 2. **URL protocol auto-detection** (http/https → StreamableHTTP → SSE, ws/wss → WebSocket)
187 | 3. **Command presence** → Stdio transport
188 | 4. **Error** if none of the above match
189 |
190 | This ensures predictable behavior while allowing flexibility for different deployment scenarios.
191 |
192 | ### Remote MCP Server Support
193 |
194 | `mcp_servers` configuration for Streamable HTTP, SSE (Server-Sent Events) and Websocket servers are as follows:
195 |
196 | ```py
197 | # Auto-detection: tries Streamable HTTP first, falls back to SSE on 4xx errors
198 | "auto-detect-server": {
199 | "url": f"http://{server_host}:{server_port}/..."
200 | },
201 |
202 | # Explicit Streamable HTTP
203 | "streamable-http-server": {
204 | "url": f"http://{server_host}:{server_port}/...",
205 | "transport": "streamable_http"
206 | # "type": "http" # VSCode-style config also works instead of the above
207 | },
208 |
209 | # Explicit SSE
210 | "sse-server-name": {
211 | "url": f"http://{sse_server_host}:{sse_server_port}/...",
212 | "transport": "sse" # or `"type": "sse"`
213 | },
214 |
215 | # WebSocket
216 | "ws-server-name": {
217 | "url": f"ws://${ws_server_host}:${ws_server_port}/..."
218 | # optionally `"transport": "ws"` or `"type": "ws"`
219 | },
220 | ```
221 |
222 | The `"headers"` key can be used to pass HTTP headers to Streamable HTTP and SSE connection.
223 |
224 | ```py
225 | "github": {
226 | "type": "http",
227 | "url": "https://api.githubcopilot.com/mcp/",
228 | "headers": {
229 | "Authorization": f"Bearer {os.environ.get('GITHUB_PERSONAL_ACCESS_TOKEN')}"
230 | }
231 | },
232 | ```
233 |
234 | NOTE: When accessing the GitHub MCP server, [GitHub PAT (Personal Access Token)](https://github.com/settings/personal-access-tokens)
235 | alone is not enough; your GitHub account must have an active Copilot subscription or be assigned a Copilot license through your organization.
236 |
237 | **Auto-detection behavior (default):**
238 | - For HTTP/HTTPS URLs without explicit `transport`, the library follows [MCP specification recommendations](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#backwards-compatibility)
239 | - First attempts Streamable HTTP transport
240 | - If Streamable HTTP fails with a 4xx error, automatically falls back to SSE transport
241 | - Non-4xx errors (network issues, etc.) are re-thrown without fallback
242 |
243 | **Explicit transport selection:**
244 | - Set `"transport": "streamable_http"` (or VSCode-style config `"type": "http"`) to force Streamable HTTP (no fallback)
245 | - Set `"transport": "sse"` to force SSE transport
246 | - WebSocket URLs (`ws://` or `wss://`) always use WebSocket transport
247 |
248 | Streamable HTTP is the modern MCP transport that replaces the older HTTP+SSE transport. According to the [official MCP documentation](https://modelcontextprotocol.io/docs/concepts/transports): "SSE as a standalone transport is deprecated as of protocol version 2025-03-26. It has been replaced by Streamable HTTP, which incorporates SSE as an optional streaming mechanism."
249 |
250 | ### Accessing Remote MCP Servers with OAuth Quickly
251 |
252 | If you need to use MCP servers that require OAuth, consider using **"[mcp-remote](https://www.npmjs.com/package/mcp-remote)"**.
253 |
254 | ```py
255 | "notionMCP": {
256 | "command": "npx",
257 | "args": ["-y", "mcp-remote", "https://mcp.notion.com/mcp"],
258 | },
259 | ```
260 |
261 | ### Authentication Support for Streamable HTTP Connections
262 |
263 | The library supports OAuth 2.1 authentication for Streamable HTTP connections:
264 |
265 | ```py
266 | from mcp.client.auth import OAuthClientProvider
267 | ...
268 |
269 | # Create OAuth authentication provider
270 | oauth_auth = OAuthClientProvider(
271 | server_url="https://...",
272 | client_metadata=...,
273 | storage=...,
274 | redirect_handler=...,
275 | callback_handler=...,
276 | )
277 |
278 | # Test configuration with OAuth auth
279 | mcp_servers = {
280 | "secure-streamable-server": {
281 | "url": "https://.../mcp/",
282 | // To avoid auto protocol fallback, specify the protocol explicitly when using authentication
283 | "transport": "streamable_http", // or `"type": "http",`
284 | "auth": oauth_auth,
285 | "timeout": 30.0
286 | },
287 | }
288 | ```
289 |
290 | Test implementations are provided:
291 |
292 | - **Streamable HTTP Authentication Tests**:
293 | - MCP client uses this library: [streamable_http_oauth_test_client.py](https://github.com/hideya/langchain-mcp-tools-py/tree/main/testfiles/streamable_http_oauth_test_client.py)
294 | - Test MCP Server: [streamable_http_oauth_test_server.py](https://github.com/hideya/langchain-mcp-tools-py/tree/main/testfiles/streamable_http_oauth_test_server.py)
295 |
296 | ### Authentication Support for SSE Connections (Legacy)
297 |
298 | The library also supports authentication for SSE connections to MCP servers.
299 | Note that SSE transport is deprecated; Streamable HTTP is the recommended approach.
300 |
301 | ## API docs
302 |
303 | Can be found [here](https://hideya.github.io/langchain-mcp-tools-py/)
304 |
305 | ## Change Log
306 |
307 | Can be found [here](https://github.com/hideya/langchain-mcp-tools-py/blob/main/CHANGELOG.md)
308 |
309 | ## Building from Source
310 |
311 | See [README_DEV.md](https://github.com/hideya/langchain-mcp-tools-py/blob/main/README_DEV.md) for details.
312 |
313 | ## Appendix
314 |
315 | ### Troubleshooting
316 |
317 | 1. **Enable debug logging**: Set the log level to DEBUG to see detailed connection and execution logs:
318 |
319 | ```
320 | tools, cleanup = await convert_mcp_to_langchain_tools(
321 | mcp_servers,
322 | logging.DEBUG
323 | )
324 | ```
325 | 2. **Check server errlog**: For stdio MCP servers, use `errlog` redirection to capture server error output
326 | 3. **Test explicit transports**: Try forcing specific transport types to isolate auto-detection issues
327 | 4. **Verify server independently**: Refer to [Debugging Section in MCP documentation](https://modelcontextprotocol.io/docs/tools/debugging)
328 |
329 | ### Troubleshooting Authentication Issues
330 |
331 | When authentication errors occur, they often generate massive logs that make it difficult to identify that authentication is the root cause.
332 |
333 | To address this problem, this library performs authentication pre-validation for HTTP/HTTPS MCP servers before attempting the actual MCP connection.
334 | This ensures that clear error messages like `Authentication failed (401 Unauthorized)` or `Authentication failed (403 Forbidden)` appear at the end of the logs, rather than being buried in the middle of extensive error output.
335 |
336 | **Important:** This pre-validation is specific to this library and not part of the official MCP specification.
337 | In rare cases, it may interfere with certain MCP server behaviors.
338 |
339 | #### When and How to Disable Pre-validation
340 | Set `"__pre_validate_authentication": False` in your server config if:
341 | - Using OAuth flows that require complex authentication handshakes
342 | - The MCP server doesn't accept simple HTTP POST requests for validation
343 | - You're experiencing false negatives in the auth validation
344 |
345 | **Example:**
346 | ```python
347 | "oauth-server": {
348 | "url": "https://api.example.com/mcp/",
349 | "auth": oauth_provider, # Complex OAuth provider
350 | "__pre_validate_authentication": False # Skip the pre-validation
351 | }
352 | ```
353 |
354 | ### Debugging Authentication
355 | 1. **Check your tokens/credentials** - Most auth failures are due to expired or incorrect tokens
356 | 2. **Verify token permissions** - Some MCP servers require specific scopes (e.g., GitHub Copilot license)
357 | 3. **Test with curl** - Try a simple HTTP request to verify your auth setup:
358 |
359 | ```bash
360 | curl -H "Authorization: Bearer your-token" https://api.example.com/mcp/
361 | ```
362 |
363 | ### For Developers
364 |
365 | See [TECHNICAL.md](./TECHNICAL.md) for technical details about implementation challenges and solutions.
366 |
--------------------------------------------------------------------------------
/src/langchain_mcp_tools/transport_utils.py:
--------------------------------------------------------------------------------
1 | """Utility functions for MCP server management and validation.
2 |
3 | This module contains helper functions used internally by the langchain_mcp_tools
4 | library for schema processing, error handling, authentication validation,
5 | transport testing, configuration validation, transport creation, and logging setup.
6 | """
7 |
8 | import logging
9 | import os
10 | import time
11 | from contextlib import AsyncExitStack
12 | from typing import Any, TypeAlias, cast
13 | from urllib.parse import urlparse
14 |
15 | try:
16 | import httpx
17 | from anyio.streams.memory import (
18 | MemoryObjectReceiveStream,
19 | MemoryObjectSendStream,
20 | )
21 | from mcp.client.sse import sse_client
22 | from mcp.client.stdio import stdio_client, StdioServerParameters
23 | from mcp.client.streamable_http import streamablehttp_client
24 | from mcp.client.websocket import websocket_client
25 | import mcp.types as mcp_types
26 | except ImportError as e:
27 | print(f"\nError: Required package not found: {e}")
28 | print("Please ensure all required packages are installed\n")
29 | import sys
30 | sys.exit(1)
31 |
32 |
33 | class McpInitializationError(Exception):
34 | """Raised when MCP server initialization fails."""
35 |
36 | def __init__(self, message: str, server_name: str | None = None):
37 | self.server_name = server_name
38 | super().__init__(message)
39 |
40 | def __str__(self) -> str:
41 | if self.server_name:
42 | return f'MCP server "{self.server_name}": {super().__str__()}'
43 | return super().__str__()
44 |
45 |
46 | # Type alias for bidirectional communication channels with MCP servers
47 | # Note: This type is not officially exported by mcp.types but represents
48 | # the standard transport interface used by all MCP client implementations
49 | Transport: TypeAlias = tuple[
50 | MemoryObjectReceiveStream[mcp_types.JSONRPCMessage | Exception],
51 | MemoryObjectSendStream[mcp_types.JSONRPCMessage]
52 | ]
53 |
54 |
55 | def _is_4xx_error(error: Exception) -> bool:
56 | """Enhanced 4xx error detection for transport fallback decisions.
57 |
58 | Used to decide whether to fall back from Streamable HTTP to SSE transport
59 | per MCP specification. Handles various error types and patterns that
60 | indicate 4xx-like conditions.
61 |
62 | Args:
63 | error: The error to check
64 |
65 | Returns:
66 | True if the error represents a 4xx HTTP status or equivalent
67 | """
68 | if not error:
69 | return False
70 |
71 | # Handle ExceptionGroup (Python 3.11+) by checking sub-exceptions
72 | if hasattr(error, 'exceptions'):
73 | return any(_is_4xx_error(sub_error) for sub_error in error.exceptions)
74 |
75 | # Check for explicit HTTP status codes
76 | if hasattr(error, 'status') and isinstance(error.status, int):
77 | return 400 <= error.status < 500
78 |
79 | # Check for httpx response errors
80 | if hasattr(error, 'response') and hasattr(error.response, 'status_code'):
81 | return 400 <= error.response.status_code < 500
82 |
83 | # Check error message for 4xx patterns
84 | error_str = str(error).lower()
85 |
86 | # Look for specific 4xx status codes (enhanced pattern matching)
87 | if any(code in error_str for code in ['400', '401', '402', '403', '404', '405', '406', '407', '408', '409']):
88 | return True
89 |
90 | # Look for 4xx error names (expanded list matching TypeScript version)
91 | return any(pattern in error_str for pattern in [
92 | 'bad request',
93 | 'unauthorized',
94 | 'forbidden',
95 | 'not found',
96 | 'method not allowed',
97 | 'not acceptable',
98 | 'request timeout',
99 | 'conflict'
100 | ])
101 |
102 |
103 | async def _validate_auth_before_connection(
104 | url_str: str,
105 | headers: dict[str, str] | None = None,
106 | timeout: float = 30.0,
107 | auth: httpx.Auth | None = None,
108 | logger: logging.Logger = logging.getLogger(__name__),
109 | server_name: str = "Unknown"
110 | ) -> tuple[bool, str]:
111 | """Pre-validate authentication with a simple HTTP request before creating MCP connection.
112 |
113 | This function helps avoid async generator cleanup bugs in the MCP client library
114 | by detecting authentication failures early, before the problematic MCP transport
115 | creation process begins.
116 |
117 | For OAuth authentication, this function skips validation since OAuth requires
118 | a complex flow that cannot be pre-validated with a simple HTTP request.
119 | Use __pre_validate_authentication=False to skip this validation.
120 |
121 | Args:
122 | url_str: The MCP server URL to test
123 | headers: Optional HTTP headers (typically containing Authorization)
124 | timeout: Request timeout in seconds
125 | auth: Optional httpx authentication object (OAuth providers are skipped)
126 | logger: Logger for debugging
127 | server_name: MCP server name to be validated
128 |
129 | Returns:
130 | Tuple of (success: bool, message: str) where:
131 | - success=True means authentication is valid or OAuth (skipped)
132 | - success=False means authentication failed with descriptive message
133 |
134 | Note:
135 | This function only validates simple authentication (401, 402, 403 errors).
136 | OAuth authentication is skipped since it requires complex flows.
137 | """
138 |
139 | # Skip auth validation for httpx.Auth providers (OAuth, etc.)
140 | # These require complex authentication flows that cannot be pre-validated
141 | # with a simple HTTP request
142 | if auth is not None:
143 | auth_class_name = auth.__class__.__name__
144 | logger.info(f'MCP server "{server_name}": Skipping auth validation for httpx.Auth provider: {auth_class_name}')
145 | return True, "httpx.Auth authentication skipped (requires full flow)"
146 |
147 | # Create InitializeRequest as per MCP specification (similar to test_streamable_http_support)
148 | init_request = {
149 | "jsonrpc": "2.0",
150 | "id": f"auth-test-{int(time.time() * 1000)}",
151 | "method": "initialize",
152 | "params": {
153 | "protocolVersion": "2024-11-05",
154 | "capabilities": {},
155 | "clientInfo": {
156 | "name": "mcp-auth-test",
157 | "version": "1.0.0"
158 | }
159 | }
160 | }
161 |
162 | # Required headers per MCP specification
163 | request_headers = {
164 | 'Content-Type': 'application/json',
165 | 'Accept': 'application/json, text/event-stream'
166 | }
167 | if headers:
168 | request_headers.update(headers)
169 |
170 | try:
171 | async with httpx.AsyncClient() as client:
172 | logger.debug(f"Pre-validating authentication for: {url_str}")
173 | response = await client.post(
174 | url_str,
175 | json=init_request,
176 | headers=request_headers,
177 | timeout=timeout,
178 | auth=auth
179 | )
180 |
181 | if response.status_code == 401:
182 | return False, f"Authentication failed (401 Unauthorized): {response.text if hasattr(response, 'text') else 'Unknown error'}"
183 | elif response.status_code == 402:
184 | return False, f"Authentication failed (402 Payment Required): {response.text if hasattr(response, 'text') else 'Unknown error'}"
185 | elif response.status_code == 403:
186 | return False, f"Authentication failed (403 Forbidden): {response.text if hasattr(response, 'text') else 'Unknown error'}"
187 |
188 | logger.info(f'MCP server "{server_name}": Authentication validation passed: {response.status_code}')
189 | return True, "Authentication validation passed"
190 |
191 | except httpx.HTTPStatusError as e:
192 | return False, f"HTTP Error ({e.response.status_code}): {e}"
193 | except (httpx.ConnectError, httpx.TimeoutException) as e:
194 | return False, f"Connection failed: {e}"
195 | except Exception as e:
196 | return False, f"Unexpected error during auth validation: {e}"
197 |
198 |
199 | async def _test_streamable_http_support(
200 | url: str,
201 | headers: dict[str, str] | None = None,
202 | timeout: float = 30.0,
203 | auth: httpx.Auth | None = None,
204 | logger: logging.Logger = logging.getLogger(__name__)
205 | ) -> bool:
206 | """Test if URL supports Streamable HTTP per official MCP specification.
207 |
208 | Follows the MCP specification's recommended approach for backwards compatibility.
209 | Uses proper InitializeRequest with official protocol version and required headers.
210 |
211 | See: https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#backwards-compatibility
212 |
213 | Args:
214 | url: The MCP server URL to test
215 | headers: Optional HTTP headers
216 | timeout: Request timeout
217 | auth: Optional httpx authentication
218 | logger: Logger for debugging
219 |
220 | Returns:
221 | True if Streamable HTTP is supported, False if should fallback to SSE
222 |
223 | Raises:
224 | Exception: For non-4xx errors that should be re-raised
225 | """
226 | # Create InitializeRequest as per MCP specification
227 | init_request = {
228 | "jsonrpc": "2.0",
229 | "id": f"transport-test-{int(time.time() * 1000)}", # Use milliseconds like TS version
230 | "method": "initialize",
231 | "params": {
232 | "protocolVersion": "2024-11-05", # Official MCP Protocol version
233 | "capabilities": {},
234 | "clientInfo": {
235 | "name": "mcp-transport-test",
236 | "version": "1.0.0"
237 | }
238 | }
239 | }
240 |
241 | # Required headers per MCP specification
242 | request_headers = {
243 | 'Content-Type': 'application/json',
244 | 'Accept': 'application/json, text/event-stream' # Required by spec
245 | }
246 | if headers:
247 | request_headers.update(headers)
248 |
249 | try:
250 | async with httpx.AsyncClient(follow_redirects=True) as client:
251 | logger.debug(f"Testing Streamable HTTP: POST InitializeRequest to {url}")
252 | response = await client.post(
253 | url,
254 | json=init_request,
255 | headers=request_headers,
256 | timeout=timeout,
257 | auth=auth
258 | )
259 |
260 | logger.debug(f"Transport test response: {response.status_code} {response.headers.get('content-type', 'N/A')}")
261 |
262 | if response.status_code == 200:
263 | # Success indicates Streamable HTTP support
264 | logger.debug("Streamable HTTP test successful")
265 | return True
266 | elif 400 <= response.status_code < 500:
267 | # 4xx error indicates fallback to SSE per MCP spec
268 | logger.debug(f"Received {response.status_code}, should fallback to SSE")
269 | return False
270 | else:
271 | # Other errors should be re-raised
272 | response.raise_for_status()
273 | return True # If we get here, it succeeded
274 |
275 | except httpx.TimeoutException:
276 | logger.debug("Request timeout - treating as connection error")
277 | raise
278 | except httpx.ConnectError:
279 | logger.debug("Connection error")
280 | raise
281 | except Exception as e:
282 | # Check if it's a 4xx-like error using improved detection
283 | if _is_4xx_error(e):
284 | logger.debug(f"4xx-like error detected: {e}")
285 | return False
286 | raise
287 |
288 |
289 | def _validate_mcp_server_config(
290 | server_name: str,
291 | server_config: Any, # Use Any to avoid circular import, will be properly typed in main file
292 | logger: logging.Logger
293 | ) -> None:
294 | """Validates MCP server configuration following TypeScript transport selection logic.
295 |
296 | Transport Selection Priority:
297 | 1. Explicit transport/type field (must match URL protocol if URL provided)
298 | 2. URL protocol auto-detection (http/https → StreamableHTTP, ws/wss → WebSocket)
299 | 3. Command presence → Stdio transport
300 | 4. Error if none of the above match
301 |
302 | Conflicts that cause errors:
303 | - Both url and command specified
304 | - transport/type doesn't match URL protocol
305 | - transport requires URL but no URL provided
306 | - transport requires command but no command provided
307 |
308 | Args:
309 | server_name: Server instance name for error messages
310 | server_config: Configuration to validate
311 | logger: Logger for warnings
312 |
313 | Raises:
314 | McpInitializationError: If configuration is invalid
315 | """
316 | has_url = "url" in server_config and server_config["url"] is not None
317 | has_command = "command" in server_config and server_config["command"] is not None
318 |
319 | # Get transport type (prefer 'transport' over 'type' for compatibility)
320 | transport_type = server_config.get("transport") or server_config.get("type")
321 |
322 | # Conflict check: Both url and command specified
323 | if has_url and has_command:
324 | raise McpInitializationError(
325 | f'Cannot specify both "url" ({server_config["url"]}) '
326 | f'and "command" ({server_config["command"]}). Use "url" for remote servers '
327 | f'or "command" for local servers.',
328 | server_name=server_name
329 | )
330 |
331 | # Must have either URL or command
332 | if not has_url and not has_command:
333 | raise McpInitializationError(
334 | 'Either "url" or "command" must be specified',
335 | server_name=server_name
336 | )
337 |
338 | if has_url:
339 | url_str = str(server_config["url"])
340 | try:
341 | parsed_url = urlparse(url_str)
342 | url_scheme = parsed_url.scheme.lower()
343 | except Exception:
344 | raise McpInitializationError(
345 | f'Invalid URL format: {url_str}',
346 | server_name=server_name
347 | )
348 |
349 | if transport_type:
350 | transport_lower = transport_type.lower()
351 |
352 | # Check transport/URL protocol compatibility
353 | if transport_lower in ["http", "streamable_http"] and url_scheme not in ["http", "https"]:
354 | raise McpInitializationError(
355 | f'Transport "{transport_type}" requires '
356 | f'http:// or https:// URL, but got: {url_scheme}://',
357 | server_name=server_name
358 | )
359 | elif transport_lower == "sse" and url_scheme not in ["http", "https"]:
360 | raise McpInitializationError(
361 | f'Transport "sse" requires '
362 | f'http:// or https:// URL, but got: {url_scheme}://',
363 | server_name=server_name
364 | )
365 | elif transport_lower in ["ws", "websocket"] and url_scheme not in ["ws", "wss"]:
366 | raise McpInitializationError(
367 | f'Transport "{transport_type}" requires '
368 | f'ws:// or wss:// URL, but got: {url_scheme}://',
369 | server_name=server_name
370 | )
371 | elif transport_lower == "stdio":
372 | raise McpInitializationError(
373 | f'Transport "stdio" requires "command", '
374 | f'but "url" was provided',
375 | server_name=server_name
376 | )
377 |
378 | # Validate URL scheme is supported
379 | if url_scheme not in ["http", "https", "ws", "wss"]:
380 | raise McpInitializationError(
381 | f'Unsupported URL scheme "{url_scheme}". '
382 | f'Supported schemes: http, https, ws, wss',
383 | server_name=server_name
384 | )
385 |
386 | elif has_command:
387 | if transport_type:
388 | transport_lower = transport_type.lower()
389 |
390 | # Check transport requires command
391 | if transport_lower == "stdio":
392 | pass # Valid
393 | elif transport_lower in ["http", "streamable_http", "sse", "ws", "websocket"]:
394 | raise McpInitializationError(
395 | f'Transport "{transport_type}" requires "url", '
396 | f'but "command" was provided',
397 | server_name=server_name
398 | )
399 | else:
400 | logger.warning(
401 | f'MCP server "{server_name}": Unknown transport type "{transport_type}", '
402 | f'treating as stdio'
403 | )
404 |
--------------------------------------------------------------------------------
/src/langchain_mcp_tools/langchain_mcp_tools.py:
--------------------------------------------------------------------------------
1 | # Public API
2 | __all__ = [
3 | 'convert_mcp_to_langchain_tools',
4 | 'McpServersConfig',
5 | 'SingleMcpServerConfig',
6 | 'McpServerCommandBasedConfig',
7 | 'McpServerUrlBasedConfig',
8 | 'McpInitializationError'
9 | ]
10 |
11 | # Standard library imports
12 | import logging
13 | import os
14 | import sys
15 | from contextlib import AsyncExitStack, asynccontextmanager
16 | from typing import (
17 | Awaitable,
18 | Callable,
19 | cast,
20 | NotRequired,
21 | TextIO,
22 | TypeAlias,
23 | TypedDict,
24 | )
25 | from urllib.parse import urlparse
26 | import time
27 |
28 | # Third-party imports
29 | try:
30 | from anyio.streams.memory import (
31 | MemoryObjectReceiveStream,
32 | MemoryObjectSendStream,
33 | )
34 | import httpx
35 | from langchain_core.tools import BaseTool
36 | from mcp import ClientSession
37 | from mcp.client.sse import sse_client
38 | from mcp.client.stdio import stdio_client, StdioServerParameters
39 | from mcp.client.streamable_http import streamablehttp_client
40 | from mcp.client.websocket import websocket_client
41 | from mcp.shared._httpx_utils import McpHttpClientFactory
42 | import mcp.types as mcp_types
43 | # from pydantic_core import to_json
44 | except ImportError as e:
45 | print(f"\nError: Required package not found: {e}")
46 | print("Please ensure all required packages are installed\n")
47 | sys.exit(1)
48 |
49 | # Local imports
50 | from .tool_adapter import create_mcp_langchain_adapter
51 | from .transport_utils import (
52 | Transport,
53 | McpInitializationError,
54 | _validate_auth_before_connection,
55 | _test_streamable_http_support,
56 | _validate_mcp_server_config,
57 | )
58 |
59 |
60 | class McpServerCommandBasedConfig(TypedDict):
61 | """Configuration for an MCP server launched via command line.
62 |
63 | This configuration is used for local MCP servers that are started as child
64 | processes using the stdio client. It defines the command to run, optional
65 | arguments, environment variables, working directory, and error logging
66 | options.
67 |
68 | Attributes:
69 | command: The executable command to run (e.g., "npx", "uvx", "python").
70 | args: Optional list of command-line arguments to pass to the command.
71 | env: Optional dictionary of environment variables to set for the
72 | process.
73 | cwd: Optional working directory where the command will be executed.
74 | errlog: Optional file-like object for redirecting the server's stderr
75 | output.
76 |
77 | Example:
78 | {
79 | "command": "npx",
80 | "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
81 | "env": {"NODE_ENV": "production"},
82 | "cwd": "/path/to/working/directory",
83 | "errlog": open("server.log", "w")
84 | }
85 | """
86 | command: str
87 | args: NotRequired[list[str] | None]
88 | env: NotRequired[dict[str, str] | None]
89 | cwd: NotRequired[str | None]
90 | errlog: NotRequired[TextIO | None]
91 |
92 |
93 | class McpServerUrlBasedConfig(TypedDict):
94 | """Configuration for a remote MCP server accessed via URL.
95 |
96 | This configuration is used for remote MCP servers that are accessed via
97 | HTTP/HTTPS (Streamable HTTP, Server-Sent Events) or WebSocket connections.
98 | It defines the URL to connect to and optional HTTP headers for authentication.
99 |
100 | Note: Per MCP spec, clients should try Streamable HTTP first, then fallback
101 | to SSE on 4xx errors for maximum compatibility.
102 |
103 | Attributes:
104 | url: The URL of the remote MCP server. For HTTP/HTTPS servers,
105 | use http:// or https:// prefix. For WebSocket servers,
106 | use ws:// or wss:// prefix.
107 | transport: Optional transport type. Supported values:
108 | "streamable_http" or "http" (recommended, attempted first),
109 | "sse" (deprecated, fallback), "websocket"
110 | type: Optional alternative field name for transport (for compatibility)
111 | headers: Optional dictionary of HTTP headers to include in the request,
112 | typically used for authentication (e.g., bearer tokens).
113 | timeout: Optional timeout for HTTP requests (default: 30.0 seconds).
114 | sse_read_timeout: Optional timeout for SSE connections (SSE only).
115 | terminate_on_close: Optional flag to terminate on connection close.
116 | httpx_client_factory: Optional factory for creating HTTP clients.
117 | auth: Optional httpx authentication for requests.
118 | __pre_validate_authentication: Optional flag to skip auth validation
119 | (default: True). Set to False for OAuth flows that require
120 | complex authentication flows.
121 |
122 | Example for auto-detection (recommended):
123 | {
124 | "url": "https://api.example.com/mcp",
125 | # Auto-tries Streamable HTTP first, falls back to SSE on 4xx
126 | "headers": {"Authorization": "Bearer token123"},
127 | "timeout": 60.0
128 | }
129 |
130 | Example for explicit Streamable HTTP:
131 | {
132 | "url": "https://api.example.com/mcp",
133 | "transport": "streamable_http",
134 | "headers": {"Authorization": "Bearer token123"},
135 | "timeout": 60.0
136 | }
137 |
138 | Example for explicit SSE (legacy):
139 | {
140 | "url": "https://example.com/mcp/sse",
141 | "transport": "sse",
142 | "headers": {"Authorization": "Bearer token123"}
143 | }
144 |
145 | Example for WebSocket:
146 | {
147 | "url": "wss://example.com/mcp/ws",
148 | "transport": "websocket"
149 | }
150 | """
151 | url: str
152 | transport: NotRequired[str] # Preferred field name
153 | type: NotRequired[str] # Alternative field name for compatibility
154 | headers: NotRequired[dict[str, str] | None]
155 | timeout: NotRequired[float]
156 | sse_read_timeout: NotRequired[float]
157 | terminate_on_close: NotRequired[bool]
158 | httpx_client_factory: NotRequired[McpHttpClientFactory]
159 | auth: NotRequired[httpx.Auth]
160 | __prevalidate_authentication: NotRequired[bool]
161 |
162 | # Type for a single MCP server configuration, which can be either
163 | # command-based or URL-based.
164 | SingleMcpServerConfig = McpServerCommandBasedConfig | McpServerUrlBasedConfig
165 | """Configuration for a single MCP server, either command-based or URL-based.
166 |
167 | This type represents the configuration for a single MCP server, which can
168 | be either:
169 | 1. A local server launched via command line (McpServerCommandBasedConfig)
170 | 2. A remote server accessed via URL (McpServerUrlBasedConfig)
171 |
172 | The type is determined by the presence of either the "command" key
173 | (for command-based) or the "url" key (for URL-based).
174 | """
175 |
176 | # Configuration dictionary for multiple MCP servers
177 | McpServersConfig = dict[str, SingleMcpServerConfig]
178 | """Configuration dictionary for multiple MCP servers.
179 |
180 | A dictionary mapping server names (as strings) to their respective
181 | configurations. Each server name acts as a logical identifier used for logging
182 | and debugging. The configuration for each server can be either command-based
183 | or URL-based.
184 |
185 | Example:
186 | {
187 | "filesystem": {
188 | "command": "npx",
189 | "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
190 | },
191 | "fetch": {
192 | "command": "uvx",
193 | "args": ["mcp-server-fetch"]
194 | },
195 | "auto-detection-server": {
196 | "url": "https://api.example.com/mcp",
197 | # Will try Streamable HTTP first, fallback to SSE on 4xx
198 | "headers": {"Authorization": "Bearer token123"},
199 | "timeout": 60.0
200 | },
201 | "explicit-sse-server": {
202 | "url": "https://legacy.example.com/mcp/sse",
203 | "transport": "sse",
204 | "headers": {"Authorization": "Bearer token123"}
205 | }
206 | }
207 | """
208 |
209 |
210 | # Type alias for bidirectional communication channels with MCP servers
211 | # Note: This type is not officially exported by mcp.types but represents
212 | # the standard transport interface used by all MCP client implementations
213 | Transport: TypeAlias = tuple[
214 | MemoryObjectReceiveStream[mcp_types.JSONRPCMessage | Exception],
215 | MemoryObjectSendStream[mcp_types.JSONRPCMessage]
216 | ]
217 |
218 |
219 | async def _connect_to_mcp_server(
220 | server_name: str,
221 | server_config: SingleMcpServerConfig,
222 | exit_stack: AsyncExitStack,
223 | logger: logging.Logger = logging.getLogger(__name__)
224 | ) -> Transport:
225 | """Establishes a connection to an MCP server with robust error handling.
226 |
227 | Implements consistent transport selection logic and includes authentication
228 | pre-validation to prevent async generator cleanup bugs in the MCP client library.
229 |
230 | Transport Selection Priority:
231 | 1. Explicit transport/type field (must match URL protocol if URL provided)
232 | 2. URL protocol auto-detection (http/https → StreamableHTTP, ws/wss → WebSocket)
233 | 3. Command presence → Stdio transport
234 | 4. Error if none of the above match
235 |
236 | For HTTP URLs without explicit transport, follows MCP specification backwards
237 | compatibility: try Streamable HTTP first, fallback to SSE on 4xx errors.
238 |
239 | Authentication Pre-validation:
240 | For HTTP/HTTPS servers, authentication is pre-validated before attempting
241 | the actual MCP connection to avoid async generator cleanup issues that can
242 | occur in the underlying MCP client library when authentication fails.
243 |
244 | Supports multiple transport types:
245 | - stdio: For local command-based servers
246 | - streamable_http, http: For Streamable HTTP servers
247 | - sse: For Server-Sent Events HTTP servers (legacy)
248 | - websocket, ws: For WebSocket servers
249 |
250 | Args:
251 | server_name: Server instance name to use for better logging and error context
252 | server_config: Configuration dictionary for server setup
253 | exit_stack: AsyncExitStack for managing transport lifecycle and cleanup
254 | logger: Logger instance for debugging and monitoring
255 |
256 | Returns:
257 | A Transport tuple containing receive and send streams for server communication
258 |
259 | Raises:
260 | McpInitializationError: If configuration is invalid or server initialization fails
261 | Exception: If unexpected errors occur during connection
262 | """
263 | try:
264 | logger.info(f'MCP server "{server_name}": '
265 | f"initializing with: {server_config}")
266 |
267 | # Validate configuration first
268 | _validate_mcp_server_config(server_name, server_config, logger)
269 |
270 | # Determine if URL-based or command-based
271 | has_url = "url" in server_config and server_config["url"] is not None
272 | has_command = "command" in server_config and server_config["command"] is not None
273 |
274 | # Get transport type (prefer 'transport' over 'type')
275 | transport_type = server_config.get("transport") or server_config.get("type")
276 |
277 | if has_url:
278 | # URL-based configuration
279 | url_config = cast(McpServerUrlBasedConfig, server_config)
280 | url_str = str(url_config["url"])
281 | parsed_url = urlparse(url_str)
282 | url_scheme = parsed_url.scheme.lower()
283 |
284 | # Extract common parameters
285 | headers = url_config.get("headers", None)
286 | timeout = url_config.get("timeout", None)
287 | auth = url_config.get("auth", None)
288 |
289 | if url_scheme in ["http", "https"]:
290 | # HTTP/HTTPS: Handle explicit transport or auto-detection
291 | if url_config.get("__pre_validate_authentication", True):
292 | # Pre-validate authentication to avoid MCP async generator cleanup bugs
293 | logger.info(f'MCP server "{server_name}": Pre-validating authentication')
294 | auth_valid, auth_message = await _validate_auth_before_connection(
295 | url_str,
296 | headers=headers,
297 | timeout=timeout or 30.0,
298 | auth=auth,
299 | logger=logger,
300 | server_name=server_name
301 | )
302 |
303 | if not auth_valid:
304 | # logger.error(f'MCP server "{server_name}": {auth_message}')
305 | raise McpInitializationError(auth_message, server_name=server_name)
306 |
307 | # Now proceed with the original connection logic
308 | if transport_type and transport_type.lower() in ["streamable_http", "http"]:
309 | # Explicit Streamable HTTP (no fallback)
310 | logger.info(f'MCP server "{server_name}": '
311 | f"connecting via Streamable HTTP (explicit) to {url_str}")
312 |
313 | kwargs = {}
314 | if headers is not None:
315 | kwargs["headers"] = headers
316 | if timeout is not None:
317 | kwargs["timeout"] = timeout
318 | if auth is not None:
319 | kwargs["auth"] = auth
320 |
321 | transport = await exit_stack.enter_async_context(
322 | streamablehttp_client(url_str, **kwargs)
323 | )
324 |
325 | elif transport_type and transport_type.lower() == "sse":
326 | # Explicit SSE (no fallback)
327 | logger.info(f'MCP server "{server_name}": '
328 | f"connecting via SSE (explicit) to {url_str}")
329 | logger.warning(f'MCP server "{server_name}": '
330 | f"Using SSE transport (deprecated as of MCP 2025-03-26), consider migrating to streamable_http")
331 |
332 | transport = await exit_stack.enter_async_context(
333 | sse_client(url_str, headers=headers)
334 | )
335 |
336 | else:
337 | # Auto-detection: URL protocol suggests HTTP transport, try Streamable HTTP first
338 | logger.debug(f'MCP server "{server_name}": '
339 | f"auto-detecting HTTP transport using MCP specification method")
340 |
341 | try:
342 | logger.info(f'MCP server "{server_name}": '
343 | f"testing Streamable HTTP support for {url_str}")
344 |
345 | supports_streamable = await _test_streamable_http_support(
346 | url_str,
347 | headers=headers,
348 | timeout=timeout,
349 | auth=auth,
350 | logger=logger
351 | )
352 |
353 | if supports_streamable:
354 | logger.info(f'MCP server "{server_name}": '
355 | f"detected Streamable HTTP transport support")
356 |
357 | kwargs = {}
358 | if headers is not None:
359 | kwargs["headers"] = headers
360 | if timeout is not None:
361 | kwargs["timeout"] = timeout
362 | if auth is not None:
363 | kwargs["auth"] = auth
364 |
365 | transport = await exit_stack.enter_async_context(
366 | streamablehttp_client(url_str, **kwargs)
367 | )
368 |
369 | else:
370 | logger.info(f'MCP server "{server_name}": '
371 | f"received 4xx error, falling back to SSE transport")
372 | logger.warning(f'MCP server "{server_name}": '
373 | f"Using SSE transport (deprecated as of MCP 2025-03-26), server should support Streamable HTTP")
374 |
375 | transport = await exit_stack.enter_async_context(
376 | sse_client(url_str, headers=headers)
377 | )
378 |
379 | except Exception as error:
380 | logger.error(f'MCP server "{server_name}": '
381 | f"transport detection failed: {error}")
382 | raise
383 |
384 | elif url_scheme in ["ws", "wss"]:
385 | # WebSocket transport
386 | if transport_type and transport_type.lower() not in ["websocket", "ws"]:
387 | logger.warning(f'MCP server "{server_name}": '
388 | f'URL scheme "{url_scheme}" suggests WebSocket, '
389 | f'but transport "{transport_type}" specified')
390 |
391 | logger.info(f'MCP server "{server_name}": '
392 | f"connecting via WebSocket to {url_str}")
393 |
394 | transport = await exit_stack.enter_async_context(
395 | websocket_client(url_str)
396 | )
397 |
398 | else:
399 | # This should be caught by validation, but include for safety
400 | raise McpInitializationError(
401 | f'Unsupported URL scheme "{url_scheme}". '
402 | f'Supported schemes: http/https (for streamable_http/sse), ws/wss (for websocket)',
403 | server_name=server_name
404 | )
405 |
406 | elif has_command:
407 | # Command-based configuration (stdio transport)
408 | if transport_type and transport_type.lower() not in ["stdio", ""]:
409 | logger.warning(f'MCP server "{server_name}": '
410 | f'Command provided suggests stdio transport, '
411 | f'but transport "{transport_type}" specified')
412 |
413 | logger.info(f'MCP server "{server_name}": '
414 | f"spawning local process via stdio")
415 |
416 | # NOTE: `uv` and `npx` seem to require PATH to be set.
417 | # To avoid confusion, it was decided to automatically append it
418 | # to the env if not explicitly set by the config.
419 | config = cast(McpServerCommandBasedConfig, server_config)
420 | # env = config.get("env", {}) doesn't work since it can yield None
421 | env_val = config.get("env")
422 | env = {} if env_val is None else dict(env_val)
423 | if "PATH" not in env:
424 | env["PATH"] = os.environ.get("PATH", "")
425 |
426 | # Use stdio client for commands
427 | # args = config.get("args", []) doesn't work since it can yield None
428 | args_val = config.get("args")
429 | args = [] if args_val is None else list(args_val)
430 | server_parameters = StdioServerParameters(
431 | command=config.get("command", ""),
432 | args=args,
433 | env=env,
434 | cwd=config.get("cwd", None)
435 | )
436 |
437 | # Initialize stdio client and register it with exit stack for cleanup
438 | errlog_val = config.get("errlog")
439 | kwargs = {"errlog": errlog_val} if errlog_val is not None else {}
440 | transport = await exit_stack.enter_async_context(
441 | stdio_client(server_parameters, **kwargs)
442 | )
443 |
444 | else:
445 | # This should be caught by validation, but include for safety
446 | raise McpInitializationError(
447 | 'Invalid configuration - '
448 | 'either "url" or "command" must be specified',
449 | server_name=server_name
450 | )
451 |
452 | except Exception as e:
453 | logger.error(f'MCP server "{server_name}": error during initialization: {str(e)}')
454 | raise
455 |
456 | return transport
457 |
458 |
459 | async def _get_mcp_server_tools(
460 | server_name: str,
461 | transport: Transport,
462 | exit_stack: AsyncExitStack,
463 | logger: logging.Logger = logging.getLogger(__name__)
464 | ) -> list[BaseTool]:
465 | """Retrieves and converts MCP server tools to LangChain BaseTool format.
466 |
467 | Establishes a client session with the MCP server, lists available tools,
468 | and wraps each tool in a LangChain-compatible adapter class. The adapter
469 | handles async execution, error handling, and result formatting.
470 |
471 | Tool Conversion Features:
472 | - JSON Schema to Pydantic model conversion for argument validation
473 | - Async-only execution (raises NotImplementedError for sync calls)
474 | - Automatic result formatting from MCP TextContent to strings
475 | - Error handling with ToolException for MCP tool failures
476 | - Comprehensive logging of tool input/output and execution metrics
477 |
478 | Args:
479 | server_name: Server instance name for logging and error context
480 | transport: Communication channels tuple (2-tuple for SSE/stdio, 3-tuple for streamable HTTP)
481 | exit_stack: AsyncExitStack for managing session lifecycle and cleanup
482 | logger: Logger instance for debugging and monitoring
483 |
484 | Returns:
485 | List of LangChain BaseTool instances that wrap MCP server tools
486 |
487 | Raises:
488 | McpInitializationError: If transport format is unexpected or session initialization fails
489 | Exception: If tool retrieval or conversion fails
490 | """
491 | try:
492 | # Handle both 2-tuple (SSE, stdio) and 3-tuple (streamable HTTP) returns
493 | # Third element in streamable HTTP contains session info/metadata
494 | if len(transport) == 2:
495 | read, write = transport
496 | elif len(transport) == 3:
497 | read, write, _ = transport # Third element is session info/metadata
498 | else:
499 | raise McpInitializationError(
500 | f"Unexpected transport tuple length: {len(transport)}",
501 | server_name=server_name
502 | )
503 |
504 | # Use an intermediate `asynccontextmanager` to log the cleanup message
505 | @asynccontextmanager
506 | async def log_before_aexit(context_manager, message):
507 | """Helper context manager that logs before cleanup"""
508 | yield await context_manager.__aenter__()
509 | try:
510 | logger.info(message)
511 | finally:
512 | await context_manager.__aexit__(None, None, None)
513 |
514 | # Initialize client session with cleanup logging
515 | session = await exit_stack.enter_async_context(
516 | log_before_aexit(
517 | ClientSession(read, write),
518 | f'MCP server "{server_name}": session closed'
519 | )
520 | )
521 |
522 | await session.initialize()
523 | logger.info(f'MCP server "{server_name}": connected')
524 |
525 | # Get MCP tools
526 | tools_response = await session.list_tools()
527 |
528 | # Wrap MCP tools into LangChain tools
529 | langchain_tools: list[BaseTool] = []
530 | for tool in tools_response.tools:
531 | adapter = create_mcp_langchain_adapter(tool, session, server_name, logger)
532 | langchain_tools.append(adapter)
533 |
534 | # Log available tools for debugging
535 | logger.info(f'MCP server "{server_name}": {len(langchain_tools)} '
536 | f"tool(s) available:")
537 | for tool in langchain_tools:
538 | logger.info(f"- {tool.name}")
539 | except Exception as e:
540 | logger.error(f'Error getting MCP tools: "{server_name}/{tool.name}": {str(e)}')
541 | raise
542 |
543 | return langchain_tools
544 |
545 |
546 | # Type hint for cleanup function
547 | McpServerCleanupFn = Callable[[], Awaitable[None]]
548 | """Type for the async cleanup function returned by convert_mcp_to_langchain_tools.
549 |
550 | This function encapsulates the cleanup of all MCP server connections managed by
551 | the AsyncExitStack. When called, it properly closes all transport connections,
552 | sessions, and resources in the correct order.
553 |
554 | Important: Always call this function when you're done using the tools to prevent
555 | resource leaks and ensure graceful shutdown of MCP server connections.
556 |
557 | Example usage:
558 | tools, cleanup = await convert_mcp_to_langchain_tools(server_configs)
559 | try:
560 | # Use tools with your LangChain application...
561 | result = await tools[0].arun(param="value")
562 | finally:
563 | # Always cleanup, even if exceptions occur
564 | await cleanup()
565 | """
566 |
567 |
568 | class ColorFormatter(logging.Formatter):
569 | COLORS = {
570 | 'DEBUG': '\x1b[90m', # Gray
571 | 'INFO': '\x1b[90m', # Gray
572 | 'WARNING': '\x1b[93m', # Yellow
573 | 'ERROR': '\x1b[91m', # Red
574 | 'CRITICAL': '\x1b[1;101m' # Red background, Bold text
575 | }
576 | RESET = '\x1b[0m'
577 |
578 | def format(self, record):
579 | levelname_color = self.COLORS.get(record.levelname, '')
580 | record.levelname = f"{levelname_color}[{record.levelname}]{self.RESET}"
581 | return super().format(record)
582 |
583 |
584 | def _init_logger(log_level=logging.INFO) -> logging.Logger:
585 | """Creates a simple pre-configured logger.
586 |
587 | Returns:
588 | A configured Logger instance
589 | """
590 | handler = logging.StreamHandler()
591 | handler.setFormatter(ColorFormatter("%(levelname)s %(message)s"))
592 |
593 | logger = logging.getLogger()
594 | logger.setLevel(log_level)
595 | logger.handlers = [] # Clear existing handlers
596 | logger.addHandler(handler)
597 |
598 | return logger
599 |
600 |
601 | async def convert_mcp_to_langchain_tools(
602 | server_configs: McpServersConfig,
603 | logger: logging.Logger | int | None = None
604 | ) -> tuple[list[BaseTool], McpServerCleanupFn]:
605 | """Initialize multiple MCP servers and convert their tools to LangChain format.
606 |
607 | This is the main entry point for the library. It orchestrates the complete
608 | lifecycle of multiple MCP server connections, from initialization through
609 | tool conversion to cleanup. Provides robust error handling and authentication
610 | pre-validation to prevent common MCP client library issues.
611 |
612 | Key Features:
613 | - Parallel initialization of multiple servers for efficiency
614 | - Authentication pre-validation for HTTP servers to prevent async generator bugs
615 | - Automatic transport selection and fallback per MCP specification
616 | - Comprehensive error handling with McpInitializationError
617 | - User-controlled cleanup via returned async function
618 | - Support for both local (stdio) and remote (HTTP/WebSocket) servers
619 |
620 | Transport Support:
621 | - stdio: Local command-based servers (npx, uvx, python, etc.)
622 | - streamable_http: Modern HTTP servers (recommended, tried first)
623 | - sse: Legacy Server-Sent Events HTTP servers (fallback)
624 | - websocket: WebSocket servers for real-time communication
625 |
626 | Error Handling:
627 | All configuration and connection errors are wrapped in McpInitializationError
628 | with server context for easy debugging. Authentication failures are detected
629 | early to prevent async generator cleanup issues in the MCP client library.
630 |
631 | Args:
632 | server_configs: Dictionary mapping server names to configurations.
633 | Each config can be either McpServerCommandBasedConfig for local
634 | servers or McpServerUrlBasedConfig for remote servers.
635 | logger: Optional logger instance. If None, creates a pre-configured
636 | logger with appropriate levels for MCP debugging.
637 | If a logging level (e.g., `logging.DEBUG`), the pre-configured
638 | logger will be initialized with that level.
639 |
640 | Returns:
641 | A tuple containing:
642 | - List[BaseTool]: All tools from all servers, ready for LangChain use
643 | - McpServerCleanupFn: Async function to properly shutdown all connections
644 |
645 | Raises:
646 | McpInitializationError: If any server fails to initialize with detailed context
647 |
648 | Example:
649 | server_configs = {
650 | "local-filesystem": {
651 | "command": "npx",
652 | "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
653 | },
654 | "remote-api": {
655 | "url": "https://api.example.com/mcp",
656 | "headers": {"Authorization": "Bearer your-token"},
657 | "timeout": 30.0
658 | }
659 | }
660 |
661 | try:
662 | tools, cleanup = await convert_mcp_to_langchain_tools(server_configs)
663 |
664 | # Use tools with your LangChain application
665 | for tool in tools:
666 | result = await tool.arun(**tool_args)
667 |
668 | except McpInitializationError as e:
669 | print(f"Failed to initialize MCP server '{e.server_name}': {e}")
670 |
671 | finally:
672 | # Always cleanup when done
673 | await cleanup()
674 | """
675 |
676 | if logger is None:
677 | logger = logging.getLogger(__name__)
678 | # Check if the root logger has handlers configured
679 | if not logging.root.handlers and not logger.handlers:
680 | # No logging configured, use a simple pre-configured logger
681 | logger = _init_logger()
682 | elif isinstance(logger, int):
683 | # logger is actually a level like logging.DEBUG
684 | logger = _init_logger(log_level=logger)
685 | elif isinstance(logger, logging.Logger):
686 | # already a logger, use as is
687 | pass
688 | else:
689 | raise TypeError(
690 | "logger must be a logging.Logger, int (log level), or None"
691 | )
692 |
693 | # Initialize AsyncExitStack for managing multiple server lifecycles
694 | transports: list[Transport] = []
695 | async_exit_stack = AsyncExitStack()
696 |
697 | # Initialize all MCP servers concurrently
698 | for server_name, server_config in server_configs.items():
699 | # NOTE for stdio MCP servers:
700 | # the following `await` only blocks until the server subprocess
701 | # is spawned, i.e. after returning from the `await`, the spawned
702 | # subprocess starts its initialization independently of (so in
703 | # parallel with) the Python execution of the following lines.
704 | transport = await _connect_to_mcp_server(
705 | server_name,
706 | server_config,
707 | async_exit_stack,
708 | logger
709 | )
710 | transports.append(transport)
711 |
712 | # Convert tools from each server to LangChain format
713 | langchain_tools: list[BaseTool] = []
714 | for (server_name, server_config), transport in zip(
715 | server_configs.items(),
716 | transports,
717 | strict=True
718 | ):
719 | tools = await _get_mcp_server_tools(
720 | server_name,
721 | transport,
722 | async_exit_stack,
723 | logger
724 | )
725 | langchain_tools.extend(tools)
726 |
727 | # Define a cleanup function to properly shut down all servers
728 | async def mcp_cleanup() -> None:
729 | """Closes all server connections and cleans up resources."""
730 | await async_exit_stack.aclose()
731 |
732 | # Log summary of initialized tools
733 | logger.info(f"MCP servers initialized: {len(langchain_tools)} tool(s) "
734 | f"available in total")
735 | for tool in langchain_tools:
736 | logger.debug(f"- {tool.name}")
737 |
738 | return langchain_tools, mcp_cleanup
739 |
--------------------------------------------------------------------------------