AI News HubLIVE
サイト内リライト4 分で読了

LlamaParse MCP: AIエージェントのためのエージェント型OCRツール

LlamaParse Platform MCPがリファクタリングされ、ストレージ・検索からドキュメント処理へ焦点を移しました。本記事では、MCPが公開するツール、接続方法、設計上の決定事項（OAuth認証、ファイルアップロード解決策、可観測性、レート制限など）について説明します。

ソースLlamaIndex Blog

LlamaParseプラットフォームのMCP（Model Context Protocol）は最近リファクタリングされ、その焦点をストレージと検索から、Parse、Classify、Splitサービスを活用したドキュメント処理へと移行しました。この記事では、MCPが公開するツール、接続方法、実装を形作った設計上の決定事項について説明します。

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サーバーの重要なコンポーネントであり、公開するツール、リソース、プロンプトに対するきめ細かなアクセス制御を可能にします。すべての呼び出し元にすべてを公開するのではなく、ユーザーごとの制御が可能です。

さらに、認証によりユーザーIDの確認が可能になり、同じバックエンドを共有するサードパーティサービスとの統合が容易になり、シームレスでセキュアなクロスシステム連携が実現します。

今回の再設計では、Googleをプロバイダーとして使う方式や手動のAPIキー入力を廃止し、WorkOS OAuthを採用しました。これにより、MCP認証はLlamaParseプラットフォーム全体で使用される同一システムと統合されます。

リファレンス実装を基に、MCPサーバー（@vercel/mcp-adapter上に構築）はすべての受信リクエストを検証するよう構成されています。各リクエストはアクセストークンを含む必要があり、トークンはユーザーIDの確認に使用され、LlamaParseプラットフォームAPIへのリクエストのベアラートークンとして下流に渡されます。

OAuthフローは通常数秒で完了し、最初のリクエスト時に自動的にトリガーされます。アクセストークンの有効期限が切れると、クライアントは再認証を促します。

ファイルアップロード

LlamaParseプラットフォームは本質的にファイル中心です。各コアサービス（Parse、Classify、Extract、Split）はファイルを直接操作します。しかし、MCPのコンテキストでは、サーバーがファイルアップロードをネイティブにサポートしていないという課題があります。代わりに、すべてのツールパラメータはモデルが直接生成する必要があり、大規模または不透明なクライアント提供リソースを処理する組み込みメカニズムはありません。

小規模ファイルの場合、base64エンコードというアプローチを検討しました。これにより、LLMがエンコードされたバイトからファイルを再構築して書き込むことができます。技術的には可能で実際に動作しましたが、大きな非効率性が生じます。生のファイルデータをトークンとしてLLMに送信することは、画像を電話でピクセル単位で説明するのに匹敵するほどリソースを消費します。

単純なテキストファイルであっても、base64エンコードはサイズを大幅に増加させ、1文字あたり約1トークンになります。これにより、本来は些細なデータ転送に対して不釣り合いに高い計算コストとコストが発生します。

URLベースのアップロード

これらの制限に対処するため、チャンクアップロードから移行し、2つの補完的なツールを導入しました。

  • uploadFileByUrl：公開ファイルURLを受け入れ、ファイルをバイナリデータとして取得し、LlamaParseプラットフォームに直接アップロードします。このアプローチには固有のSSRFリスクがあります。攻撃者は細工されたURLを提供して内部サービスをプローブしたり、クラウドメタデータを流出させたりする可能性があります。当社の場合、ツールが内部インフラストラクチャやクラウドメタデータエンドポイントにアクセスできない隔離されたネットワークで実行されているため、これらのリスクは軽減されます。
  • getUploadUrl：一時的で認証済みのアップロードエンドポイントを生成し、クライアントは標準のPOSTリクエストでファイルをアップロードできます。

アップロードバイURLフロー（トークンベースのアップロードエンドポイント）

具体的なフロー：

  1. ランダムな48バイトトークン（URLセーフbase64）を生成。
  2. トークンとユーザーの認証コンテキストをTTL 10分でRedisに保存。
  3. ツールは/api/upload/[token]を指すURLを返す。
  4. クライアントはマルチパートフォームデータを使用してこのエンドポイントにファイルを直接アップロード。サーバーはトークンを検証し、関連する認証コンテキストを取得し、ファイルをLlamaParseプラットフォームに転送。成功するとトークンは無効化され、アップロードされたファイルIDが返される。

耐障害性を向上させるため、ファイルIDもRedisに（TTL 1時間）キャッシュされ、トークンに関連付けられます。これにより、同じトークンでの繰り返しリクエストは同じ結果を返します。

直接HTTPツール（bashアクセスなしなど）を持たないエージェントの場合、ユーザーは/upload/[token]にアクセスし、シンプルなUIからファイルをアップロードすることもできます。

可観測性とレート制限

サーバーをプロダクション対応にするため、軽量な可観測性と悪用防止機能を追加しました。すべてのツール呼び出しはOpenTelemetry（@vercel/otel経由）でトレースされ、実行時間、入力、出力、エラーをキャプチャ。スパンはOTLP経由でAxiomにエクスポートされ、エンドツーエンドの可視性を提供します。レート制限は/mcpエントリポイントで実施されます。スライディングウィンドウ戦略を使用し、ユーザーあたり毎分100リクエント。制限を超えたクライアントにはRetry-Afterヘッダーが返され、エージェントはそれをユーザーに直接伝えることができます。

デプロイメント

サーバーはVercel上でNext.jsアプリケーションとして実行され、ファイルアップロードUIとMCPエンドポイントを単一のコードベースに共存させることができます。一時的なアップロードトークンはUpstash経由でRedisに保存されます。プルリクエストは自動的にプレビュー環境にデプロイされます。mainブランチはプロダクションです。

結論

プロダクション対応のMCPサーバーを構築することで、従来のAPI設計では明らかではなかった制約が浮き彫りになりました。認証は既存のプラットフォームIDと整合させる必要があり、ファイル処理はMCPのネイティブアップロード非対応に対する回避策が必要であり、可観測性とレート制限は大規模な安全な運用に不可欠でした。

AIワークフローでLlamaParseツールを使用したい場合は、MCP互換のクライアントをhttps://mcp.llamaindex.ai/mcpに向け、LlamaCloudアカウントでサインインしてください。完全な実装はオープンソースです：https://github.com/run-llama/mcp-llamaindex-ai。