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。