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。