feat(langchain): Add MCP Middleware for Efficient Model Context Protocol Integration

[christian-bromann]

This PR introduces a new middleware that enables LangChain.js agents to interact with MCP (Model Context Protocol) servers through a virtual file system interface. Instead of loading all tool definitions upfront, agents can progressively discover and use only the MCP tools they need, significantly reducing token usage and improving efficiency.

Key Features

• Virtual File System: MCP tools are presented as TypeScript files in a virtual file system, allowing agents to explore and load tools on-demand
• Progressive Disclosure: Agents only load tool definitions they actually need, reducing context size
• Code Execution Interface: Agents write code to interact with MCP tools, enabling better control flow, filtering, and data transformation
• Optional Dependency: Uses @langchain/mcp-adapters as an optional dependency, loaded dynamically at runtime
• Proper Cleanup: Automatically closes MCP client connections when agent execution completes (important for serverless environments like Next.js)

How It Works

The middleware provides three tools to agents:

1. mcp_list_directory: Browse the virtual file system to discover available MCP servers and tools
2. mcp_read_file: Read specific tool definition files when needed
3. execute_mcp_code: Execute code that calls MCP tools, with tool calls specified as an array

The middleware automatically:

• Connects to configured MCP servers on agent initialization
• Generates TypeScript tool definitions and stores them in a memory-based file system
• Injects a system prompt guiding the agent on how to use the virtual file system
• Manages MCP client lifecycle and ensures proper cleanup via afterAgent hook

Benefits

• Reduced Token Usage: Only load tool definitions that are actually used
• Better Context Efficiency: Filter and transform data in code before returning results
• Improved Control Flow: Use familiar code patterns (loops, conditionals, error handling)
• Privacy: Intermediate results stay in the execution environment by default

Usage Example

import { mcpMiddleware } from "langchain/agents/middleware";
import { createAgent } from "langchain/agents";

const middleware = mcpMiddleware({
  mcpConfig: {
    mcpServers: {
      "google-drive": {
        transport: "stdio",
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-google-drive"],
      },
    },
  },
});

const agent = createAgent({
  model: "openai:gpt-4o",
  middleware: [middleware],
});

Technical Details

• Uses a module-level Map to track MCP client instances for proper cleanup
• Implements robust path normalization and resolution for the virtual file system
• Handles tool name prefixing and mapping between server names and tool names
• Reuses client instances across tool invocations for efficiency
• Gracefully handles errors during initialization and cleanup

[changeset-bot]

⚠️ No Changeset found

Latest commit: fda9c57

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR