Create ,write connection and tool‑loading part first:

import "dotenv/config";import { MultiServerMCPClient } from "@langchain/mcp-adapters";不过，function requireEnv {
const value = process.env;不过，if {
throw new Error;老实说，}
return value;}
const mcpClient = new MultiServerMCPClient({
useStandardContentBlocks: true,mcpServers: {
remoteService: {
transport: "http"。url: requireEnv,},// 如需本地 stdio，只需改成下面形式：
// localService: {
// transport: "stdio",// command: "node",// args:,// },},});const tools = await mcpClient.getTools;console.log);

Pain point: 很多团队在“获取工具列表”这一步直接硬编码或手动复制 swagger，这导致维护成本爆炸。一旦后端更新，只需要重新跑一次 getTools 即可自动同步。

把工具交给模型，不等于已经执行工具

import { ChatOpenAI } from "@langchain/openai";const model = new ChatOpenAI({
model的观点是，requireEnv,apiKey: requireEnv。temperature: 0,configuration: { baseURL: requireEnv },});const modelWithTools = model.bindTools;

User pain point: 开发者经常误以为 bindTools 就会自动执行。这导致调试时看到“模型说要用 X 工具，却没有实际请求”。bindTools 仅是把“菜单”交给 LLM 看，看完后仍需自行循环调度。

用消息列表完成工具调用闭环

A single question may need multiple tools,or repeated calls to same tool . Therefore we must loop until model stops requesting tools.

import { HumanMessage } from "@langchain/core/messages";async function runAgent {
const messages =;for {
console.log;const response = await modelWithTools.invoke;其实，messages.push;const toolCalls = response.tool_calls?，;if {
// 没有 tool_calls 表示得到最终答案
return response.content;怎么说呢，}
for {
const tool = tools.find;if {
throw new Error;}
console.log})`);// 必须传入完整对象，以保留 call_id 等元信息
const toolMessage = await tool.invoke;messages.push;}
}
throw new Error;}

Pain point:

• If you only pass 。you lose call ID and model cannot associate results with its request,causing “我没有收到结果” 的错误。
• If you forget to push  back into ,subsequent rounds will not see tool’s output.
• The loop guard (maxIterations） prevents runaway billing when a mis‑configured model keeps calling tools forever.

完整可运行代码

import "dotenv/config";import { MultiServerMCPClient } from "@langchain/mcp-adapters";import { ChatOpenAI } from "@langchain/openai";import { HumanMessage } from "@langchain/core/messages";function requireEnv {
const v = process.env;if throw new Error;return v，}
// ---------- 初始化 MCP 客户端 ----------
const mcpClient = new MultiServerMCPClient({
useStandardContentBlocks: true。mcpServers: {
remoteService: {
transport: "http",url: requireEnv,},},});async function run {
// ---- 步骤1：发现并转换工具 ----
const tools = await mcpClient.getTools;console.log，// ---- 步骤2：创建支持 Tool Calling 的语言模型 ----
const model = new ChatOpenAI({
再看model。requireEnv,apiKey: requireEnv,temperature: 0,configuration: { baseURL: requireEnv },});
const modelWithTools = model.bindTools;// ---- 步骤3：进入 Agent 循环 ----
const answer = await runAgent(
"请告诉我这个 MCP 服务提供了哪些能力，并选择合适的工具验证其中一项。",tools,modelWithTools。/* maxIterations */5
);console.log，}
// ---------- Agent Loop ----------
async function runAgent {
const messages =;老实说，for {
console.log;const aiResp = await modelWithTools.invoke;messages.push;const calls = aiResp.tool_calls?，;if return aiResp.content;for {
const tool = tools.find;if throw new Error;console.log);const resultMsg = await tool.invoke;// 保留 call_id 等元信息
messages.push;console.log);}
}
throw new Error 已达，但仍未产生最终答案`);}
// ---------- 执行入口 ----------
run
.catch)
.finally => mcpClient.close);

程序从启动到结束发生了什么

1. .env 加载：`dotenv/config` 把配置注入 `process.env`。
2. MCP 客户端实例化：`MultiServerMCPClient` 创建但尚未发起网络请求。
3. #1 工具发现：`getTools` 向远程 HTTP MCP Server 发起握手，请求并解析 `` 为 LangChain 可识别对象。
4. #2 模型创建 & bind：`ChatOpenAI` 配置好兼容 OpenAI 的 endpoint，接下来 `bindTools` 把每个 Tool 的 name/description/schema 注入后续请求 payload 中。
5. #3 第一次推理：`modelWithTools.invoke` 将使用者问题 + Tool schema 发给 LLM；LLM 若需要外部信息，会返回 `tool_calls` 数组。此响应也被记录进 `messages` 历史。
6. #4 工具执行：`tool.invoke` 使用 MCP 协议通过 HTTP/STDIO 实际调用远端服务；返回值被包装成 `ToolMessage`，随后追加到 `messages`。
7. #5 循环迭代：LMM 看到完整历史，决定是否继续调取其他 Tool 或直接给出答案。如果 `tool_calls` 为，循环终止并返回最终 `content`。
8. #6 清理资源：`finally` 块里统一调用 `mcpClient.close`。关闭 HTTP 长连或子进程句柄，以防进程悬挂或泄漏句柄导致超时计费。

常见错误与排查方法

1️⃣ 工具结果为空或模型提示“没有收到结果” 🚩

• Pain point：开发者往往只取 `toolCall.args` 手动请求后返回字符串。而忘记把关联 ID 包装回 `ToolMessage`，导致 LLM 无法匹配结果来源。
• SOLUTION：始终使用完整对象 `await tool.invoke`；若自行实现自定义适配器，请确保返回对象包含 `{content。tool_call_id}` 字段。
• TROUBLESHOOTING：
  1. 检查控制台是否打印 “执行 Tool …” 日志，若没有说明 `tool_calls` 本身为空。
  2. 确认 Remote Service 返回的是标准化 ContentBlock，而不是随意打印日志到 stdout。
  3. If using HTTP,inspect raw response via curl – you should see a JSON envelope with `content_blocks`.

2️⃣ Remote 地址浏览器可访问。但 MCP 连不上 ❌

• Pain point：很多人误以为任意公开 URL 都是有效 MCP endpoint，仅凭浏览器能打开就认为配置正确，从而浪费时间定位网络层错误。
• SOLUTION：
  • - 确认 URL 包含完整方法，如 `/mcp/v1/stream` 而非根域名。
  • - 检查服务器是否实现 *Streamable* HTTP，而非普通 REST 响应。如果是旧式 SSE，需要将 client 配置改为 `{transport:"sse"}`。
  • - 如需鉴权，在 client 配置里加入 `{headers:{Authorization:`Bearer ${token}`}}`。
  • - 本地网络防火墙 / 公司代理 是否阻断了 Node.js 对该域名的 outbound 请求？可尝试 telnet / curl 验证。不过，

3️⃣ 模型一直不触发 Tool 调用 🔄

• Pain point：开发者经常忘记确认所选 LLM 真正支持 “function calling / tool calling”。或者 Prompt 没有明确引导需求，使得 LLM 给出直接答案而不需要外部信息。"​"
• SOLUTION：
  • - 打印已加载 Tools 列表 `)，确保描述足够明确且符合业务场景。
  • - 在 Prompt 中加入 “如果需要获取 X。请使用 Y 工具”，或者使用程序指令强制开启函数模式。
  • - 若使用 OpenAI‑compatible 服务。请确认 API 文档中标明支持 `"tools"` 参数，否则接口会忽略并返回纯文本。

4️⃣ 本地 stdio 服务报 “Cannot find module …老实说，” 📁

• Pain point：相对方法经常因启动目录不同而失效。使得子进程根本没法启动，从而导致客户端一直等待超时。
• SOLUTION：
  • - 使用绝对方法 `) 填入 `args`.
  • - 在终端单独运行 `node /abs/path/to/server.mjs` 确认脚本本身可以正常启动且不向 stdout 输出除 error 外的信息。

5️⃣ 程序异常后进程不退出 ⚙️

• Pain point：HTTP 长链接或子进程仍保持打开状态。使得 Node.js event loop 永久活跃，即使主逻辑已经抛错退出也看不到 exit code。
• SOLUTION：
  • - 将所有资源释放写在 `finally { await mcpClient.close;}`.
  • - 对于 stdio 子进程，可显式调用 `.kill` 或监听 `'exit'` 回调确保已结束。

从演示走向真实生产环境 🚀

• A. 限制可用 Tool 列表： 不要盲目暴露所有服务器实现的功能，只让业务需要的几项通过白名单方式注册到 LangChain。这能防止恶意 Prompt 调用危险操作。
• B. 超时、重试与输出上限： 网络 I/O 与搜索类 Service 常有长尾延迟，为每次 invoke 设置 `timeoutMs ` 并限制最大重试次数；对返回内容做大小截断或摘要，以免占满 LLM。不过，
| 场景 | 推荐配置 | |------|----------| | 搜索 API | timeoutMs=5000。retry=2 | | 文件读取 | maxBytes=200KB | | 图片生成 | maxTokens=300 |
• C. 完整日志与追踪 ID： 为每次使用者查询生成唯一 traceId，将其随每轮消息、Tool 调用还有响应一起记录。日志中 **不要** 打印 API 密钥或原始使用者隐私数据，只保留摘要信息供运维排查。怎么说呢，
• D. 参数复核 & 安全校验： 即便 Schema 限定了类型。也不能直接信任，例如方法字段合法但可能指向受保护目录；URL 参数合法却可能触发 SSRF。建议在实际执行前再走一遍业务白名单检查或人工批准流程。

🎯

MCP 并不是某个神奇函数，而是一套"发现‑描述‑调用‑回流" 的闭环机制。从在这套机制里来看，

• Discovery —— 用统一协议拿到远端 Service 暴露出的 Tools；