如何在WebUI中使用MCP工具:工具调用与资源网关对比
作者:demo2026.11.16 10:57浏览量:0简介:本文围绕MCP协议中的“工具调用”与“资源访问”两种方式展开,说明它们在职责边界、数据流、权限控制、错误处理和适用场景上的区别,并结合文档解析、RAG和科研数据处理场景,给出从服务注册、参数设计到审计运维的完整接入思路,帮助开发者选择更稳妥的集成方案。
一、先明确对比对象:MCP工具调用与MCP资源访问
在WebUI中接入MCP协议时,开发者通常会遇到两类能力:
- MCP工具调用:由模型根据任务主动发起调用,用于执行某个动作,例如解析文件、查询数据、生成摘要、启动检索任务或提交处理请求。
- MCP资源访问:由服务端提供可读取、可引用、可复用的数据资源,例如解析后的文档、结构化表格、图片、公式、元数据和任务日志。
两者都可以通过MCP协议向Agent或WebUI暴露能力,但解决的问题不同。工具更像“执行函数”,资源更像“可被读取和引用的数据对象”。如果把所有内容都设计成工具,接口数量容易膨胀;如果把所有能力都设计成资源,又会缺少主动执行任务的能力。
因此,在实际架构中,较合理的做法通常是:用工具启动和控制任务,用资源承载任务结果和可复核数据。
二、为什么文档解析需要区分工具和资源
传统文档处理流程往往是:
上传文件 → OCR或文本提取 → 文本切块 → 向量化 → 进入问答流程
这种方式能够快速完成基础入库,但对科研论文、实验报告、专利、扫描件和复杂办公文档而言,纯文本并不能完整表达原始信息。
例如,以下内容都可能影响回答的准确性:
- 表格中的行列关系;
- 跨页表格的连续结构;
- 公式中的上下标和特殊符号;
- 图片及其图注;
- 标题层级和章节关系;
- 页码、段落、脚注等来源信息;
- 扫描文字的识别置信度;
- 文本片段与原始版面之间的对应关系。
如果解析结果只保留一段文本,Agent虽然能够“读到”内容,却不一定能够回答以下问题:
- 这句话来自哪一页?
- 该数字是正文内容还是表格内容?
- 公式是否可以被重新核验?
- 图片是否应当进入知识库?
- 这个表格是否跨页?
- 当前答案能否定位到原始文档?
因此,文档解析服务不应只是一个简单的 parse_document 函数,而应被设计成一个具备输入治理、任务调度、结果管理和审计能力的解析网关。
三、MCP工具调用的工作方式
MCP工具适合表达“需要执行的动作”。在WebUI中,模型通常根据用户意图选择工具,并按照工具定义提交参数。
一个通用的工具描述可以抽象为:
{"name": "parse_document","description": "解析指定文档并生成结构化结果","inputSchema": {"type": "object","properties": {"document_id": {"type": "string","description": "文档唯一标识"},"page_range": {"type": "string","description": "需要解析的页码范围"},"output_format": {"type": "string","enum": ["markdown", "json", "html"]}},"required": ["document_id"]}}
调用流程通常包括:
- 用户在WebUI中提出需求;
- 模型判断是否需要调用工具;
- 模型根据工具Schema生成参数;
- MCP服务端校验身份、权限和参数;
- 服务端执行任务;
- 返回结果或任务标识;
- WebUI向用户展示处理状态和最终结果。
工具调用的优势
第一,动作边界清晰。
工具名称、参数类型和返回结构可以被明确描述,便于模型理解,也便于开发者进行接口治理。
第二,适合主动执行任务。
例如文档解析、重新索引、抽取表格、生成摘要、刷新缓存等操作,都属于明显的动作型需求。
第三,便于权限控制。
服务端可以根据用户身份限制工具调用范围,例如普通用户只能读取文档,管理员才允许删除索引或重新处理全部文件。
工具调用的局限
工具并不适合承载所有复杂结果。如果解析一个大型文档后,直接把完整正文、图片和表格都放在工具返回值中,可能产生几个问题:
- 返回内容过大,增加上下文消耗;
- 结果无法稳定复用;
- 页面刷新后难以重新定位;
- 失败重试时缺少任务状态;
- 审计系统难以记录结果版本;
- 模型可能只看到截断后的内容。
因此,工具更适合返回任务状态、资源标识和少量摘要,而不是承载全部原始结果。
四、MCP资源访问的工作方式
MCP资源适合表达“已经存在、可以被读取和引用的数据”。例如:
- 解析后的Markdown;
- 结构化文档JSON;
- 表格HTML;
- 公式的LaTeX表示;
- 图片文件;
- 页级文本;
- 文档元数据;
- 解析日志和质量评估结果。
一个资源可以具有稳定的标识,例如:
resource://documents/{document_id}/contentresource://documents/{document_id}/pages/12resource://documents/{document_id}/tables/03resource://documents/{document_id}/figures/02
这里的资源标识只是通用示意,实际系统可以根据自身路由和存储方式设计。
资源访问的核心价值在于:把解析结果从一次性响应变成可管理的数据资产。
例如,工具负责启动任务:
parse_document(document_id="doc-001")
工具返回:
{"task_id": "task-1001","status": "accepted","resource_ids": ["resource://documents/doc-001/manifest"]}
随后,WebUI或Agent再通过资源读取接口获取任务清单、页级内容、表格和图片。
资源访问的优势
第一,适合大结果和多模态结果。
正文、表格、图片、公式可以分别保存,避免所有数据都挤在一次工具响应中。
第二,便于引用和复核。
资源可以携带页码、坐标、来源文件哈希和解析版本,使答案能够追溯到原文。
第三,适合重复使用。
同一个解析结果可以服务于问答、检索、摘要、数据抽取和人工审核,而不必重复解析。
第四,便于版本管理。
当解析策略升级后,可以保留旧版本和新版本,比较差异并支持回滚。
资源访问的局限
资源设计也会带来额外工作:
- 需要规划资源标识;
- 需要管理资源生命周期;
- 需要处理权限继承;
- 需要设计过期、删除和归档策略;
- 需要保证工具返回的资源确实可用;
- 需要解决大文件分片和访问超时问题。
因此,资源并不是工具的替代品,而是对工具执行结果的结构化承载。
五、工具与资源的核心差异
| 对比维度 | MCP工具 | MCP资源 |
|---|---|---|
| 核心定位 | 执行动作 | 提供数据 |
| 典型操作 | 解析、检索、转换、提交任务 | 读取正文、表格、图片、元数据 |
| 调用主体 | 通常由模型或应用主动发起 | 通常由应用、模型或用户按需读取 |
| 返回内容 | 状态、摘要、标识、短结果 | 完整或分层的数据对象 |
| 适合数据量 | 小到中等 | 中到大型 |
| 主要风险 | 参数误用、重复执行、权限越界 | 资源泄露、生命周期失控、版本混乱 |
| 审计重点 | 谁在何时执行了什么动作 | 谁读取了什么资源及哪个版本 |
| 重试方式 | 需要考虑幂等性 | 通常重复读取即可 |
| 典型场景 | 发起解析、刷新索引、生成报告 | 读取解析结果、查看页内容、引用图表 |
| 设计重点 | Schema、权限、超时、幂等 | 标识、版本、访问控制、存储管理 |
从系统设计角度看,工具侧重“改变系统状态”,资源侧重“读取系统状态”。这也是两类接口在权限和可靠性设计上的重要分界。
六、在WebUI中接入MCP工具的通用流程
1. 建立MCP服务端
首先需要准备一个能够提供工具描述和调用处理的MCP服务端。服务端至少要完成以下职责:
- 暴露工具清单;
- 提供工具名称、描述和输入Schema;
- 校验调用参数;
- 验证用户身份;
- 执行动作并返回结果;
- 记录调用日志;
- 对异常进行标准化处理。
如果文档解析服务本身已经存在,可以在其外部增加一层MCP适配层,而不必直接改造底层解析引擎。
2. 在WebUI中注册服务
WebUI通常需要配置以下信息:
- MCP服务地址;
- 通信方式;
- 身份认证信息;
- 是否允许当前模型使用该服务;
- 工具调用超时时间;
- 并发调用限制;
- 是否展示工具执行过程。
配置时应避免把所有工具默认开放给所有模型。更稳妥的方式是按照用户角色、工作空间和业务场景进行授权。
3. 设计少量、明确的工具
工具数量不宜无限增加。过多的相似工具会增加模型选择难度,也会提升维护成本。
例如,与其定义多个高度相似的接口:
parse_pdfparse_scanned_pdfparse_reportparse_research_file
不如通过统一工具配合明确参数表达差异:
parse_document(document_id, mode, page_range, output_policy)
但参数也不能无限堆叠。若一个工具包含大量互相冲突的选项,模型可能难以正确调用。工具设计应遵循单一职责,必要时拆分为“提交任务”“查询状态”“读取结果”三个阶段。
4. 让工具返回资源标识
对于文档解析这类长任务,建议采用异步模式:
提交任务 → 返回任务标识 → 查询状态 → 获取资源清单 → 读取具体资源
伪代码如下:
task = call_tool("parse_document",{"document_id": "doc-001","page_range": "1-20","output_format": "structured"})while task["status"] in ["queued", "running"]:task = call_tool("get_task_status", {"task_id": task["task_id"]})manifest = read_resource(task["manifest_resource"])content = read_resource(manifest["content_resource"])
这种设计比同步返回完整文档更适合生产环境,因为它能够处理长耗时任务、失败重试和用户主动取消。
七、文档解析网关应如何划分边界
一个完整的解析网关可以划分为五层。
第一层:输入治理
负责检查:
- 文件类型;
- 文件大小;
- 页数限制;
- 文件哈希;
- 上传者身份;
- 数据敏感级别;
- 是否允许进入外部处理链路。
输入治理可以减少恶意文件、重复文件和不符合策略的数据进入后续流程。
第二层:解析执行
负责完成:
- 文字识别;
- 版面分析;
- 标题层级识别;
- 表格提取;
- 公式转换;
- 图片抽取;
- 页码与坐标保留。
解析过程中应尽量保留原始来源信息,不要在最早阶段就把所有结构压扁成纯文本。
第三层:结果组织
建议至少提供以下结果层次:
- 文档级元数据;
- 页级内容;
- 段落级内容;
- 表格资源;
- 图片资源;
- 公式资源;
- 解析质量信息;
- 原始文件关联信息。
不同消费者可以读取不同粒度的结果,避免每次都加载完整文档。
第四层:MCP接口层
这一层将内部能力映射为工具和资源:
- 工具用于提交任务、查询状态和触发重处理;
- 资源用于读取解析内容和质量信息;
- 权限系统决定用户能调用哪些工具、读取哪些资源。
第五层:入库与审计层
负责记录:
- 文档哈希;
- 解析版本;
- 模型或算法版本;
- 处理时间;
- 失败原因;
- 人工复核结果;
- 资源访问记录;
- 索引构建状态。
这样才能保证文档进入知识库后仍然可追溯、可复核、可重建。
八、安全、稳定性与运维注意事项
身份认证与权限控制
MCP服务端不能只依赖WebUI前端传递的用户信息。服务端应独立校验身份,并建立资源级权限控制。
例如,同一份文档可能包含公开正文和受限附件,不能因为用户拥有文档列表权限,就默认拥有全部资源的读取权限。
工具幂等性
重新执行解析、生成索引或修改状态的工具,必须考虑重复调用问题。可以使用文档哈希、任务标识和操作标识判断是否已有相同任务正在执行。
超时与取消
解析大型文件可能耗时较长,不能简单依赖单次HTTP请求保持连接。应采用异步任务、状态查询和取消机制,并区分排队、执行、成功、失败和取消等状态。
错误信息
错误信息应便于模型和开发者理解,例如:
{"code": "INVALID_PAGE_RANGE","message": "页码范围超出文档实际页数","retryable": false,"details": {"total_pages": 18}}
其中,retryable 可以帮助调用方判断是否值得自动重试,避免对参数错误进行无效重复调用。
可观测性
至少应记录:
- 工具调用次数;
- 调用用户和来源;
- 参数校验失败次数;
- 平均处理时长;
- 任务排队时长;
- 解析失败率;
- 资源读取量;
- 重试次数;
- 不同版本的结果差异。
这些指标能够帮助定位是模型调用问题、MCP适配问题,还是底层解析问题。
九、不同场景下如何选择
场景一:简单问答和小文件处理
如果文档较小、任务耗时短,工具可以直接返回简要解析结果。此时系统实现简单,接入成本较低。
但仍建议保留文档标识和页码信息,避免后续无法引用来源。
场景二:科研论文和复杂报告
更适合采用“工具提交任务+资源分层读取”的方式。正文、表格、公式和图片应分别管理,Agent根据问题只读取必要资源。
场景三:批量入库
批量任务通常需要异步队列、任务状态、失败重试和结果验收。工具负责启动任务,资源负责承载产物,审计系统负责记录处理链路。
场景四:高敏感数据
应重点关注身份认证、最小权限、资源隔离、访问审计和数据保留期限。对于此类场景,不建议把完整文档内容直接放在工具返回值中。
场景五:开发测试环境
可以先采用较简单的同步工具,快速验证模型是否能够正确选择工具和生成参数。进入生产环境后,再逐步引入异步任务、资源版本和审计能力。
十、迁移和落地时的注意事项
从传统文档解析接口迁移到MCP架构时,不建议一次性重写所有模块,可以按照以下顺序推进:
- 保留原有解析服务;
- 增加MCP适配层;
- 先暴露一个只读查询工具;
- 再增加文档解析任务工具;
- 将大型结果改造成资源;
- 补充权限、审计和监控;
- 最后接入自动重试和版本管理。
迁移过程中需要重点检查:
- 原接口参数是否能映射到清晰的Schema;
- 原返回结果是否适合拆成资源;
- 原有调用方是否依赖某种固定字段;
- 任务失败后是否能够安全重试;
- 旧数据是否具备文档哈希和版本信息;
- 资源删除后是否会影响已有引用;
- 模型是否能够正确区分工具和资源;
- 用户权限是否会因适配层引入而扩大。
总结
在WebUI中使用MCP协议,关键并不是简单地“把几个函数接进来”,而是重新设计Agent与后端能力之间的边界。
- MCP工具适合执行动作,重点关注参数Schema、权限、幂等性、超时和错误处理;
- MCP资源适合承载结果,重点关注资源标识、版本、引用、生命周期和访问控制;
- 对于文档解析、RAG和科研数据处理,推荐采用“工具负责执行,资源负责承载”的组合模式;
- 对于小任务可以采用同步调用,对于复杂文档和批量任务应优先考虑异步处理;
- 生产系统不能只验证接口是否调用成功,还应关注来源追踪、失败重试、人工复核、版本管理和全链路审计。
当文档被组织成可调用、可读取、可引用和可复核的结构化资源后,MCP才真正从“工具连接协议”发展为Agent应用的治理接口。

登录后可评论,请前往 登录 或 注册