LlamaParse MCP：为AI代理提供智能OCR工具

LlamaParse平台MCP（Model Context Protocol）近期完成了重构，其核心重点从存储和检索转向了文档处理。此次更新全面集成了Parsing、Classify和Split三大服务，为AI代理提供了强大的文档处理能力。

如何使用MCP

LlamaParse MCP服务器现已上线，地址为https://mcp.llamaindex.ai/mcp。任何兼容MCP的客户端都可以连接，并通过LlamaCloud账户登录后立即开始使用。

连接客户端

Claude Desktop：在配置文件~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或%APPDATA%\Claude\claude_desktop_config.json（Windows）中添加：

{"mcpServers": {"llamaparse": {"type": "http", "url": "https://mcp.llamaindex.ai/mcp"}}}

重启Claude Desktop后，运行/mcp命令，选择llamaparse并点击重新认证。

Claude Code：运行命令claude mcp add --transport http llamaparse https://mcp.llamaindex.ai/mcp，然后在Claude会话中执行/mcp，选择llamaparse并在浏览器中完成OAuth流程。

Cursor：在~/.cursor/mcp.json中添加相同配置。

GitHub Copilot (VS Code)：在settings.json中配置。

首次使用时，客户端会重定向到LlamaCloud账户进行认证，OAuth流程只需几秒且令牌会自动刷新。

OAuth认证

认证是MCP服务器的关键组成部分，它实现了细粒度的访问控制，避免了所有工具对调用者无差别开放。此外，认证还支持验证用户身份，为与共享同一后端的第三方服务集成铺平了道路，实现安全无缝的跨系统交互。

本次重构采用了WorkOS OAuth，取代了之前依赖Google或手动输入API密钥的方式，使MCP认证与LlamaParse平台其他部分保持一致。基于参考实现，我们配置了MCP服务器（基于@vercel/mcp-adapter）验证每个请求，每个请求必须包含访问令牌，用于验证身份并作为下游请求的Bearer令牌传递。

OAuth流程通常在几秒内完成，并在首次请求时自动触发。令牌过期后，客户端会提示重新认证。

文件上传挑战与解决方案

LlamaParse平台本质上是文件为中心的：每个核心服务（Parse、Classify、Extract、Split）都直接处理文件。然而，MCP原生不支持文件上传，所有工具参数必须由模型直接生成，缺乏处理大文件或客户端提供资源的内置机制。

对于小文件，我们曾探索base64编码，让LLM从编码字节重建文件。虽然技术可行，但效率低下：传输原始文件数据通过LLM作为令牌非常消耗资源，类似于逐像素描述图像。即使简单的文本文件，base64编码也会显著增大体积，导致高昂的计算和成本开销。

URL上传方案

为解决这些问题，我们放弃了分块上传，引入了两个互补工具：

• uploadFileByUrl：接受公开文件URL，以二进制方式获取并上传至LlamaParse平台。此方法存在SSRF风险，但在我们的场景中，由于工具运行在隔离网络中，且无法访问内部基础设施或云元数据端点，风险得到缓解。

• getUploadUrl：生成临时、认证的上传端点，客户端可通过标准POST请求上传文件。

具体流程：生成48字节随机令牌（URL安全base64），将令牌与用户认证上下文存储到Redis（TTL 10分钟），返回指向/api/upload/[token]的URL。客户端可将文件作为multipart数据直接上传，服务器验证令牌、检索上下文并转发文件至平台。成功后令牌失效，返回上传文件ID。为提升弹性，文件ID也在Redis中缓存（TTL 1小时），重复请求返回相同结果。

对于没有直接HTTP工具（如无bash访问）的代理，用户可访问/upload/[token]通过简单UI上传文件。

可观测性与速率限制

为保证服务器生产就绪，我们加入了轻量级可观测性和滥用防护。每次工具调用都通过OpenTelemetry（@vercel/otel）追踪，捕获持续时间、输入、输出和错误，跨平台导出至Axiom实现端到端可见性。速率限制在/mcp入口点实施：每用户每分钟100请求，采用滑动窗口策略。超限客户端收到Retry-After头，代理可直接反馈给用户。

部署

服务器作为Next.js应用运行在Vercel上，使文件上传UI和MCP端点共置于同一代码库。临时上传令牌通过Upstash存储在Redis。拉取请求自动部署到预览环境，main分支部署至生产。

结语

构建生产级MCP服务器揭示了传统API设计中不明显的约束：认证必须与现有平台身份对齐；文件处理需要针对MCP原生上传支持缺失的变通方案；可观测性和速率限制对于安全大规模运行至关重要。

如果希望在AI工作流中使用LlamaParse工具，只需将任何MCP兼容客户端指向https://mcp.llamaindex.ai/mcp并使用LlamaCloud账户登录即可。完整实现已开源：https://github.com/run-llama/mcp-llamaindex-ai。