MCP To LangChain Tools Conversion Utility / TypeScript

MCP to LangChain Tools Conversion Library / TypeScript

LangChain から Model Context Protocol（MCP） サーバーのツールを利用するための、シンプルで軽量なライブラリです。

プロジェクトのステータス

このライブラリは現在、MCP プロトコルバージョン 2025-03-26 をサポートしています。 MCP の 2026-07-28 仕様はサポートしていません。

新しいプロジェクトでは、LangChain の包括的な MCP 統合を提供する LangChain 公式の LangChain.js MCP Adapters ライブラリ の使用をおすすめします。

このプロジェクトは現在、メンテナンス／休止状態です。既存のユーザーは、2025-03-26 仕様に対応する MCP サーバーで引き続き使用できますが、新しい MCP プロトコル機能が積極的に実装されることはありません。

はじめに

LangChain から Model Context Protocol（MCP） サーバーのツールを利用するための、シンプルで軽量なライブラリです。

シンプルさに加え、LLM との互換性を高めるツールスキーマの調整やツール呼び出しのログ記録などの追加機能も備えているため、実験やカスタマイズの基盤として便利です。ただし、ツール呼び出しのテキスト結果のみをサポートしており、Tools 以外の MCP 機能はサポートしていません。

LangChain との包括的な統合をサポートする LangChain の公式 LangChain.js MCP Adaptersライブラリ がリリースされました。新しいプロジェクトでは、LangChain の MCP 統合方法としてこちらをおすすめします。

前提条件

• Node.js 18+
• Node.js パッケージベースのローカル MCP サーバーを実行する場合は[任意] npm 7+（npx）
• Python ベースのローカル（stdio）MCP サーバーを実行する場合は、uv（uvx）をインストールします[任意]

インストール

npm i @h1deya/langchain-mcp-tools

クイックスタート

convertMcpToLangchainTools() ユーティリティ関数は、 Claude for Desktopと同じ構造に従うMCPサーバー設定を受け取りますが、 mcpServers プロパティの内容のみを対象とし、 次のようにJSオブジェクトで表現します。

const mcpServers: McpServersConfig = {
  filesystem: {
    command: 'npx',
    args: ['-y', '@modelcontextprotocol/server-filesystem', '.'],
  },
  fetch: {
    command: 'uvx',
    args: ['mcp-server-fetch'],
  },
  'brave-search': {
    command: 'npx',
    args: ['-y', '@modelcontextprotocol/server-brave-search'],
    env: { BRAVE_API_KEY: process.env.BRAVE_API_KEY || '' },
  },
  github: {
    type: 'http',
    url: 'https://api.githubcopilot.com/mcp/',
    headers: {
      Authorization: `Bearer ${process.env.GITHUB_PERSONAL_ACCESS_TOKEN}`,
    },
  },
  notion: {
    // For MCP servers that require OAuth, consider using "mcp-remote"
    command: 'npx',
    args: ['-y', 'mcp-remote', 'https://mcp.notion.com/mcp'],
  },
}

const { tools, cleanup } = await convertMcpToLangchainTools(mcpServers, {
  // Perform provider-specific JSON schema transformations to prevent schema compatibility issues
  llmProvider: 'google_gemini',
  // llmProvider: "openai"
  // llmProvider: "anthropic"  // no transformations
  // llmProvider: "xai"  // no transformations
  // llmProvider: "none"  // for others (default)
})

このユーティリティ関数は、指定されたすべてのMCPサーバーを並列に初期化し、 サーバーから利用可能なMCPツールを収集してLangChainツールでラップすることで、 LangChainツール （tools: StructuredTool[]） を返します。

llmProvider オプションが指定されている場合、スキーマの互換性に関する問題を防ぐため、 MCPツールに対してLLMプロバイダー固有のスキーマ変換を行います。 実行時にスキーマ関連の警告やエラーが発生した場合は、このオプションを設定してください。
詳細は以下をご覧ください。

また、完了時にすべてのMCPサーバーセッションを閉じるために呼び出す非同期コールバック関数（cleanup: McpServerCleanupFn）も返します。

返されたツールは、次のようにLangChainで使用できます。

// import { ChatGoogleGenerativeAI } from "@langchain/google-genai";
const model = new ChatGoogleGenerativeAI({ model: 'gemini-2.5-flash' })

// import { createAgent } from "langchain";
const agent = createAgent({
  model,
  tools,
})

返された cleanup 関数は、リソースのクリーンアップを適切に処理します。

• すべてのMCPサーバー接続を並行して閉じ、クリーンアップの失敗をログに記録します
• 一部のサーバーで失敗しても、残りのサーバーのクリーンアップを続行します
• ツールの使用が終わったら、必ず呼び出してください

通常はfinallyブロック内で呼び出します。

let mcpCleanup: McpServerCleanupFn | undefined

try {
  const { tools, cleanup } = await convertMcpToLangchainTools(mcpServers)
  mcpCleanup = cleanup
  // Use tools with your LLM
} finally {
  // Always cleanup, even if errors occur
  await mcpCleanup?.()
}

動作する簡単な使用例は、langchain-mcp-tools-ts-usageリポジトリのこちらの例で確認できます。

MCPサーバーとの連携を実際に試すには、このライブラリで構築されたMCP Client CLIツールをお試しください。

このユーティリティと同等のPython版はこちらから利用できます。

APIリファレンス

こちらで確認できます。

変更履歴

こちらで確認できます。

動作する使用例

langchain-mcp-tools-ts-usageリポジトリのこちらの例で確認できます。

ソースからのビルド

詳細はREADME_DEV.mdをご覧ください。

はじめに

このパッケージは、LangChain／TypeScriptでModel Context Protocol (MCP)サーバーツールを簡単に使用できるようにすることを目的としています。

Model Context Protocol (MCP)は、DB、クラウドストレージ、GitHub、Docker、Slackなどの外部ツールやリソースとの連携を可能にし、LLMの適用範囲を大幅に広げる、事実上の業界標準です。 すでに多くの便利なMCPサーバーが利用できます。
公式サイトのMCPサーバー一覧をご覧ください。

このユーティリティの目的は、これらの多数のMCPサーバーをLangChainから簡単に利用できるようにすることです。
このパッケージには、ユーティリティ関数 convertMcpToLangchainTools() が含まれています。
この非同期関数は、指定された複数のMCPサーバーを並列に初期化し、利用可能なツールをLangChain互換のツールの配列に変換します。 また、スキーマの互換性に関する問題を防ぐために、LLMプロバイダー固有のスキーマ変換も行います。

このライブラリの使用方法について詳しくは、次のドキュメントをご覧ください。 「LangChainを強化する：2000以上のMCPをReActに統合」。

MCP プロトコルのサポート

このライブラリはMCP プロトコルバージョン 2025-03-26をサポートし、バージョン 2024-11-05 との後方互換性を維持しています。 トランスポートの選択と後方互換性については、公式 MCP 仕様に従っています。

このライブラリは、MCP の2026-07-28仕様をサポートしていません。 2026-07-28 の更新では、MCP クライアントの動作と TypeScript SDK の統合に大幅な変更が必要ですが、 このプロジェクトではこれらの新しいプロトコル機能を積極的に追跡していません。

LangChain で新しい MCP 統合を行う場合は、 LangChain の公式 LangChain.js MCP アダプターライブラリを使用してください。

制限事項

• ツールの戻り値の型：現在、ツール呼び出しのテキスト結果のみをサポートしています。 このライブラリは LangChain の response_format: 'content'（デフォルト）を使用しており、テキスト文字列のみをサポートします。 MCP ツールは複数のコンテンツタイプ（テキスト、画像など）を返せますが、このライブラリは現在、テキストコンテンツのみをフィルタリングして使用します。
• MCP の機能：MCP のツールのみをサポートしています。リソース、プロンプト、サンプリングなど、その他の MCP 機能は実装されていません。

注記

• LLM との互換性とスキーマ変換：このライブラリは、LLM との互換性を確保するためにスキーマ変換を実行できます。 詳細については以下をご覧ください。
• PATH 環境変数の受け渡し：サーバーが必要な実行ファイルを見つけられるように、明示的に指定されていない場合、このライブラリはローカルサーバーの設定に PATH 環境変数を自動的に追加します。

機能

ローカル MCP サーバーの環境変数設定

環境変数を使って API キーやその他の設定をローカル MCP サーバーに渡す必要がある場合は、 次の例を参考にしてください。

  brave: {
    command: "npx",
    args: [ "-y", "@modelcontextprotocol/server-brave-search"],
    env: { "BRAVE_API_KEY": process.env.BRAVE_API_KEY || "" }
  },

注記：サーバーが必要な実行ファイルを見つけられるように、明示的に指定されていない場合、このライブラリはローカルサーバーの設定に PATH 環境変数を自動的に追加します。

ローカル MCP サーバーの stderr リダイレクト

ローカル MCP サーバーの stderr をリダイレクトするファイルディスクリプターを指定するために、新しいキー "stderr" が導入されました。

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

使用例はこちらにあります。
キー名 stderr は TypeScript SDK のStdioServerParametersに由来します。

ローカル MCP サーバーの作業ディレクトリ設定

ローカル MCP サーバーの起動時に使用する作業ディレクトリは、 次のように "cwd" キーで指定できます。

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

キー名 cwd は TypeScript SDK のStdioServerParametersに由来します。

トランスポートの選択優先順位

このライブラリは、次の優先順位でトランスポートを選択します。

1. 明示的な transport/type フィールド（URL が指定されている場合は、URL のプロトコルと一致している必要があります）
2. URL プロトコルの自動検出（http/https → StreamableHTTP → SSE、ws/wss → WebSocket）
3. コマンドの存在 → Stdio トランスポート（ローカル MCP サーバー）
4. 上記のいずれにも該当しない場合はエラー

これにより、さまざまなデプロイシナリオに柔軟に対応しながら、予測可能な動作を実現します。
**注記：**SSE トランスポートはプロトコルバージョン 2025-03-26 で非推奨になりました。Streamable HTTP の使用が推奨されています。

リモート MCP サーバーのサポート

Streamable HTTP、SSE、WebSocket サーバーの mcp_servers 設定は次のとおりです。

    // 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 (Note: SSE transport is deprecated)
    "sse-server-name": {
        url: `http://${sse_server_host}:${sse_server_port}/...`,
        transport: "sse"  // or `type: "sse"`
    },

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

"headers" キーを使用すると、Streamable HTTP および SSE の接続に HTTP ヘッダーを渡せます。
streamableHTTPOptions または sseOptions のいずれかが指定されている場合、このヘッダー設定は上書きされます（詳細は以下を参照）。

    github: {
      // To avoid auto protocol fallback, specify the protocol explicitly when using authentication
      type: "http",  // or `transport: "http",`
      url: "https://api.githubcopilot.com/mcp/",
      headers: {
        "Authorization": `Bearer ${process.env.GITHUB_PERSONAL_ACCESS_TOKEN}`
      }
    },

自動検出の動作（デフォルト）：

• transport を明示せずに HTTP/HTTPS URL を指定すると、ライブラリはMCP 仕様の推奨事項に従います
• 最初に Streamable HTTP トランスポートを試みます
• Streamable HTTP が 4xx エラーで失敗した場合、自動的に SSE トランスポートにフォールバックします
• 4xx 以外のエラー（ネットワークの問題など）は、フォールバックせずに再スローされます

トランスポートの明示的な選択：

• Streamable HTTP を強制するには、transport: "streamable_http"（または VSCode 形式の設定 type: "http"）を指定します（フォールバックなし）
• SSE トランスポートを強制するには、transport: "sse" を指定します（SSE トランスポートは非推奨です）
• WebSocket URL（ws:// または wss://）では、常に WebSocket トランスポートが使用されます

Streamable HTTP は、以前の HTTP+SSE トランスポートに代わる最新の MCP トランスポートです。MCP 公式ドキュメントによると、「SSE 単独のトランスポートは、プロトコルバージョン 2025-03-26 で非推奨になりました。SSE をオプションのストリーミング方式として取り込んだ Streamable HTTP に置き換えられています。」

OAuth が必要なリモート MCP サーバーに手早くアクセスする

OAuth が必要な MCP サーバーを使用する場合は、**「mcp-remote」**の利用をご検討ください。

    notion: {
      command: "npx",
      args: ["-y", "mcp-remote", "https://mcp.notion.com/mcp"],
    },

Streamable HTTP 接続の認証サポート

このライブラリは、Streamable HTTP 接続での OAuth 2.1 認証をサポートしています。

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',
    // To avoid auto protocol fallback, specify the protocol explicitly when using authentication
    transport: 'streamable_http', // or `type: "http",`
    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,
      },
    },
  },
}

テスト用の実装も用意されています。

• Streamable HTTP 認証テスト：
  • このライブラリを使用する MCP クライアント：streamable-http-auth-test-client.ts
  • テスト用 MCP サーバー：streamable-http-auth-test-server.ts

付録

トラブルシューティング

1. デバッグログを有効にする：logLevel: "debug" を設定すると、接続と実行の詳細なログを確認できます
2. サーバーの標準エラー出力を確認する：ローカル MCP サーバーでは、stderr リダイレクトを使用してサーバーのエラー出力を取得します
3. トランスポートを明示的にテストする：特定のトランスポートタイプを強制し、自動検出の問題を切り分けます
4. サーバーを個別に検証する：MCP ドキュメントのデバッグセクションを参照してください

認証のデバッグ

1. トークン／認証情報を確認する — 認証の失敗の大半は、トークンの期限切れまたは誤りが原因です

2. トークンの権限を確認する — 一部の MCP サーバーでは、特定のスコープ（GitHub Copilot ライセンスなど）が必要です

3. curl でテストする — 簡単な HTTP リクエストを試して、認証設定を確認します：

   curl -H "Authorization: Bearer your-token" https://api.example.com/mcp/
   

LLM プロバイダーのスキーマ互換性

LLM プロバイダーによって、関数呼び出しに必要な JSON Schema の要件は異なります。

• OpenAI の要件：関数呼び出しでは、オプションのフィールドを nullable にする必要があります（.optional() + .nullable()） （Structured Outputs API の要件に基づいており、 今後の SDK バージョンで厳格に適用される予定です）
• Google Gemini API：nullable フィールドと $defs 参照を拒否し、OpenAPI 3.0 の厳密なサブセットへの準拠を要求します
• Anthropic Claude と xAI Grok：スキーマ要件は非常に緩やかで、文書化された制約はありません

注：Google Vertex AI は、より緩やかな要件に対応する OpenAI 互換エンドポイントを提供しています。

実環境での影響

これにより、開発者がプロバイダー間で共通のスキーマを作成しようとする際に課題が生じます。

一部の MCP サーバーは、すべてのプロバイダーの要件を満たさないスキーマを生成します。
たとえば、公式の Notion ローカル MCP サーバー @notionhq/notion-mcp-server（バージョン 1.9.0）とリモートサーバー（「https://mcp.notion.com/mcp」、mcp-remote 0.1.18）は、次の内容を生成します。

OpenAI の警告：

Zod field at `#/definitions/read_file/properties/tail` uses `.optional()` without `.nullable()` which is not supported by the API. See: https://platform.openai.com/docs/guides/structured-outputs?api-mode=responses#all-fields-must-be-required
... followed by many more

Gemini のエラー：

[GoogleGenerativeAI Error]: Error fetching from https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent: [400 Bad Request] Invalid JSON payload received. Unknown name "exclusiveMaximum" at 'tools[0].function_declarations[14].parameters.properties[1].value': Cannot find field.
... followed by many more

解決策

プロバイダー固有の JSON スキーマ変換を実行するため、新しいオプション llmProvider が導入されました。

const { tools, cleanup } = await convertMcpToLangchainTools(mcpServers, {
  llmProvider: 'openai', // Makes optional fields nullable
  // llmProvider: "google_gemini" // Applies Gemini's strict validation rules
  // llmProvider: "anthropic"     // No transformations needed
})

機能：

• 変換が適用されると、INFO レベルのログを生成します
• MCP サーバーのスキーマを改善できる可能性がある箇所をユーザーが特定するのに役立ちます
• llmProvider が指定されていない場合は、元のスキーマにフォールバックします

プロバイダー固有の変換

プロバイダー	適用される変換
openai	オプションのフィールドを nullable にし、ユニオン型を処理します
google_gemini または google_genai	無効な必須フィールドを除外し、anyOf のバリアントを修正し、サポートされていない機能を削除します
anthropic および xai	変換は行いませんが、スキーマを若干効率的に処理します

その他のプロバイダーでは、オプションを指定せずにお試しください。

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

参考資料

• OpenAI の Function Calling
• Gemini API のスキーマ要件
• Anthropic の Tool Use

デバッグとログ

このライブラリでは、接続やツール実行に関する問題のデバッグに役立つ、設定可能なログ機能を提供しています。

// Configure log level
const { tools, cleanup } = await convertMcpToLangchainTools(mcpServers, {
  logLevel: 'debug',
})

// Use custom logger
class MyLogger implements McpToolsLogger {
  debug(...args: unknown[]) {
    console.log('[DEBUG]', ...args)
  }
  info(...args: unknown[]) {
    console.log('[INFO]', ...args)
  }
  warn(...args: unknown[]) {
    console.warn('[WARN]', ...args)
  }
  error(...args: unknown[]) {
    console.error('[ERROR]', ...args)
  }
}

const { tools, cleanup } = await convertMcpToLangchainTools(mcpServers, {
  logger: new MyLogger(),
})

使用可能なログレベル："fatal" | "error" | "warn" | "info" | "debug" | "trace"

開発者向け

開発とテストの詳細については、README_DEV.mdを参照してください。

ライセンス

MIT ライセンスです。詳細はLICENSEファイルを参照してください。

コントリビューション

Issueと プルリクエストを歓迎します！
特に、LangChain と LLM モデルの最新バージョン、および特定の MCP サーバーに関する問題をぜひ共有してください。