LangChain MCP Adapters

Warnings

• gotcha Connecting to multiple MCP servers can lead to high token consumption due to all tool schemas being preloaded into the LLM's system prompt. This 'token overhead' can be significant, especially with many verbose tool definitions.
  Fix: Consider strategies like lazy-loading schemas (if supported by future versions or custom logic), using a gateway for selective loading, or carefully managing the number and verbosity of exposed tools.
• gotcha Each MCP server can have distinct authentication requirements (API keys, OAuth, etc.), leading to 'Auth Fragmentation' and complex credential management across multiple development and production environments.
  Fix: Implement a centralized authentication mechanism, potentially via a gateway that handles credentials for upstream servers, or leverage `authProvider` options in `MultiServerMCPClient` for OAuth 2.0 (new in v0.4.6 of JS version, check Python equivalent).
• gotcha Schema misalignment between MCP tool input/output JSON schemas and LangChain's expectations, or invalid connection configurations for `MultiServerMCPClient`, can lead to `ZodError` or silent failures.
  Fix: Carefully validate MCP tool schemas and `MultiServerMCPClient` configurations, paying close attention to required parameters and expected data types for each transport (e.g., `command` for `stdio`, `url` for `http`/`sse`). Enable verbose logging for debugging.
• gotcha Managing different transport protocols (stdio, HTTP, SSE) and handling connection issues (e.g., server startup delays, unreachable servers) can add complexity to setup and debugging.
  Fix: Utilize `onConnectionError: 'ignore'` for non-critical servers during development. Implement robust error handling and monitoring for production environments. Ensure proper server startup and network connectivity, especially for HTTP/SSE transports.
• gotcha When connecting to multiple MCP servers, tools from different servers might have conflicting names, leading to ambiguity or unexpected behavior if not properly handled.
  Fix: Use the `prefixToolNameWithServerName` option in `MultiServerMCPClient` to automatically add a server-specific prefix to tool names, preventing collisions.

Install

• pip install langchain-mcp-adapters langchain-core Install core library and LangChain dependencies

Imports

• MultiServerMCPClient

  from langchain_mcp_adapters.client import MultiServerMCPClient

• load_mcp_tools

  from langchain_mcp_adapters.tools import load_mcp_tools

• ClientSession

  from mcp import ClientSession

  MCP's ClientSession is directly from the 'mcp' library, not the adapter.
• StdioServerParameters

  from mcp import StdioServerParameters

  MCP's StdioServerParameters is directly from the 'mcp' library, not the adapter.

Quickstart

This quickstart demonstrates how to set up `MultiServerMCPClient` to connect to multiple (mock) MCP servers and use their tools with a LangChain agent. It shows configuration for both `stdio` (local subprocess) and `http` transports. Remember to replace `/path/to/your/math_server.py` with an actual path to a running MCP math server and ensure your API keys for the chosen LLM are set as environment variables.

import os
import asyncio
from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain.agents import create_agent
from langchain_core.messages import HumanMessage

# NOTE: For this example to be runnable, you need a running MCP server.
# For a 'math' server, you could use fastmcp:
# # math_server.py
# from fastmcp import FastMCP
# mcp = FastMCP("Math")
# @mcp.tool()
# def add(a: int, b: int) -> int:
#     """Add two numbers"""
#     return a + b
# if __name__ == "__main__":
#     mcp.run(transport="stdio")

# And start it from your terminal: python /path/to/math_server.py

async def main():
    # Set your LLM API key as an environment variable
    # e.g., export OPENAI_API_KEY="your_key_here"
    # Or, for Anthropic: export ANTHROPIC_API_KEY="your_key_here"
    if not os.environ.get('OPENAI_API_KEY') and not os.environ.get('ANTHROPIC_API_KEY'):
        print("Please set OPENAI_API_KEY or ANTHROPIC_API_KEY environment variable.")
        return

    client = MultiServerMCPClient(
        {
            "math": {
                "transport": "stdio", # Local subprocess communication
                "command": "python", # Path to python interpreter
                "args": ["/path/to/your/math_server.py"], # ABSOLUTE path to your math_server.py
            },
            "weather": {
                "transport": "http", # HTTP-based remote server
                "url": "http://localhost:8000/mcp", # Ensure your weather server is running on port 8000
                "onConnectionError": "ignore" # Ignore if this server is not running for demo
            }
        }
    )

    # Retrieve tools from the connected MCP servers
    tools = await client.get_tools()
    print(f"Loaded {len(tools)} tools.")

    # Example: Create an agent using LangChain's create_agent
    # Choose your LLM. For example, "openai:gpt-4o" or "anthropic:claude-3-opus-20240229"
    agent = create_agent("openai:gpt-4o", tools)

    # Invoke the agent with a message that uses a tool
    print("\nInvoking agent for math query...")
    math_response = await agent.ainvoke(
        {"messages": [HumanMessage(content="what's (3 + 5) x 12?")]}
    )
    print("Math Agent Response:", math_response)

    print("\nInvoking agent for weather query (may fail if server not running)...")
    weather_response = await agent.ainvoke(
        {"messages": [HumanMessage(content="what is the weather in nyc?")]}
    )
    print("Weather Agent Response:", weather_response)

    await client.close() # Important to close client to terminate subprocesses

if __name__ == "__main__":
    asyncio.run(main())