Skip to content

hideya/langchain-mcp-tools-ts

BranchesTags

Repository files navigation

MCP To LangChain Tools Conversion Utility / TypeScript License: MIT npm version

This is a simple, lightweight library intended to simplify the use of Model Context Protocol (MCP) server tools with LangChain.

Its simplicity and extra features for stdio MCP servers can make it useful as a basis for your own customizations. However, it only supports text results of tool calls and does not support MCP features other than tools.

LangChain's official LangChain.js MCP Adapters library, which supports comprehensive integration with LangChain, has been released at:

You may want to consider using the above if you don't have specific needs for this library.

Introduction

This package is intended to simplify the use of Model Context Protocol (MCP) server tools with LangChain / TypeScript.

Model Context Protocol (MCP) is the de facto industry standard that dramatically expands the scope of LLMs by enabling the integration of external tools and resources, including DBs, GitHub, Google Drive, Docker, Slack, Notion, Spotify, and more.

There are quite a few useful MCP servers already available:

This utility's goal is to make these massive numbers of MCP servers easily accessible from LangChain.

It contains a utility function convertMcpToLangchainTools().
This async function handles parallel initialization of specified multiple MCP servers and converts their available tools into an array of LangChain-compatible tools.

For detailed information on how to use this library, please refer to the following document:

A python equivalent of this utility is available here

Prerequisites

  • Node.js 16+

Installation

npm i @h1deya/langchain-mcp-tools

API docs

Can be found here

Quick Start

A minimal but complete working usage example can be found in this example in the langchain-mcp-tools-ts-usage repo

convertMcpToLangchainTools() utility function accepts MCP server configurations that follow the same structure as Claude for Desktop, but only the contents of the mcpServers property, and is expressed as a JS Object, e.g.:

const mcpServers: McpServersConfig = {
  filesystem: {
    command: "npx",
    args: ["-y", "@modelcontextprotocol/server-filesystem", "."]
  },
  fetch: {
    command: "uvx",
    args: ["mcp-server-fetch"]
  }
};

const { tools, cleanup } = await convertMcpToLangchainTools(mcpServers);

This utility function initializes all specified MCP servers in parallel, and returns LangChain Tools (tools: StructuredTool[]) by gathering available MCP tools from the servers, and by wrapping them into LangChain tools. It also returns an async callback function (cleanup: McpServerCleanupFn) to be invoked to close all MCP server sessions when finished.

The returned tools can be used with LangChain, e.g.:

// import { ChatAnthropic } from "@langchain/anthropic";
const llm = new ChatAnthropic({ model: "claude-sonnet-4-0" });

// import { createReactAgent } from "@langchain/langgraph/prebuilt";
const agent = createReactAgent({
  llm,
  tools
});

For hands-on experimentation with MCP server integration, try this LangChain application built with the utility

For detailed information on how to use this library, please refer to the following document:
"Supercharging LangChain: Integrating 2000+ MCP with ReAct"

Features

stderr Redirection for Local MCP Server

A new key "stderr" has been introduced to specify a file descriptor to which local (stdio) MCP server's stderr is redirected.
The key name stderr is derived from TypeScript SDK's StdioServerParameters.

    const logPath = `mcp-server-${serverName}.log`;
    const logFd = fs.openSync(logPath, "w");
    mcpServers[serverName].stderr = logFd;

A usage example can be found here

Working Directory Configuration for Local MCP Servers

The working directory that is used when spawning a local (stdio) MCP server can be specified with the "cwd" key as follows:

    "local-server-name": {
      command: "...",
      args: [...],
      cwd: "/working/directory"  // the working dir to be use by the server
    },

The key name cwd is derived from TypeScript SDK's StdioServerParameters.

Remote MCP Server Support

mcp_servers configuration for Streamable HTTP, SSE and Websocket servers are as follows:

    // Auto-detection: tries Streamable HTTP first, falls back to SSE on 4xx errors
    "auto-detect-server": {
        url: `http://${server_host}:${server_port}/...`
    },

    // Explicit Streamable HTTP
    "streamable-http-server": {
        url: `http://${server_host}:${server_port}/...`,
        transport: "streamable_http"
        // type: "http"  // VSCode-style config also works instead of the above
    },

    // Explicit SSE
    "sse-server-name": {
        url: `http://${sse_server_host}:${sse_server_port}/...`,
        transport: "sse"
    },

    // WebSocket
    "ws-server-name": {
        url: `ws://${ws_server_host}:${ws_server_port}/...`
    },

For the convenience of adding authorization headers, the following shorthand expression is supported. This header configuration will be overridden if either streamableHTTPOptions or sseOptions is specified.

    github: {
      type: "http",  // recommended to specify the protocol explicitly when authentication is used
      url: "https://api.githubcopilot.com/mcp/",
      headers: {
        "Authorization": `Bearer ${process.env.GITHUB_PERSONAL_ACCESS_TOKEN}`
      }
    },

NOTE: When accessing the GitHub MCP server, GitHub PAT (Personal Access Token) alone is not enough; your GitHub account must have an active Copilot subscription or be assigned a Copilot license through your organization.

Auto-detection behavior (default):

  • For HTTP/HTTPS URLs without explicit transport, the library follows MCP specification recommendations
  • First attempts Streamable HTTP transport
  • If Streamable HTTP fails with a 4xx error, automatically falls back to SSE transport
  • Non-4xx errors (network issues, etc.) are re-thrown without fallback

Explicit transport selection:

  • Set transport: "streamable_http" to force Streamable HTTP (no fallback)
  • VSCode-style config type: "http" also works instead of the above
  • Set transport: "sse" to force SSE transport
  • WebSocket URLs (ws:// or wss://) always use WebSocket transport

Streamable HTTP is the modern MCP transport that replaces the older HTTP+SSE transport. According to the official MCP documentation:

"SSE as a standalone transport is deprecated as of protocol version 2024-11-05. It has been replaced by Streamable HTTP, which incorporates SSE as an optional streaming mechanism."

Note that even when you specify the Streamable HTTP transport, you may see SSE activity in the logs, such as Accept: text/event-stream. This occurs when the MCP SDK chooses to use SSE for streaming server responses within the Streamable HTTP transport.

Authentication Support for Streamable HTTP Connections

The library supports OAuth 2.1 authentication for Streamable HTTP connections:

import { OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth.js';

// Implement your own OAuth client provider
class MyOAuthProvider implements OAuthClientProvider {
  // Implementation details...
}

const mcpServers = {
  "secure-streamable-server": {
    url: "https://secure-mcp-server.example.com/mcp",
    transport: "streamable_http",  // Optional: explicit transport
    streamableHTTPOptions: {
      // Provide an OAuth client provider
      authProvider: new MyOAuthProvider(),
      
      // Optionally customize HTTP requests
      requestInit: {
        headers: {
          'X-Custom-Header': 'custom-value'
        }
      },
      
      // Optionally configure reconnection behavior
      reconnectionOptions: {
        maxReconnectAttempts: 5,
        reconnectDelay: 1000
      }
    }
  }
};

Test implementations are provided:

Authentication Support for SSE Connections (Legacy)

The library also supports authentication for SSE connections to MCP servers. Note that SSE transport is deprecated; Streamable HTTP is the recommended approach.

To enable authentication, provide SSE options in your server configuration:

import { OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth.js';

// Implement your own OAuth client provider
class MyOAuthProvider implements OAuthClientProvider {
  // Implementation details...
}

const mcpServers = {
  "secure-server": {
    url: "https://secure-mcp-server.example.com",
    sseOptions: {
      // Provide an OAuth client provider
      authProvider: new MyOAuthProvider(),
      
      // Optionally customize the initial SSE request
      eventSourceInit: {
        // Custom options
      },
      
      // Optionally customize recurring POST requests
      requestInit: {
        headers: {
          'X-Custom-Header': 'custom-value'
        }
      }
    }
  }
};

Test implementations are provided:

Limitations

  • Currently, only text results of tool calls are supported.
  • MCP features other than Tools are not supported.

Change Log

Can be found here

About

MCP To LangChain Tools Conversion Utility / TypeScript

www.npmjs.com/package/@h1deya/langchain-mcp-tools

Topics

nodejs typescript mcp npm-package langchain langchain-typescript tool-calling modelcontextprotocol mcp-client

Resources

Readme

License

MIT license
Activity

Stars

21 stars

Watchers

3 watching

Forks

6 forks
Report repository

Languages