多数 MCP 教程只讲「工具返回一段文字」。但真实场景里，智能体常常需要拿到图片、 PDF 、音视频或任意文件——比如让它截图标注、读合同原件、导出报表。 MCP 的内容块（content block）机制本来就支持多模态结果，只是很多人把文件硬塞进文本，结果客户端要么显示不出、要么把二进制搅成一团乱码。本文讲清怎么让 MCP 工具正确返回图片与文件，以及客户端怎么显示、怎么避坑。
MCP 工具返回的是什么
MCP 的工具结果不是单个字符串，而是一组「内容块」。最常见的是文本块，此外还有图片块（image）和资源块（resource）。文本块承载结论，图片块直接内嵌一张图，资源块则指向一个可被客户端取用的文件或数据。理解这套结构，是把多模态结果交给智能体的前提。如果还没建立 MCP 的整体概念，可以先看 MCP 入门教程，把客户端、服务端和内容协议的关系理顺。
返回图片：base64 还是 URI
小图（如图表、标注截图）直接用 image 内容块，带上 base64 数据与正确的 MIME 类型（如 image/png），客户端能原地渲染。但大图或私有资源不要 base64 内联——它会被序列化成超长字符串，撑爆上下文还拖慢传输。正确做法是返回一个 resource_link 或一个带鉴权的 https URI，让客户端按需拉取。关于结果如何被客户端呈现，MCP 工具结果渲染 里专门讲过不同内容类型的展示约定，写服务端时应对照。
返回文件：用 Resource 而非塞进文本
PDF 、 CSV 、音视频这类二进制，绝不能用文本块硬装。正确姿势是作为 embedded resource（直接内嵌且带 URI 与 MIME）或 resource_link（给一个可拉取的地址）。客户端拿到后会渲染预览或提供下载，智能体也能在后续步骤里引用这个资源 URI 。资源的定义与生命周期在 MCP 资源与提示指南 里有系统说明，多模态工具本质上是把文件当资源来暴露。
客户端怎么显示多模态结果
不同客户端对内容块的支持差异很大：Claude Desktop 对 image 块原生渲染，Cursor 在某些传输下对 resource 的处理不同，自建客户端更要自己实现解析。写完多模态工具，务必在目标客户端上实测，而不是只看服务端日志「返回成功」。传输层也会影响大资源的稳定性，MCP stdio 与 HTTP 传输 讲明了两种模式下的限制，大文件场景建议走 HTTP 流式而非 stdio 。
避坑：体积、隐私与超时
三个高频坑：一是 base64 让结果体积膨胀约三分之一，大文件务必走 URI；二是敏感文件（合同、报表）要带鉴权和过期策略，别把内网资源裸奔成公开链接；三是超大资源会拖垮单次工具调用，触发客户端超时。把多模态工具收敛一层网关，统一做鉴权、限流和格式转换，能大幅降低踩坑概率，做法可参照 MCP 网关代理指南。
- 分清类型：文本用 text 块，图片用 image 块，文件用 resource 块，别混装。
- 小图内联：小图表用 base64 + 正确 MIME 的 image 块，客户端可原地渲染。
- 大文件走 URI：大图或私有资源返回 resource_link 或鉴权 https URI，按需拉取。
- 客户端实测：在目标客户端验证 image/resource 真正渲染，不只看服务端日志。
- 加网关护栏：统一做鉴权、限流与格式转换，规避体积、隐私与超时问题。
常见问题
MCP 工具能直接返回图片吗？
返回 PDF 或 CSV 该用什么块？
为什么服务端返回成功，客户端却显示不出？
大文件直接 base64 内联有什么后果？
评论 (0)