Model Context Protocol (MCP)

使用 MCPAdapter 将 LangChain 智能体连接至 MCP 服务器。

Model Context Protocol (MCP) 是一个开放协议，它规范了应用程序如何向语言模型提供工具和上下文。LangChain 智能体通过 MCPAdapter 调用在 MCP 服务器上定义的工具，该适配器可发现服务器的工具并将其适配为可以直接传递给 createAgent 的 LangChain 工具。

NOTE

本指南需要 @langchain/mcp-adapters 2.0 或更高版本。如果你使用的是 1.x 版本，请参阅 1.x 文档或迁移指南。

安装

安装 @langchain/mcp-adapters 包及其对等依赖项：

npm

npm install @langchain/mcp-adapters@^2.0.0 @langchain/core @langchain/langgraph

pnpm

pnpm add @langchain/mcp-adapters@^2.0.0 @langchain/core @langchain/langgraph

yarn

yarn add @langchain/mcp-adapters@^2.0.0 @langchain/core @langchain/langgraph

bun

bun add @langchain/mcp-adapters@^2.0.0 @langchain/core @langchain/langgraph

如果你导入 SDK 类型或传输层，还需要添加 @modelcontextprotocol/client。

快速入门

将智能体连接至 LangChain 文档 MCP 服务器以搜索文档。该示例需要 langchain、@langchain/anthropic 以及一个 Anthropic API 密钥。有关配置请参阅 LangChain 快速入门。

在智能体运行期间保持适配器处于开启状态，然后在 finally 中将其关闭：

import { MCPAdapter } from "@langchain/mcp-adapters";
import { createAgent } from "langchain";

async function main() {
  const adapter = new MCPAdapter({
    servers: { docs: { url: "https://docs.langchain.com/mcp" } },
  });

  try {
    const tools = await adapter.listTools();
    const agent = createAgent({ model: "claude-sonnet-5", tools });
    const result = await agent.invoke({
      messages: [
        {
          role: "user",
          content: "How do I add short-term memory to a LangChain agent?",
        },
      ],
    });
    console.log(result.messages.at(-1)?.text);
  } finally {
    await adapter.close();
  }
}

await main();

查看示例 Trace

打开此示例的公开 LangSmith 运行记录。

LangChain 文档 MCP 服务器

LangChain 文档 MCP 服务器是一个位于 https://docs.langchain.com/mcp 的公开 HTTP 端点。

将智能体连接到该服务器，无需编写自定义工具即可搜索和阅读文档：

import { MCPAdapter } from "@langchain/mcp-adapters";
import { createAgent } from "langchain";

async function main() {
  const adapter = new MCPAdapter({
    servers: { docs: { url: "https://docs.langchain.com/mcp" } }, 
  });

  try {
    const tools = await adapter.listTools();
    const agent = createAgent({ model: "claude-sonnet-5", tools });
    return await agent.invoke({
      messages: [
        {
          role: "user",
          content: "How do I add short-term memory to a LangChain agent?",
        },
      ],
    });
  } finally {
    await adapter.close();
  }
}

查看示例 Trace

打开此示例的公开 LangSmith 运行记录。

NOTE

文档 MCP 服务器是公开的，不需要 API 密钥。有关 IDE 和代码编写智能体配置（Claude Code、Cursor 等），请参阅以编程方式使用文档。

该服务器公开了以下工具：

工具	描述
search_docs_by_lang_chain	在文档中搜索相关的指南、操作教程和示例。
query_docs_filesystem_docs_by_lang_chain	通过虚拟文件系统阅读或搜索文档（rg、head、cat 及相关命令）。
submit_feedback	报告文档页面的问题。

MCPAdapter 在公开这些工具时会带有服务器名称前缀，例如 docs_search_docs_by_lang_chain。

传输方式

MCPAdapter 接收一个已命名服务器定义的对象映射。它会根据每个定义选择对应的传输方式，因此单个适配器可以同时连接到本地 stdio 服务器和远程 HTTP 服务器：

import { MCPAdapter } from "@langchain/mcp-adapters";

const adapter = new MCPAdapter({
  servers: {
    // 通过 stdio 作为子进程启动的本地服务器。
    local: {
      command: "node",
      args: ["./weather-server.js"],
    },

    // 通过 Streamable HTTP 访问的远程服务器。
    remote: {
      url: "https://example.com/mcp",
    },

    // 带有显式 SSE 端点的遗留服务器。
    legacy: {
      url: "https://legacy.example.com/sse",
      transport: "sse",
      mode: "legacy",
    },
  },
});

try {
  const tools = await adapter.listTools();
  // 将 tools 传递给 createAgent({ tools, ... })。
} finally {
  await adapter.close();
}

查看示例 Trace

打开此示例的公开 LangSmith 运行记录。

每个服务器定义可以使用以下传输方式之一：

• stdio：提供 command 和 args。适配器将该命令作为子进程启动，并通过标准输入和输出进行通信。
• Streamable HTTP：提供 url。这是基于 URL 的服务器的默认传输方式，因此 transport: "http" 是可选的。
• SSE：提供 url 并设置 transport: "sse"。仅对公开了 SSE 端点的遗留服务器使用此传输方式。

传输方式选择与协议协商是相互独立的。可选的 mode 设置控制客户端接受哪个 MCP 协议时代。请参阅协议时代。

NOTE

对于新的远程服务器，可以同时省略 transport 和 mode。适配器将使用 Streamable HTTP 并进行自动协议协商。仅在连接具有已知遗留需求的服务器时才指定这些设置。

后续步骤

工具

将 MCP 工具加载到智能体中，控制其执行并处理其输出。

连接

连接生命周期、多服务器、协议时代和缓存。

身份验证

Bearer 令牌、OAuth 2.1 以及按用户划分的服务器身份验证。