开发第一个 MCP Server
本文将逐步说明如何在云开发平台上开发一个 MCP Server，包含以下几个步骤：
- 用模板创建出 MCP Server 云托管服务
- 使用云开发 MCP 框架开发 MCP Server
- 使用图形界面本地调试 MCP Server
- 部署至线上，覆盖原有云托管服务
- 在 Agent 中使用 MCP Server
创建空白 MCP Server
前往 云开发平台 创建一个空白 MCP Server，设置标识为 first-mcp。
该步骤会自动创建一个云托管服务承载 MCP Server，在后文中我们将会自己开发一个 MCP Server 并覆盖该云托管服务。
准备代码
我们提供了一个基本的 MCP Server 模板，包含了一个完整的 MCP Server 项目。可以以此项目为基础进行修改，开发您自己的 MCP Server。
本文将会介绍如何使用此项目代码进行本地开发调试以及部署。
安装依赖
下载项目代码，解压后进入项目目录，通过命令行执行如下命令，安装依赖：
npm i
为 MCP Server 添加第一个工具
修改 src/server.ts 中的实现，实现一个获取用户访问信息的工具，该工具会返回最近 count 条用户访问信息。
也可以使用模板自带的工具，直接进入下一步。
import {
ContextInjected,
TcbExtendedContext,
} from "@cloudbase/functions-typings";
import { CloudbaseMcpServer } from "@cloudbase/mcp/server";
import tcb from "@cloudbase/node-sdk";
import { z } from "zod";
export function createServer(context: ContextInjected<TcbExtendedContext>) {
const server = new CloudbaseMcpServer(
{
name: "Basic Server",
version: "1.0.0",
},
{ capabilities: { tools: {} } }
);
const env =
context.extendedContext?.envId || process.env.CLOUDBASE_ENVIRONMENT; // 本地开发从环境变量读
const secretId = context.extendedContext?.tmpSecret?.secretId;
const secretKey = context.extendedContext?.tmpSecret?.secretKey;
const sessionToken = context.extendedContext?.tmpSecret?.token;
// 创建 Cloudbase Node sdk 实例
const app = tcb.init({
env,
secretId,
secretKey,
sessionToken,
});
server
.tool("getUserVisitInfo") // 工具名
.description("获取最新的用户访问信息") // 工具的描述
.inputSchema({
count: z.number().describe("获取最近 {count} 条用户访问信息"),
}) // 工具的入参
.outputSchema({
total: z.number().describe("数据模型中总共的用户访问信息数量"),
records: z
.array(
z.object({
device: z.string().describe("用户设备"),
visitTime: z.number().describe("用户访问时间"),
})
)
.describe("返回的用户访问信息数组"),
}) // 工具的出参
.formatter(({ count }, { records, total }) => {
return {
content: [
{
type: "text",
text: `要求获取 ${count} 条用户访问信息，实际获取到 ${
records.length
} 条, 数据模型中总共 ${total} 条。\n${records
.map(
(x, index) =>
`${index + 1}: 来自 ${
x.device
} 的用户在 ${new Date().toLocaleTimeString()} 访问了。\n`
)
.join("\n")}`,
},
],
};
}) // 工具的格式化函数，给到大模型的时候返回的是经过格式化的数据
.create(async ({ count }) => {
const res = await app.models.sys_user_dau.list({
pageSize: count,
getCount: true,
orderBy: [
{
visit_time: "desc",
},
],
}); // 工具的实现函数;
return {
total: res.data.total,
records: res.data.records.map((x) => ({
device: x.device,
visitTime: x.visit_time,
})),
};
});
// todo
// 可以添加更多工具
return { server };
}
本地调试 MCP Server
添加环境变量文件
新建一个 .env.development 文件，填入以下内容:
MCP_SSE_ROUTE=LOCAL
SKIP_VERIFY_ACCESS=true
该文件定义了环境变量：
MCP_SSE_ROUTE=LOCAL：设置后可启用本地 SSE 服务，将 MCP Inspector/MCP Host（如 Cursor）连接至本地 MCP ServerSKIP_VERIFY_ACCESS=true：设置后可跳过 token 校验。原有 token 校验将只允许来自 API Key 和超管身份的 token 调用
设置 MCP_SSE_ROUTE、SKIP_VERIFY_ACCESS 这两个环境变量有助于我们在本地进行调试，但不建议在线上生产环境设置。
启动本地 MCP Server
npm run login # 登录云开发
npm run dev
启动后，将会在 http://localhost:3000/messages 提供服务。
修改代码，即可触发重新编译并重启服务。
启动图形界面调试
开启另一个终端，启动 @cloudbase/mcp-inspector:
npx -y @cloudbase/mcp-inspector
访问 http://127.0.0.1:5173 即可看到调试页面了。
- 在左侧选择
POST或SSE类型，并填入URL为http://localhost:3000/messages - 在左侧点击
Connect - 在
Toolstab 下点击List Tools展示工具列表 - 选择任一工具进行调用
构建
开发调试完成后，在项目根目录运行构建命令:
npm run build
部署
构建完成后，运行部署命令:
npm run login
npm run deploy
选择环境后，服务名称输入前面创建 MCP 服务时候指定的服务标识，例如 first-mcp。
使用线上的 MCP Server
部署后，即可阅读以下文档使用 MCP Server 了:
问题排查
本地调试时，MCP Server 无法连接
检查本地环境变量是否正确设置，检查本地端口是否被占用。
可以在 inspector 界面中开启 F12 打开浏览器的调试工具查看网络请求
查看类似
http://localhost:3000/sse?transportType=sse&url=http%3A%2F%2F127.0.0.1%3A3099%2Fmessages 这个请求返回的响应，一般如果连接不成功，这里都会有对应的错误信息