从零搭建MCP服务器：让AI助手检索并预览3D资产数据-北京尧图网络

最近我完成了一个不大不小的需求让 AI 助手能直接访问我们内部那套“创世虚拟世界 CRM”里的 3D 资产数据。过去这类数据全都躺在内部数据库里开发要用 SQL 拉、要调内部接口业务同事只能开后台看AI 完全进不来。我花了几天时间从零打通了 MCP 访问创世虚拟世界 CRM 的 3D 数据链路顺手搭了一个可以直接调用的演示站把“AI 检索 3D 资产 - 返回模型元数据 - 前端实时预览模型”整个流程跑通了。这篇文章把需求分析、技术选型、实操细节和踩过的坑完整复盘一遍适合这几类读者想给内部系统开 AI 接口的人、研究 3D 资产管理方案的人、以及正在纠结“用 MCP 还是直接写 REST API”的人。我个人的结论先说在前面MCP 这套协议本身不难难的是把领域知识翻译成模型能看懂的工具描述以及搞定 3D 数据这种“又大又重”的返回结构。接下来按需求起源、架构设计、服务端实现、演示站搭建、问题排查几个部分展开。1. 需求起源为什么 AI 要读 3D 数据1.1 创世虚拟世界 CRM 里到底存了什么接手这个项目之前我对“CRM 里存 3D 数据”这件事是有点疑惑的。传统 CRM 通常存的是客户、线索、商机但创世虚拟世界 CRM 不太一样它名义上叫客户关系管理实际承载的是虚拟世界业务的核心资产客户在虚拟世界里购买、租赁、定制的各种三维模型和场景资源。具体来说系统里主要存了这么几类数据场景模型展厅、办公楼、室外街区这类大空间模型单个 GLB 文件经常 50MB 往上走。道具模型桌椅、灯具、电子设备、装饰品它们的特征是数量多、分类细。角色与服装模型虚拟形象、NPC、穿戴物这类模型 SKU 更新很频繁。场景布局配置记录“哪个模型放在哪个坐标、旋转角度是多少、是否可交互”等结构化信息。以前开发要查这些数据一般是直接连数据库写 SQL或者调用一套内部 REST API。接口做了好几个版本但有一个共同问题它们是给人设计的不是给模型设计的。AI 要查数据需要知道端点和参数格式还要理解返回 JSON 里的每个字段这套成本内化在代码里可以内化给大模型就不行了。所以需求本质上是让 AI 能像运营同事一样用自然语言去检索、查看、理解这些 3D 资产并且把结果可视化。这句话说得很轻松落地时涉及的东西却不少。1.2 传统 REST 接口在 AI 面前为什么不够用在考虑 MCP 之前我先评估了一下直接让 AI 调 REST API 的可行性。理论上可行但有几道绕不过去的坎第一接口发现成本高。AI 面对十几个甚至几十个 API 端点需要一份详细文档。就算把文档塞进提示词里token 消耗也很高而且文档更新后提示词还得同步改。更何况业务接口每天都在调整文档必然滞后。第二参数描述太弱。一个?typemodelcategorychairstatusactive这样的查询串人看文档能懂模型不一定能正确生成。特别是过滤条件多的时候模型经常漏参数、传错枚举值。第三3D 数据根本不适合塞进文本返回。一个 GLB 模型动辄几十 MBREST 接口返回 JSON 元数据还好但真要把模型内容交给 AI“理解”总不能走 base64 内嵌——那会直接撑爆上下文窗口。第四权限问题。内部接口的 Token 体系、操作审计、频率限制这些如果直接暴露给外部模型调用风险很难控制。我需要的是一个统一接入层在这个层上做收敛和审计。这些痛点归结起来就是一句话AI 需要一个“标准化工具箱”而不是一堆散落的接口。1.3 MCP 把“接口”变成了“工具”MCPModel Context Protocol模型上下文协议做的事情正好是把“接口”抽象成“工具”。它定义了服务端怎么暴露能力、客户端怎么发现能力、模型怎么调用能力一套标准下来我只需要实现一次 MCP 服务端任何支持 MCP 的客户端都能接。MCP 里有三个核心原语我用项目里的说法解释一下Tools工具类似一次函数调用模型根据描述决定要不要调、传什么参数。比如search_3d_assets。Resources资源类似静态文件或数据源客户端可以主动读取适合暴露固定数据片段。Prompts提示词模板提前写好的指令模板方便复用常见任务流程。这个项目里核心是 Tools因为“搜索模型”、“获取模型详情”、“生成预览链接”天然是动作不是数据页。用生活化的类比REST API 是散落在各部门门口的对讲机MCP 是一个总机每个能力都注册了分机号码并写了使用说明AI 只要对着总机报分机号接线员就知道该转给谁。2. 方案选型与整体架构设计2.1 为什么不直接开放 API要套一层 MCP我在前面讲了 REST 接口的问题这里再补充一下为什么最终选了 MCP 方案而不是自己写一套 Function Calling 封装。最大的原因是不想绑定某一家模型厂商。市面上的大模型客户端各自有 Function Calling / Tool Use 的调用格式核心思想一致但接口不通用。如果我为某个模型定制一套工具调用协议将来换模型、接多个模型都要重写。而 MCP 是标准化协议服务端实现一次客户端生态里已经有不少现成支持我可以把 MCP 服务器接到不同模型客户端上用同一套代码。另一个原因是“工具描述即能力声明”。MCP 工具需要写清楚名称、描述、输入参数 Schema这个东西写好了模型靠它就能判断该调哪个工具。REST API 做不到这种自描述因为一个 HTTP 方法加一个 URL 并不能告诉模型这个接口的业务含义。最后是权限收敛。所有数据访问都通过 MCP 服务器这一层我可以在这层统一做鉴权、日志、限流、数据脱敏。如果把权限逻辑散落在各种 API 网关和业务代码里维护成本会高很多。2.2 整体架构数据服务、MCP 服务器、演示站三件套整个项目我拆成了三层图示逻辑是这样的层次职责关键技术数据服务层存储 3D 资产元数据与模型文件PostgreSQL 元数据库对象存储存 GLB/缩略图MCP 服务层把数据服务能力包装成 MCP 工具处理鉴权、会话、日志Python MCP SDKStreamable HTTP 传输演示站层提供可视化页面展示 MCP 调用过程与 3D 模型预览前端静态页调用网关 Three.js数据服务层还是那套内部的 CRM 系统我没有动它的表结构只是新加了一套只读的查询视图和文件访问接口。MCP 服务层是新增的它不直接连接数据库读写所有表而是只暴露精选的几个能力搜索资产、获取详情、生成预览、更新资产状态。演示站层是给业务同事和老板看的也方便我自己调试。为什么加演示站而不是只写一个配置因为老板要看结果业务同事也要验证“输入一句话能不能查到想要的模型”。一个网页比命令行输出直观得多。2.3 传输方式我为什么用 Streamable HTTP 而不是 stdioMCP 目前主流有两种传输方式stdio 和 Streamable HTTP我最后选了后者原因和项目形态强相关。stdio 适合本地场景客户端直接拉起 MCP 服务器进程通过标准输入输出通信。这个模式在本地 CLI、桌面应用里很爽不需要开端口、不需要网络配置调试也简单。但问题也很明显它不适合远程部署。如果演示站跑在另一台服务器上客户端没法直接拉起我的进程。Streamable HTTP 则是把 MCP 的请求映射为 HTTP 调用服务端启动一个 HTTP 端点客户端通过 POST 发送 JSON 请求服务端可以返回一个流式响应。这个模式适合我这种“MCP 服务器独立部署演示站远程调用”的架构。我只需要在网关层定义好路由规则演示站前端通过一个轻量代理就能发起 MCP 请求不需要在浏览器里直接跑 MCP 客户端。实际开发时本地我还是会用 stdio 模式做快速测试部署到服务器才切 Streamable HTTP。两条路都保留配置项切一下就行不算额外成本。3. 从零搭建 MCP 服务器让 3D 资产“开口说话”3.1 先理清 3D 资产的数据模型开始写 MCP 工具之前我先花了大半天梳理 3D 资产的数据结构。这一步很关键如果数据结构没理清后面的工具定义就会抽象得很尴尬。创世虚拟世界 CRM 的资产表结构大致是这样的字段名类型说明asset_idvarchar全局唯一 ID如AST-7F3A2Cnamevarchar资产名称如“未来展厅 03”asset_typeenummodel / texture / scene / characterspace_idvarchar归属空间 IDstatusenumactive / archived / processingsize_bytesbigint模型文件大小tri_countint三角面数material_countint材质数量glb_urivarcharGLB 文件存储路径thumb_urivarchar缩略图路径extrajsonb扩展属性如作者、标签、版本等GLB 文件本身放在对象存储数据库只存路径和元信息。这样做的好处是不要在 MCP 返回里去塞模型二进制只返回 URI客户端拿到 URI 后再去加载模型。这个设计在后续解决“返回体过大会卡死”的问题时帮了大忙。3.2 定义第一个工具搜索 3D 资产MCP 工具最核心的是三个部分名称、描述、输入 Schema。下面是我定义的第一个工具专门用于搜索资产。{ name: search_3d_assets, description: 按名称、类型、空间、状态等条件搜索 3D 资产返回资产列表只包含元数据不包含模型文件。适用于查找某个展厅/道具/角色的模型或按标签筛选资产。, inputSchema: { type: object, properties: { keyword: { type: string, description: 搜索关键词支持模糊匹配资产名称例如椅、展厅或完整名称。 }, asset_type: { type: string, enum: [model, texture, scene, character], description: 资产类型不传则匹配全部。 }, space_id: { type: string, description: 空间 ID例如 SPACE-001。 }, status: { type: string, enum: [active, archived, processing], description: 资产状态默认返回 active。 }, limit: { type: integer, minimum: 1, maximum: 50, default: 20 } } } }有一个值得展开的细节description字段里一定要写清参数的业务含义和边界。一开始我写得很简略模型经常把space_id传成资产 ID导致查不到数据。后来我把每个字段的可选值、默认行为、举例都写进 description情况立刻好转。这个经验在我后面项目里一直沿用工具描述本质上是模型唯一的“操作手册”写得不细致效果就大打折扣。工具调用的返回格式我统一设计成下面这种[ { asset_id: AST-7F3A2C, name: 未来展厅 03, asset_type: scene, space_id: SPACE-001, status: active, size_bytes: 83886080, tri_count: 320000, comment: 包含完整 PBR 材质无动画 } ]这里有个小设计列表返回时只给几张关键字段不给extra里的大段项目描述更不带glb_uri这类存储路径。为什么因为列表场景用户只看概要详情应该点进去再取。这样 MCP 的返回体小模型理解和展示的速度都会快很多。3.3 定义第二个工具获取模型详情与预览链接查询列表往往不是终点用户真正想要的是“看一眼这个模型长什么样”。所以我定义了第二个工具get_asset_preview。{ name: get_asset_preview, description: 根据 asset_id 获取单个 3D 资产的详情信息和预览链接返回模型文件地址、缩略图地址、三角面数、材质数量、格式和状态。适合用户想查看某个具体模型时调用。, inputSchema: { type: object, properties: { asset_id: { type: string, description: 资产 ID例如 AST-7F3A2C。 } }, required: [asset_id] } }返回体我设计得比较完整{ asset_id: AST-7F3A2C, name: 未来展厅 03, asset_type: scene, status: active, glb_uri: https://assets.example.internal/spaces/SPACE-001/AST-7F3A2C/export.glb, thumb_uri: https://assets.example.internal/spaces/SPACE-001/AST-7F3A2C/thumb.jpg, tri_count: 320000, material_count: 12, format: glb, has_animation: false }注意glb_uri用的是外部可访问的临时签名 URL不是内网路径。MCP 服务层负责把内部存储路径转换成带签名的外链同时设置有效期。这样前端拿到 URL 后直接用它加载 Three.js 场景而不会把存储桶的访问密钥暴露出去。可能有同学会问为什么不让模型直接读 GLB 文件我试过。LLM 对二进制文件的理解能力目前基本为零直接喂 GLB 只会浪费上下文。更合理的做法是模型拿到元数据和 URI把它丢给前端渲染或者模型聚合多个资产的元数据生成一份摘要、对比表、或者统计报告。这个思路决定了整个 MCP 工具集的定位工具是给模型操作的“手柄”不是数据搬运工。3.4 配置传输与鉴权初始化连接、Token 校验服务端我用的是 Python 的 MCP SDK开发体验还不错。核心代码虽然不长但有几个配置点是容易踩坑的。from mcp.server.fastmcp import FastMCP mcp FastMCP( asset-crm-mcp, instructions这个服务器用于访问创世虚拟世界 CRM 的 3D 资产数据。 ) mcp.tool() def search_3d_assets( keyword: str | None None, asset_type: str | None None, space_id: str | None None, status: str active, limit: int 20, ) - list[dict]: 按条件搜索 3D 资产返回元数据列表。 ... mcp.tool() def get_asset_preview(asset_id: str) - dict: 获取单个 3D 资产的详情和预览链接。 ...FastMCP 框架会自动把 Python 函数转成 MCP 工具定义但我还是会在每个函数的 docstring 里详细写明参数语义因为文档字符串会被拼进工具描述里模型读到这个描述才能正确调用。鉴权方面我在 Streamable HTTP 模式下挂了一层中间件校验请求头里的Authorizationfrom fastapi import Request, HTTPException AUTH_TOKEN os.environ[MCP_ACCESS_TOKEN] async def check_auth(request: Request): auth request.headers.get(Authorization, ) if auth ! fBearer {AUTH_TOKEN}: raise HTTPException(status_code401, detailinvalid token)这里有一个细节MCP 服务端有自己的会话管理不要把自定义鉴权和它混在一起。我是在最外层做鉴权通过之后再把请求交给 MCP 处理程序。Token 放在环境变量里不写进代码也不写进配置文件。演示站调用时Token 由部署侧的网关注入前端拿不到。本地调试时我强烈推荐 MCP Inspector 这个工具启动后可以交互式地查看每个工具的定义、试传参数、看返回。它节省了我大量时间尤其是调试 JSON Schema 边界条件的时候。3.5 让 CRM 的数据服务可以被 MCP 安全访问MCP 服务器不是直接连数据库的它通过一层内部网关访问 CRM 的数据服务。这一层我已经在架构图里画了实际操作还有几个安全细节第一MCP 服务器和 CRM 数据服务之间走内网 VPC不暴露公网。MCP 服务器作为唯一对外的入口所有外部请求先过它再进内网。第二MCP 服务器对glb_uri做路径映射。内部存储路径形如s3://internal-bucket/spaces/SPACE-001/AST-7F3A2C/export.glb返回给前端时转换成签名 URL。第三每个签名 URL 附带短时效比如 10 分钟过期就算泄露也不能长时间滥用。第四MCP 工具只提供搜索、查询、预览能力不给“遍历全部资产”的大范围导出工具从模型层限制数据批量泄露的风险。4. 演示站前端与后端实现4.1 演示站要解决什么问题MCP 服务器部署完之后我第一时间用命令行调通了但我知道这没有说服力——业务同事不可能打开终端去敲 MCP 请求。所以我决定搭一个演示站目标很明确让用户敲一句话或点一个按钮就能通过 MCP 查到 3D 资产并在页面里预览。这个演示站我拆成了两个部分前端页面和轻量网关。前端页面负责交互和 3D 渲染网关负责把浏览器的请求转发给 MCP 服务器并处理鉴权。前端不直接连 MCP避免把 Token 暴露在浏览器里。页面布局很简单左侧是一个查询面板右侧是 3D 预览区底部是调用日志面板。查询面板支持按关键词、资产类型、空间 ID 检索每个搜索结果卡片上有“预览模型”按钮点击后加载模型并渲染到右侧场景中。底部日志面板展示完整的 MCP 调用过程工具名称、入参、出参、耗时、返回码业务同事可以直观感受到“AI 是怎么调工具的”。4.2 前端三维预览的实现3D 预览我选的是 Three.js GLTFLoader直接加载 GLB。这个组合在 Web 端最稳不需要额外插件浏览器原生支持 WebGL。import { GLTFLoader } from three/examples/jsm/loaders/GLTFLoader.js; import { DRACOLoader } from three/examples/jsm/loaders/DRACOLoader.js; const loader new GLTFLoader(); const dracoLoader new DRACOLoader(); dracoLoader.setDecoderPath(https://www.gstatic.com/draco/versioned/decoders/1.5.7/); loader.setDRACOLoader(dracoLoader); function loadAsset(url) { loader.load( url, (gltf) { const model gltf.scene; scene.add(model); fitCameraToObject(model); }, (progress) { console.log(loading..., progress.loaded / progress.total); }, (error) { console.error(load failed, error); } ); }有几个我在实际调式中反复踩的坑一是光照。GLB 文件通常自带 PBR 材质如果场景里没有足够亮的灯光模型看起来会是一团黑。我加了一个环境光加一个方向光并且把环境光的intensity调到 1.0方向光调 0.8这样才能还原模型在建模软件里的观感。二是相机适配。不同模型尺寸差异巨大有的小到 0.3 米有的大到上百米。我写了一个fitCameraToObject函数根据模型包围盒大小动态调整相机位置和距离同时限制最小/最大观看距离避免缩放飞出可视范围。三是压缩纹理支持。部分生产管线用了 Draco 压缩直接加载会报“unknown geometry type”之类的错误必须引入 DRACOLoader。所以我在代码里一上来就设置了setDRACOLoader把这个潜在问题从源头解决。4.3 调用面板设计模拟一次 MCP 交互演示站最有意思的部分是“模拟 AI 调用”面板。用户输入一句自然语言比如“帮我找一下二号展厅里所有 active 状态的椅子资产”前端不会真的去调用大模型——那样成本高且不可控——而是采用规则映射的方式从句子中提取关键词组装成 MCP 工具参数。这一步我本来想接一个 LLM 来做自然语言到工具参数的转换但权衡之后决定演示站里先用规则引擎因为演示场景的意图是比较固定。规则映射效果已经足够稳定也让用户可以看到一个“结构化”的调用流程。面板会依次展示以下内容解析出的意图search_3d_assets生成的参数{keyword: 椅, asset_type: model, status: active, limit: 20}网关转发的 MCP 请求体JSON 格式MCP 返回的结果JSON 格式前端根据结果渲染的资产卡片列表这样设计的好处是透明度极高。业务同事和开发评审去看演示能清楚看到“这句话怎么变成一个 MCP 请求”而不是一个神秘的黑盒魔法。在实际项目里如果要把这个面板接回真实 LLM我只需要把 MCP endpoint 配置到 AI 客户端的工具列表里客户端自动就能发现search_3d_assets和get_asset_preview。到了那一步用户输入自然语言AI 自行决定调用哪个工具演示站的规则映射反而变成了兜底方案。整个升级路径非常平滑这也是 MCP 生态的价值所在。5. 实操中遇到的坑与排查记录5.1 工具描述含糊导致模型选错工具第一次联调时我在 MCP Inspector 里手动调用search_3d_assets一切正常但通过真实模型调用时它经常混用工具比如用户问“某个展厅里的模型”模型会去调用get_asset_preview传进去一个space_id结果当然是查不到。排查后发现根因是工具描述写得太泛。get_asset_preview的 description 里写的是“获取资产详情”模型看到“详情”就把查询需求也归到这里。解决办法是把描述改得更加面向场景search_3d_assets的 description 明确写“这是第一个应该调用的函数用于搜索或筛选资产”并给出多个调用示例。get_asset_preview的 description 明确写“仅当已知 asset_id 时使用”并要求必须先通过 search 获取 ID。这个改动让模型选工具的准确率提升很明显。经验就是每个工具的描述里一定要写清“什么时候用、什么时候不要用”。5.2 数据返回太大把 MCP 通道卡死开发预览工具时我踩了一个严重的坑get_asset_preview一开始把extra字段里的完整项目描述、贴图清单、制作过程全都放进了返回体。结果一个资产的返回 JSON 膨胀到 2MBMCP 通道解析变慢模型直接超时。优化方案分三步列表接口只返回精简字段详情接口也只返回前端渲染必需的字段。长文本内容放资源Resources而不是工具返回由客户端按需读取。大文件一律用 URL 指代替不内嵌二进制。改完以后最重的返回也只有几十 KB体感舒适很多。这也印证了 MCP 工具设计的一条原则模型不需要一次知道所有信息它只需要知道“下一步去哪里拿”。5.3 模型预览黑屏演示站前端第一个版本调通后有一部分资产点击预览时黑屏。查了半天发现不是 Three.js 的问题而是 GLB 文件本身的问题部分生产导出工具生成的 GLB 自带贴图路径是绝对路径Web 端加载时无法访问那个内网路径于是贴图丢失模型变成黑灰色。解决办法有两个方向一是规范导出流程贴图尽可能内嵌到 GLB 中使用BIN数据块二是对于必须外链贴图的文件签名的 URL 需要覆盖贴图路径。由于贴图数量多且路径不确定我用了个折中方案为 GLB 文件生成一个同名的 ZIP 资源包前端通过GLTFLoader配合资源包加载器处理。这个问题也提醒了我3D 数据接入不是只打通一个 HTTP 接口就完事数据规格本身也要向 Web 端适配。5.4 鉴权过期与跨域问题部署到测试环境后第二天演示站突然报 401。查看日志发现是 Token 过期了。因为我在测试阶段把 Token 有效期设成 12 小时第二天演示站的网关缓存还拿着昨天的 Token。我把 Token 的有效期改为 2 小时并且网关增加了 Token 自动刷新逻辑缓存到 Redis 里。另外还加了跨域白名单浏览器发起的请求只允许演示站域名访问其他域名一律拒绝。这里要提醒MCP over HTTP 和普通 API 一样必须处理 CORS、超时、重试这些老生常谈的问题协议本身不会帮你避免这些问题。5.5 常见问题速查表问题现象解决办法模型选错工具AI 调用预览工具传了 space_id优化工具 description写清使用时机MCP 返回超时单个返回体过大精简字段大文件用 URL 指代预览黑屏GLB 贴图路径失效贴图内嵌或提供资源包加载鉴权过期演示站突然 401缩短 Token 有效期网关自动刷新CORS 拦了请求浏览器控制台报跨域网关配置白名单只允许演示站域名资产加载缓慢模型几十 MB 纹理启用 Draco 压缩生成缩略图优先展示我从这次项目中最大的体会是MCP 的价值不在于协议本身有多高级而在于它让 AI 变成了一个真正能操作内部系统的“接线员”。3D 数据只是其中一个场景这个模式完全可以套到更多资产类型上视频素材、图纸文件、自动化报告、运维巡检记录只要你能把数据能力翻译成工具描述AI 就有机会帮你调用来完成实际任务。最后再分享一个小技巧整个链路调试时先把 MCP 工具当作普通函数测在 MCP Inspector 里把每个工具的边界条件都过一遍再接真实模型。否则出了问题你会分不清是协议配置、工具描述、还是数据服务的锅。先分层验证再联合联调是这类项目最省时间的路径。

从零搭建MCP服务器：让AI助手检索并预览3D资产数据

相关推荐

复刻 Claude Code 御马术缰绳系统：harness engineering 落地蓝图与 hooks 配置清单

SQLServer2000老库维护与迁移：从安装到避坑的实战指南

Linux进程管理：孤儿进程、僵尸进程与wait/waitpid回收实战

更多资讯

深度拆解WPE封包修改：从截包分析、滤镜制作到独立外挂打包的实战路径

Open Code Review：开放评审过程的工程实践方法论

论文查重与AIGC检测全解析：从原理到降重实战

Open-Code-Review：一种去中心化的代码协作新范式

软件开发接单遭遇先交履约保证金？识别骗局与安全接单指南

mysql-8.0.15-winx64 zip包安装：初始化、配置与避坑全攻略

今日更新

Susi AI API实战指南：susi_alexa_skill如何用Node.js调用chat.json获取智能回答

换新电脑了？KeyStats 恢复码数据找回完全指南，端到端加密统计一键重建

重建二叉树：由前序与中序遍历序列还原二叉树的原理与 Java 实现（YCBlogs 剑指 Offer 精讲）

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？