# langchain-ai/langchainjs-mcp-adapters architecture

> Architecture diagram of the GitHub repository langchain-ai/langchainjs-mcp-adapters, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/langchain-ai/langchainjs-mcp-adapters
- Repository: https://github.com/langchain-ai/langchainjs-mcp-adapters

## Overview

##### Project Type and Purpose
- This project is a Node.js/TypeScript library that serves as an adapter for the Anthropic Model Context Protocol (MCP) tools. It makes MCP servers (which can run locally via stdio or remotely via SSE) compatible with LangChain.js and LangGraph.js.
- The library is focused on providing multi-server management, tool loading, and robust transport connections while integrating with LLM agent workflows.

##### Key Components and Their Roles
A. Client/Adapter Layer:
- Core modules found in the src directory (client.ts, index.ts, tools.ts) implement the client logic to connect with MCP servers.
- The MultiServerMCPClient (as seen in the README examples) wraps connections to one or multiple MCP servers.
B. Transport Layer:
- There are two main transport options:
– Stdio Transport: For local connections (e.g., launching Python MCP servers like math_server.py).
– SSE (Server-Sent Events) Transport: For remote MCP server connections. The transport options also include configuration for headers and reconnection strategies.
- The client connects to these transports using commands and configurations specified either in code or via external JSON configuration files (e.g., mcp.json).
C. Configuration Management:
- The library supports multiple ways of specifying configuration – via mcp.json, additional configuration files, and direct method calls (e.g., addConfigFromFile(), addConnections()).
- This configuration module merges multiple sources and resolves conflicts based on ordering.
D. Integration with External Agents:
- The adapter is built to integrate with agents from LangChain.js or LangGraph.js, as demonstrated by creating an agent with createReactAgent.
- The loaded MCP tools become a set of operations that the LangChain agent can invoke.
E. Tests and Examples:
- The __tests__ folder and examples directory provide validation of the component behaviors and usage scenarios (e.g., math server examples, weather server examples).

##### Relationships and Interactions
- The client component (e.g., MultiServerMCPClient) is at the center of the architecture, orchestrating:
– Connections to one or multiple MCP servers through either stdio or SSE transport mechanisms.
– Loading of MCP tools from these servers.
– Managing and organizing the tools (either as a flattened list or grouped by server).
- The client sends configuration details (command, args, environment variables, reconnection settings) to the underlying transport methods.
- Once the connection is established, the adapter acts as a bridge by exposing functions (tools) that the higher level LangChain/Graph agent can invoke, creating a chain of data flow from the user’s request, through the agent, to the MCP server, and back as a response.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The library neatly separates transport connectivity, configuration management, and agent integration into distinct modules.
- Extensibility and Flexibility: With various configuration loading options and multiple transport strategies, the design allows for easy integration with different MCP servers and tool sources.
- Robustness: Mechanisms like auto-reconnection strategies and error handling (as shown in the README) emphasize a resilient design.

##### Final Recommendations for the Principal Software Engineer
- Component has clear labels and descriptive annotations.
- Stay detailed in capturing all essential interactions—don’t omit the configuration management stage or the multiple transport connections.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration Management Layer
    subgraph "Configuration Management"
        CM1["Configuration (auth_mcp.json)"]:::config
        CM2["Configuration (complex_mcp.json)"]:::config
    end

    %% Client Adapter Layer
    subgraph "Client Adapter"
        CA1["Client Module (src/client.ts)"]:::client
        CA2["Entry Point (src/index.ts)"]:::client
        CA3["Tools Module (src/tools.ts)"]:::client
    end

    %% Transport Layer
    subgraph "Transport Layer"
        T1["Stdio Transport"]:::transport
        T2["SSE Transport"]:::transport
    end

    %% External MCP Servers
    subgraph "External MCP Servers"
        EMS1["Math Server (Local)"]:::server
        EMS2["Weather Server (Remote)"]:::server
    end

    %% Integration with External Agents
    subgraph "Integration with External Agents"
        IA1["LangChain/Graph Agents"]:::agent
    end

    %% Tests and Examples
    subgraph "Tests and Examples"
        TE1["Unit Tests (__tests__)"]:::test
        TE2["Usage Examples (examples)"]:::test
    end

    %% Relationships
    CM1 ---|"configurationInjection"| CA1
    CM2 ---|"configurationInjection"| CA1
    CA1 ---|"initiatesTransport"| T1
    CA1 ---|"initiatesTransport"| T2
    CM1 ---|"configuresTransport"| T1
    CM2 ---|"configuresTransport"| T2
    T1 ---|"establishConnection"| EMS1
    T2 ---|"establishConnection"| EMS2
    EMS1 ---|"toolLoading"| CA1
    EMS2 ---|"toolLoading"| CA1
    CA1 ---|"exposesTools"| IA1
    TE1 ---|"validates"| CA1
    TE2 ---|"demonstratesUsage"| CA1

    %% Click Events for Client Adapter
    click CA1 "https://github.com/langchain-ai/langchainjs-mcp-adapters/blob/main/src/client.ts"
    click CA2 "https://github.com/langchain-ai/langchainjs-mcp-adapters/blob/main/src/index.ts"
    click CA3 "https://github.com/langchain-ai/langchainjs-mcp-adapters/blob/main/src/tools.ts"

    %% Click Events for Configuration Management
    click CM1 "https://github.com/langchain-ai/langchainjs-mcp-adapters/blob/main/examples/auth_mcp.json"
    click CM2 "https://github.com/langchain-ai/langchainjs-mcp-adapters/blob/main/examples/complex_mcp.json"

    %% Click Events for External MCP Servers (Transport Examples)
    click EMS1 "https://github.com/langchain-ai/langchainjs-mcp-adapters/blob/main/examples/math_server.py"
    click EMS2 "https://github.com/langchain-ai/langchainjs-mcp-adapters/blob/main/examples/weather_server.py"

    %% Click Events for Integration with External Agents
    click IA1 "https://github.com/langchain-ai/langchainjs-mcp-adapters/blob/main/examples/config_langgraph_test.ts"
    click IA1 "https://github.com/langchain-ai/langchainjs-mcp-adapters/blob/main/examples/filesystem_langgraph_example.ts"
    click IA1 "https://github.com/langchain-ai/langchainjs-mcp-adapters/blob/main/examples/langgraph_example.ts"

    %% Click Events for Tests and Examples
    click TE1 "https://github.com/langchain-ai/langchainjs-mcp-adapters/tree/main/__tests__"
    click TE2 "https://github.com/langchain-ai/langchainjs-mcp-adapters/tree/main/examples"

    %% Styles
    classDef client fill:#bbdefb,stroke:#0d47a1,stroke-width:2px;
    classDef transport fill:#ffe082,stroke:#ff6f00,stroke-width:2px;
    classDef config fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px;
    classDef server fill:#ffcdd2,stroke:#b71c1c,stroke-width:2px;
    classDef agent fill:#d1c4e9,stroke:#512da8,stroke-width:2px;
    classDef test fill:#f0f4c3,stroke:#afb42b,stroke-width:2px;
```
