前端搭建 MCP Client(Web版)+ Server + Agent 实践

关注更多AI编程资讯请去AI Coding专区：
https://juejin.cn/aicoding

先上个效果图，上图是在 web 版 Client 中使用 todoist-mcp-server 帮我新建了一条 todolist。

本文主要介绍整体的思路和实现以及踩坑记录。

前言

MCP（Model Context Protocol）是一种开放协议，旨在通过标准化接口实现大语言模型（LLMs）与外部数据源及工具的无缝集成。MCP由 Anthropic 公司在2024年底推出，其设计理念类似于USB接口，为AI模型提供了一个“即插即用”的扩展能力，使其能够轻松连接至不同的工具和数据源。想深入了解可查看 官方文档，这里只做实战经验分享。

概念介绍

MCP Hosts（MCP 应用）：如Claude Desktop、IDE、AI应用等，希望通过MCP访问数据或工具。MCP Clients（MCP 客户端）：与一对一与服务端进行连接，相当于我们应用中实现数据库交互需要实现的一个客户端。MCP Servers（MCP 服务端）：基于MCP协议实现特定功能的程序。Local Data Sources：本地数据源，公MCP服务器进行本地访问。Remote Services：远端服务，供MCP服务器访问远端访问，例如api的方式。

本文主要搭建 Web 版本的 MCP Client 和 MCP Server。

技术栈

系统要求：Node.js >= 18（本地用了v20）

核心依赖库：CopilotKit、LangChain及其生态。

• CopilotKit：React UI + 适用于 AI Copilot、AI 聊天机器人和应用内 AI 代理的优雅基础架构。
• LangChain.js 和 LangGraph：LangChain相关主要用于开发agent。
• langchainjs-mcp-adapters :提供了一个轻量级的包装器，使得 MCP 与 LangChain.js 兼容。
• modelcontextprotocol/typescript-sdk：MCP TypeScript SDK
• open-mcp-client：CopilotKit 开源的 MCP Client。
• mcp-server-supos：一个可用的 MCP Server。

Client

页面大概这样，包括：左侧管理MCP Server、右侧聊天机器人

技术方案

声明：此 Client 是基于CopilotKit 开源的 MCP Client open-mcp-client 二次改造

该代码库主要分为两个部分：

1. /agent – 连接到 MCP Server并调用其工具的LangGraph代理(Python)。
2. /app – 使用 CopilotKit 进行UI和状态同步的前端应用程序(Next.js)。

由于 Python 的 agent 在 Windows 环境下运行时报错：

本人Python编码能力有限，基于此改造成了基于 JS 的 agent（/agent-js部分），后续均以agent-js为例；想用 Python 的也可按后续的改动点对 /agent 进行修改。

一、agent部分

文件结构

核心代码

「agent.js」 - 基于 langgraph 创建 workflow，其中主要节点为 chat_node，该节点功能点：

• 定义LLM

import { ChatOpenAI } from"@langchain/openai";// import { HttpsProxyAgent } from "https-proxy-agent";// const agentProxy = new HttpsProxyAgent("http://127.0.0.1:xxxx");...// 1 Define the modelconst model = new ChatOpenAI(    {      temperature: 0,      model: "gpt-4o",    },    // todo: test, 走本地代理便于翻墙    // {    //   httpAgent: agentProxy,    // }  );...

「注意：本地联调需访问 openai 时，如果是使用的代理工具，还是需要在代码里指定代理地址（HttpsProxyAgent）」

• 从 state 获取 MCP Server Configs，创建 MCP Client 连接到 MCP Server，连通后获取 Server 的 tools。(@langchain/mcp-adapters)

const mcpConfig: any = state.mcp_config || {};// 重要：设置环境变量时，最好把当前进程的环境变量也传递过去，确保执行Server的子进程需要的环境变量都存在let newMcpConfig: any = {};Object.keys(mcpConfig).forEach((key) => {    newMcpConfig[key] = { ...mcpConfig[key] };    if (newMcpConfig[key].env) {      newMcpConfig[key].env = { ...process.env, ...newMcpConfig[key].env };    }  });console.log("****mcpConfig****", mcpConfig);// 2 Create clientconst client = new MultiServerMCPClient(newMcpConfig);// examples// const client = new MultiServerMCPClient({//   math: {//     transport: "stdio",//     command: "npx",//     args: ["-y", "mcp-server-supos"],//     env: {"SUPOS_API_KEY": "xxxxx"}//   },// });// 3 Initialize connection to the serverawait client.initializeConnections();const tools = client.getTools();

• 基于 model 和 tools 创建代理，并调用模型发送状态中的消息

// 4 Create the React agent width model and tools  const agent = createReactAgent({    llm: model,    tools,  });  // 5 Invoke the model with the system message and the messages in the state  const response = await agent.invoke({ messages: state.messages });

「完整代码」

agent.js

/** * This is the main entry point for the agent. * It defines the workflow graph, state, tools, nodes and edges. */import { RunnableConfig } from"@langchain/core/runnables";import {  MemorySaver,  START,  StateGraph,  Command,  END,} from"@langchain/langgraph";import { createReactAgent } from"@langchain/langgraph/prebuilt";import { Connection, MultiServerMCPClient } from"@langchain/mcp-adapters";import { AgentState, AgentStateAnnotation } from"./state";import { getModel } from"./model";// 判断操作系统const isWindows = process.platform === "win32";const DEFAULT_MCP_CONFIG: Record<string, Connection> = {supos: {    command: isWindows ? "npx.cmd" : "npx",    args: [      "-y",      "mcp-server-supos",    ],    env: {      SUPOS_API_URL: process.env.SUPOS_API_URL || "",      SUPOS_API_KEY: process.env.SUPOS_API_KEY || "",      SUPOS_MQTT_URL: process.env.SUPOS_MQTT_URL || "",    },    transport: "stdio",  },};asyncfunction chat_node(state: AgentState, config: RunnableConfig) {// 1 Define the modelconst model = getModel(state);const mcpConfig: any = { ...DEFAULT_MCP_CONFIG, ...(state.mcp_config || {}) };// 重要：设置环境变量时，最好把当前进程的环境变量也传递过去，确保执行Server的子进程需要的环境变量都存在let newMcpConfig: any = {};Object.keys(mcpConfig).forEach((key) => {    newMcpConfig[key] = { ...mcpConfig[key] };    if (newMcpConfig[key].env) {      newMcpConfig[key].env = { ...process.env, ...newMcpConfig[key].env };    }  });console.log("****mcpConfig****", mcpConfig);// 2 Create clientconst client = new MultiServerMCPClient(newMcpConfig);// const client = new MultiServerMCPClient({//   math: {//     transport: "stdio",//     command: "npx",//     args: ["-y", "mcp-server-supos"],//     env: {"SUPOS_API_KEY": "xxxxx"}//   },// });// 3 Initialize connection to the serverawait client.initializeConnections();const tools = client.getTools();// 4 Create the React agent width model and toolsconst agent = createReactAgent({    llm: model,    tools,  });// 5 Invoke the model with the system message and the messages in the stateconst response = await agent.invoke({ messages: state.messages });// 6 Return the response, which will be added to the statereturn [    new Command({      goto: END,      update: { messages: response.messages },    }),  ];}// Define the workflow graphconst workflow = new StateGraph(AgentStateAnnotation)  .addNode("chat_node", chat_node)  .addEdge(START, "chat_node");const memory = new MemorySaver();exportconst graph = workflow.compile({checkpointer: memory,});

model.js

/** * This module provides a function to get a model based on the configuration. */import { BaseChatModel } from"@langchain/core/language_models/chat_models";import { AgentState } from"./state";import { ChatOpenAI } from"@langchain/openai";import { ChatAnthropic } from"@langchain/anthropic";import { ChatMistralAI } from"@langchain/mistralai";// import { HttpsProxyAgent } from "https-proxy-agent";// todo test agentProxy// const agentProxy = new HttpsProxyAgent("http://127.0.0.1:7897");function getModel(state: AgentState): BaseChatModel {/**   * Get a model based on the environment variable.   */const stateModel = state.model;const stateModelSdk = state.modelSdk;// 解密const stateApiKey = atob(state.apiKey || "");const model = process.env.MODEL || stateModel;console.log(    `Using stateModelSdk: ${stateModelSdk}, stateApiKey: ${stateApiKey}, stateModel: ${stateModel}`  );if (stateModelSdk === "openai") {    returnnew ChatOpenAI({      temperature: 0,      model: model || "gpt-4o",      apiKey: stateApiKey || undefined,    }      // {      //   httpAgent: agentProxy,      // }    );  }if (stateModelSdk === "anthropic") {    returnnew ChatAnthropic({      temperature: 0,      modelName: model || "claude-3-7-sonnet-latest",      apiKey: stateApiKey || undefined,    });  }if (stateModelSdk === "mistralai") {    returnnew ChatMistralAI({      temperature: 0,      modelName: model || "codestral-latest",      apiKey: stateApiKey || undefined,    });  }thrownewError("Invalid model specified");}export { getModel };

state.js

import { Annotation } from"@langchain/langgraph";import { CopilotKitStateAnnotation } from"@copilotkit/sdk-js/langgraph";import { Connection } from"@langchain/mcp-adapters";// Define the AgentState annotation, extending MessagesStateexportconst AgentStateAnnotation = Annotation.Root({model: Annotation<string>,modelSdk: Annotation<string>,apiKey: Annotation<string>,mcp_config: Annotation<Connection>,  ...CopilotKitStateAnnotation.spec,});export type AgentState = typeof AgentStateAnnotation.State;

构建和运行

1. 定义 langgraph.json 配置文件，定义 agent 相关配置，比如agent名称：sample_agent等

{  "node_version": "20","dockerfile_lines": [],"dependencies": ["."],"graphs": {    "sample_agent": "./src/agent.ts:graph"// 定义agent名称等，用于前端指定使用  },"env": ".env"// 指定环境变量从.env文件中获取，生产环境可以删除该配置，从系统变量中获取}

在本地运行时，在根路径 /agent-js 添加 .env 文件

LANGSMITH_API_KEY=lsv2_...
OPENAI_API_KEY=sk-...

2.借助命令行工具@langchain/langgraph-cli进行构建和运行，在 
package.json 中定义脚本：

"scripts": {    "start": "npx @langchain/langgraph-cli dev --host localhost --port 8123",    "dev": "npx @langchain/langgraph-cli dev --host localhost --port 8123 --no-browser"  },

加上--no-browser不会自动打开本地调试的studio页面

运行后可以在Studio预览联调等

(Studio:https://smith.langchain.com/studio/thread?baseUrl=http%3A%2F%2Flocalhost%3A8123)

注意点（踩坑记录）

1. 引入modelcontextprotocol/

typescript-sdk报错：

@modelcontextprotocol/sdk fails in CommonJS projects due to incompatible ESM-only dependency (pkce-challenge)

主要是modelcontextprotocol/

typescript-sdk的cjs包里面引用的pkce-challenge不支持cjs

官方的issues也有提出些解决方案，但目前为止官方还未发布解决了该问题的版本

「解决：package.json 添加"type": "module" 字段，声明项目使用 「ES Modules (ESM)」 规范」

2. 配置 MCP Server 环境变量 env 问题

例如：Node.js 的 child_process.spawn() 方法无法找到例如 npx 等可执行文件。

「环境变量 PATH 缺失」，系统未正确识别 npx 的安装路径。

可能的原因：

1）MCP Server配置了 env 参数后，导致传入的 env 覆盖了默认从父进程获取的环境变量

「解决：对配置了 env 的 Server，将当前的环境变量合并传入」

const mcpConfig: any = state.mcp_config || {};  // 重要：设置环境变量时，最好把当前进程的环境变量也传递过去，确保执行Server的子进程需要的环境变量都存在  let newMcpConfig: any = {};  Object.keys(mcpConfig).forEach((key) => {    newMcpConfig[key] = { ...mcpConfig[key] };    if (newMcpConfig[key].env) {      newMcpConfig[key].env = { ...process.env, ...newMcpConfig[key].env };    }  });

2） 「跨平台路径问题」：比如在 Windows 中直接调用 npx 需使用 npx.cmd

// 判断操作系统const isWindows = process.platform === "win32";const DEFAULT_MCP_CONFIG: Record<string, Connection> = {supos: {    command: isWindows ? "npx.cmd" : "npx",    args: [      "-y",      "mcp-server-supos",    ],    env: {      SUPOS_API_URL: process.env.SUPOS_API_URL || "",      SUPOS_API_KEY: process.env.SUPOS_API_KEY || "",      SUPOS_MQTT_URL: process.env.SUPOS_MQTT_URL || "",    },    transport: "stdio",  },};

二、前端应用部分

前端应用部分改动主要是页面上的一些功能添加等，例如支持选模型，支持配置 env 参数等，页面功能相关的内容就略过，可以直接看 open-mcp-client，这里简单介绍下整体的一个架构。

架构方案

主要是 CopilotKit + Next.js，先看下 「CopilotKit」 官方的一个架构图：

根据本文实际用到的简化下（本文采用的 CoAgents模式）

核心代码（以Next.js为例）

核心依赖 @copilotkit/react-ui @copilotkit/react-core @copilotkit/runtime

1. 设置运行时端点

/app/api/copilotkit/route.ts：设置 agent 远程端点

import {    CopilotRuntime,    ExperimentalEmptyAdapter,    copilotRuntimeNextJSAppRouterEndpoint,    langGraphPlatformEndpoint} from"@copilotkit/runtime";;import { NextRequest } from"next/server";// You can use any service adapter here for multi-agent support.const serviceAdapter = new ExperimentalEmptyAdapter();const runtime = new CopilotRuntime({    remoteEndpoints: [        langGraphPlatformEndpoint({            // agent部署地址            deploymentUrl: `${process.env.AGENT_DEPLOYMENT_URL || 'http://localhost:8123'}`,             langsmithApiKey: process.env.LANGSMITH_API_KEY,            agents: [                {                    name: 'sample_agent', // agent 名称                    description: 'A helpful LLM agent.',                }            ]        }),    ],});exportconst POST = async (req: NextRequest) => {    const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({        runtime,        serviceAdapter,        endpoint: "/api/copilotkit",    });    return handleRequest(req);};

2. 页面接入 CopilotKit UI

/app/layout.tsx：页面最外层用 CopilotKit 包裹，配置 runtimeUrl 和 agent

import type { Metadata } from"next";import { Geist, Geist_Mono } from"next/font/google";import"./globals.css";import"@copilotkit/react-ui/styles.css";import { CopilotKit } from"@copilotkit/react-core";const geistSans = Geist({variable: "--font-geist-sans",subsets: ["latin"],});const geistMono = Geist_Mono({variable: "--font-geist-mono",subsets: ["latin"],});exportconst metadata: Metadata = {title: "Open MCP Client",description: "An open source MCP client built with CopilotKit ",};exportdefaultfunction RootLayout({  children,}: Readonly<{  children: React.ReactNode;}>) {return (    <html lang="en">      <body        className={`${geistSans.variable} ${geistMono.variable} antialiased w-screen h-screen`}      >        <CopilotKit          runtimeUrl="/api/copilotkit"          agent="sample_agent"          showDevConsole={false}        >          {children}        </CopilotKit>      </body>    </html>  );}

/app/page.tsx：选择需要的聊天组件，例如 CopilotPopup

"use client";import { CopilotPopup } from "@copilotkit/react-ui";export function Home() {  return (    <>      <YourMainContent />      <CopilotChat          className="h-full flex flex-col"          instructions={            "Youareassistingtheuserasbestasyoucan.Answerinthebestwaypossiblegiventhedatayouhave."          }          labels={{            title: "MCPAssistant",            initial: "Needanyhelp?",          }}        />    </>  );}

构建和运行

这里就参照 Next.js 官方即可

package.json

  "scripts": {    "dev-frontend": "pnpm i && next dev --turbopack",    "dev-agent-js": "cd agent-js && pnpm i && npx @langchain/langgraph-cli dev --host 0.0.0.0 --port 8123 --no-browser",    "dev-agent-py": "cd agent && poetry install && poetry run langgraph dev --host 0.0.0.0 --port 8123 --no-browser",    "dev": "pnpx concurrently \"pnpm dev-frontend\" \"pnpm dev-agent-js\" --names ui,agent --prefix-colors blue,green",    "build": "next build",    "start": "next start",    "lint": "next lint"  },

Server

建议直接参考 MCP Server Typescript SDK 示例开发，官网文档的用法更新没那么及时，容易走弯路。

mcp-server-supos 是一个可用的 MCP Server，也发布了对应的 npm 包。

这里截取核心代码片段，想了解更多可点击查看源码和使用文档等。

核心代码

• 提供tool-调用API查询信息
• 实时订阅MQTT topic数据进行缓存，用于提供 tool 查询分析最新数据
• 示例 server.resource

index.ts

#!/usr/bin/env nodeimport { McpServer } from"@modelcontextprotocol/sdk/server/mcp.js";import { StdioServerTransport } from"@modelcontextprotocol/sdk/server/stdio.js";import fetch from"node-fetch";import { z } from"zod";import fs, { readFileSync } from"fs";import _ from"lodash";import mqtt from"mqtt";import { pathToFileURL } from"url";import { createFilePath } from"./utils.js";let SUPOS_API_URL =  process.env.SUPOS_API_URL;let SUPOS_API_KEY =  process.env.SUPOS_API_KEY;let SUPOS_MQTT_URL =  process.env.SUPOS_MQTT_URL;if (!SUPOS_API_URL) {console.error("SUPOS_API_URL environment variable is not set");  process.exit(1);}if (!SUPOS_API_KEY) {console.error("SUPOS_API_KEY environment variable is not set");  process.exit(1);}const filePath = createFilePath();const fileUri = pathToFileURL(filePath).href;asyncfunction getModelTopicDetail(topic: string): Promise<any> {const url = `${SUPOS_API_URL}/open-api/supos/uns/model?topic=${encodeURIComponent(    topic  )}`;const response = await fetch(url, {    headers: {      apiKey: `${SUPOS_API_KEY}`,    },  });if (!response.ok) {    thrownewError(`SupOS API error: ${response.statusText}`);  }returnawait response.json();}function getAllTopicRealtimeData() {// 缓存实时数据，定时写入缓存文件const cache = newMap();let timer: any = null;const options = {    clean: true,    connectTimeout: 4000,    clientId: "emqx_topic_all",    rejectUnauthorized: false,    reconnectPeriod: 0, // 不进行重连  };const connectUrl = SUPOS_MQTT_URL;if (!connectUrl) {    return;  }const client = mqtt.connect(connectUrl, options);  client.on("connect", function () {    client.subscribe("#", function (err) {      // console.log("err", err);    });  });  client.on("message", function (topic, message) {    cache.set(topic, message.toString());  });  client.on("error", function (error) {    // console.log("error", error);  });  client.on("close", function () {    if (timer) {      clearInterval(timer);    }  });// 每 5 秒批量写入一次  timer = setInterval(() => {    const cacheJson = JSON.stringify(      Object.fromEntries(Array.from(cache)),      null,      2    );    // 将更新后的数据写入 JSON 文件    fs.writeFile(      filePath,      cacheJson,      {        encoding: "utf-8",      },      (error) => {        if (error) {          fs.writeFile(            filePath,            JSON.stringify({ msg: "写入数据失败" }, null, 2),            { encoding: "utf-8" },            () => {}          );        }      }    );  }, 5000);}function createMcpServer() {const server = new McpServer(    {      name: "mcp-server-supos",      version: "0.0.1",    },    {      capabilities: {        tools: {},      },    }  );// Static resource  server.resource("all-topic-realtime-data", fileUri, async (uri) => ({    contents: [      {        uri: uri.href,        text: readFileSync(filePath, { encoding: "utf-8" }),      },    ],  }));  server.tool(    "get-model-topic-detail",    { topic: z.string() },    async (args: any) => {      const detail = await getModelTopicDetail(args.topic);      return {        content: [{ type: "text", text: `${JSON.stringify(detail)}` }],      };    }  );  server.tool("get-all-topic-realtime-data", {}, async () => {    return {      content: [        {          type: "text",          text: readFileSync(filePath, { encoding: "utf-8" }),        },      ],    };  });asyncfunction runServer() {    const transport = new StdioServerTransport();    const serverConnect = await server.connect(transport);    console.error("SupOS MCP Server running on stdio");    return serverConnect;  }  runServer().catch((error) => {    console.error("Fatal error in main():", error);    process.exit(1);  });}asyncfunction main() {try {    createMcpServer();    getAllTopicRealtimeData();  } catch (error) {    console.error("Error in main():", error);    process.exit(1);  }}main();

utils.ts

import fs from"fs";import path from"path";exportfunction createFilePath(  filedir: string = ".cache",  filename: string = "all_topic_realdata.json") {// 获取项目根路径const rootPath = process.cwd();// 创建缓存目录const filePath = path.resolve(rootPath, filedir, filename);const dirPath = path.dirname(filePath);// 检查目录是否存在，如果不存在则创建if (!fs.existsSync(dirPath)) {    fs.mkdirSync(dirPath, { recursive: true });  }return filePath;}exportfunction readFileSync(filePath: string, options: any) {try {    return fs.readFileSync(filePath, options);  } catch (err) {    return`读取文件时出错: ${err}`;  }}

如何使用

「Client」：目前支持MCP协议的客户端已有很多，比如桌面端应用 Claude for Desktop，或者IDE的一些插件等（VSCode 的 Cline 插件），想了解已支持的客户端可访问 Model Context Protocol Client

「Server」：除了官方例子Model Context Protocol Client 外，已有很多网站整合了 MCP Servers，例如 mcp.so, Glama 等。

下面列举几个介绍下：

1. 配合本文 web 版 Client 使用（以todoist-mcp-server为例子）

1）配置

2）使用

2. 配合 Claude 使用

具体可参考：mcp-server-supos README.md，服务换成自己需要的即可

3. 使用 VSCode 的 Cline 插件

由于使用 npx 找不到路径，这里以 node 执行本地文件为例

1）配置

2）使用

结语

以上便是近期使用 MCP 的一点小经验~

整理完后看了下，如果只是单纯想集成些 MCP Server，其实可以不用 agent 形式，直接使用 copilotkit 的标准模式，在本地服务调用 langchainjs-mcp-adapters 和 LLM 即可，例如：

import {  CopilotRuntime,  LangChainAdapter,  copilotRuntimeNextJSAppRouterEndpoint,} from'@copilotkit/runtime';import { ChatOpenAI } from"@langchain/openai";import { NextRequest } from'next/server';// todo: 调用 @langchain/mcp-adapters 集成 MCP Server 获取 tools 给到大模型 ...const model = new ChatOpenAI({ model: "gpt-4o", apiKey: process.env.OPENAI_API_KEY });const serviceAdapter = new LangChainAdapter({    chainFn: async ({ messages, tools }) => {    return model.bindTools(tools).stream(messages);    // or optionally enable strict mode    // return model.bindTools(tools, { strict: true }).stream(messages);  }});const runtime = new CopilotRuntime();exportconst POST = async (req: NextRequest) => {const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({    runtime,    serviceAdapter,    endpoint: '/api/copilotkit',  });return handleRequest(req);};

但这样可能少了些上下文状态等，具体可以下来都试试~