Claude Desktop、Cursor、エージェントワークフローのための最も簡単なホステッドマルチモーダルRAG MCPサーバー
たった1つのnpxコマンド。Gemini File Search搭載。PDF、スクリーンショット、チャート、図、画像をネイティブに処理し、検証可能な引用を提供します。
Claude、Cursor、Windsurf、カスタムエージェントにホステッドマルチモーダルRAGを追加する最も簡単な方法。
超簡単セットアップ: npx -y @calypsohq/multimodal-rag-mcp-server --api-key sk-your-key-here
真のマルチモーダルRAG: Gemini File Searchを通じてテキストとビジュアルをネイティブに処理
アップロードとクエリ: 永続的なナレッジファイルとバッチアップロードのための専用ツール
マルチターン会話: /newリセットによるコンテキストを考慮した回答
発見可能なワークフロー: 安全なRAG、アップロード、取り込みフローのためのリソースとプロンプト
GitHub | Docs | Smithery | Official MCP Registry
タグ: multimodal-rag, easiest-mcp-rag, gemini-rag, hosted-rag-mcp, mcp-server
各エージェントやワークフローを一回限りのドキュメント検索スタックに接続する代わりに、このMCPを再利用可能な回答レイヤーへのエージェント向けエントリポイントとして使用します。ソース資料を一度アップロードし、テキストとビジュアルコンテンツを横断して取得し、ユーザーが検証できる証拠付きの回答を返します。
# One-liner with npx
npx -y @calypsohq/multimodal-rag-mcp-server --api-key "sk-your-key-here"または環境変数を使用:
CALYPSO_API_KEY="sk-..." npx -y @calypsohq/multimodal-rag-mcp-server次に、以下の設定例を使用して、同じコマンドをClaude Desktop、Cursor、またはSmitheryに追加します。
Related MCP server: RAG-Anything MCP Server
Calypsoは、最も簡単なホステッドマルチモーダルRAG MCPサーバーを求めるチーム向けに構築されています。ローカルベクタースタック、Docker Compose、カスタムOCRや画像処理パイプラインは不要で、エージェントが根拠のある質問をする前に準備する必要はありません。
機能 | Calypso | rag-anything-mcp | Pixeltable |
セットアップ | 1つのnpxコマンド（インフラ不要） | Clone + Python | Docker Compose |
マルチモーダル | ネイティブGemini File Search（テキスト+画像、チャート、図、PDF）追加のビジョンパイプライン不要 | 強力なOpenAIビジョンベースのドキュメントRAG | ビデオ、オーディオ、画像、テーブルに最適 |
ホスティング | 完全ホステッド（セルフホストオプションあり） | ローカルファースト | ローカルファースト |
運用 | ゼロ運用クラウド | Pythonセットアップが必要 | Dockerが必要 |
アップロードツール | 組み込みのアップロードセッション単一ファイルおよびバッチナレッジツール | あり | あり |
引用 / グラウンディング | 取得メタデータ付きの強力なエビデンストレイル | あり | あり |
最適な用途 | MCPクライアント向けのゼロ運用ホステッドマルチモーダルRAGを求めるチーム | ローカルドキュメントRAG実験 | 重いローカルビデオ/オーディオ/データワークフロー |
最も簡単なホステッドマルチモーダルRAG MCPサーバーを求めるなら、ここから始めてください。
マルチターンメモリを備えた本番マルチモーダルRAGエージェント
単一ファイルおよびバッチナレッジアップロード用の組み込みアップロードツール
チームのRAGバリアントとナレッジバケットの自動検出
ソース参照と取得メタデータ付きの検証可能な引用
安全なワークフローのための読み取り専用リソースと再利用可能なプロンプト
ほとんどの企業ナレッジはテキストだけではありません。答えはセットアップスクリーンショット、PDFテーブル、製品図、ヘルプセンターページ、レポート内のチャートなどに分散していることがよくあります。Calypsoはその全知識面を単一の取得レイヤーにパッケージ化し、エージェントが一般的なモデルメモリから推測することなく、根拠のある質問をできるようにします。
ユーザーが実際に頼る形式を検索: ドキュメント、PDF、スクリーンショット、チャート、図、製品画像、サポート記事、マニュアル、ポリシー、FAQ、レポート。
モデルが書く前に回答をグラウンド: Gemini File Searchが関連するテキストとビジュアルコンテキストを最初に取得し、その後RAGエージェントがそのソース資料から回答します。
エビデンストレイルを表示: 応答にはソース参照、ページ対応グラウンディング、取得メタデータを含めることができ、ユーザーは信頼する前に検証できます。
メタデータで取得をスコープ: ワークスペース、チーム、顧客、言語、ファイルタイプ、ステータス、その他のメタデータを使用して、ナレッジベースを複製せずに回答の関連性を維持します。
同じナレッジレイヤーをどこでも再利用: Cursor、Claude Desktop、AIエージェント、n8nワークフロー、製品UI、サポートフロー、ウェブサイト体験を同じソースバックレイヤーに接続します。
実際には、エージェントは次のような質問に答えることができます:
「このセットアップスクリーンショットと添付のポリシーPDFを説明してください。サポート担当者は次に何をすべきですか？」
「このオンボーディングPDFは承認ルールについて何と言っていますか？」
「このセットアップ画面が失敗するのはなぜですか？」
「価格チャートをプランドキュメントと比較して、適切なティアを推奨してください。」
「このサポートチケットに適用されるポリシーを要約してください。」
「価格ドキュメントに基づいて、この顧客に合う製品プランはどれですか？」
「図示された取り込みフローと取得フローを比較してください。」
calypso-rag-agentを使用すると:
設定されたCalypsoナレッジベースに対して根拠のある質問をする
オプションのmodel引数で検出された任意のチームRAGバリアントを選択する
ネイティブの/v1/responses会話モデルを介してマルチターン会話を続ける
/newで会話コンテキストをリセットする
calypso-rag-agentを提供するのと同じOpenAI互換Responsesエンドポイントを使用する
サポートされているCalypsoワークフロー用の組み込みリソースとプロンプトを発見する
Node.js 18+
サーバーはAPI呼び出しとSDK互換性のためにWeb Fetch APIプリミティブ（fetch、Headers、Request、Response、FormData、Blob、File）を使用します。パッケージは起動時にNode 18+ Web APIサーフェスの一部のみを公開するMCPランタイムのために欠落しているグローバルをブートストラップします。
以下を公開するCalypso APIエンドポイント:
POST /v1/responses
GET /v1/rag-agent/models
GET /v1/knowledge/buckets
POST /v1/knowledge/files/upload-session
POST /v1/knowledge/files/upload-session/{session_id}/finalize
POST /v1/knowledge/files:batch/upload-session
POST /v1/knowledge/files:batch/upload-session/{batch_id}/finalize
GET /v1/knowledge/batches/{batch_id}
Calypso APIキー（sk-...）
環境変数:
CALYPSO_API_KEY（必須）
CALYPSO_API_BASE_URL（オプション、デフォルト https://api.calypso.so/v1）
CLIフラグ:
--api-key
--api-base-url
設定の優先順位:
CLIフラグ / Smithery提供のコマンド引数
環境変数
デフォルトのベースURL（https://api.calypso.so/v1）
npx -y @calypsohq/multimodal-rag-mcp-server --api-key "sk-..."env CALYPSO_API_KEY="sk-..." CALYPSO_API_BASE_URL="https://api.calypso.so/v1" npx -y @calypsohq/multimodal-rag-mcp-server次のような新しいMCPサーバー（コマンドタイプ）を追加します:
npx -y @calypsohq/multimodal-rag-mcp-server --api-key sk-... --api-base-url https://api.calypso.so/v1Claude Desktopで:
Claude -> Settings -> Developer -> Edit Config
macOSでは、ファイルは通常:
~/Library/Application Support/Claude/claude_desktop_config.jsonClaude DesktopはデスクトップMCPサーバーにclaude_desktop_config.jsonを使用します。Claude Codeは~/.claude.jsonやプロジェクトレベルの.mcp.jsonなどの別の設定場所を使用します。
これをclaude_desktop_config.jsonに貼り付けます:
{
"mcpServers": {
"Calypso Multimodal RAG": {
"command": "npx",
"args": [
"-y",
"@calypsohq/multimodal-rag-mcp-server"
],
"env": {
"CALYPSO_API_KEY": "sk-your-calypso-api-key",
"CALYPSO_API_BASE_URL": "https://api.calypso.so/v1"
}
}
}
}置き換え:
sk-your-calypso-api-key
を実際のCalypso APIキーに置き換えます。
Claude Desktopを完全に終了し、再度開きます。
ウィンドウを閉じるだけでは不十分です。macOSでは:
Cmd + Q再起動後、MCPがClaudeに表示され、次のツールが利用可能になります:
calypso-rag-agent
calypso-list-buckets
calypso-upload-file
calypso-upload-files-batch
CalypsoはホステッドマルチモーダルRAGツールを提供します。生成されたレポート、サマリー、CSV、JSONファイル、ウェブ検索アーティファクトをローカルコンピュータに直接書き込むことはありません。
Claude Desktopが生成ファイルをローカルに保存できるようにするには、Calypsoと一緒に標準のfilesystem MCPサーバーを追加し、専用の安全なフォルダに制限します。
最初にフォルダを作成します:
mkdir -p ~/Claude次に、両方のサーバーをclaude_desktop_config.jsonに追加します:
{
"mcpServers": {
"Calypso Multimodal RAG": {
"command": "npx",
"args": [
"-y",
"@calypsohq/multimodal-rag-mcp-server"
],
"env": {
"CALYPSO_API_KEY": "sk-your-calypso-api-key",
"CALYPSO_API_BASE_URL": "https://api.calypso.so/v1"
}
},
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/Users/yourname/Claude"
]
}
}
}設定変更後、Claude Desktopを完全に終了して再度開きます。
プロンプト例:
Use Calypso for the grounded RAG answer, then save the final report as /Users/yourname/Claude/report.md using the filesystem tool.安全性のため、filesystemアクセスは~/Claudeなどの専用フォルダにのみ許可し、ホームディレクトリ全体には許可しないでください。
懸念事項 | 最適な所有者 |
ソースバックのRAG回答 | Calypso MCP |
Calypsoへのファイルアップロード | Calypso MCP |
| filesystem MCP |
Claudeからのウェブ検索アーティファクト | Claude plus filesystem MCPプロンプト |
サーバーはSmitheryで利用可能で、デスクトップクライアントが使用するのと同じnpxパッケージパスを通じて起動します。
Smitheryユーザー設定:
calypsoApiKey（必須）
calypsoApiBaseUrl（オプション、デフォルト https://api.calypso.so/v1）
Smithery起動パスは次と同等です:
npx -y @calypsohq/multimodal-rag-mcp-server --api-key sk-... --api-base-url https://api.calypso.so/v1calypsoApiBaseUrlは、セルフホストのCalypso互換デプロイメントを対象とする場合にのみ使用します。クラウドデフォルトはオーバーライドする必要はありません。
APIキーが見つからない: --api-key または CALYPSO_API_KEY を指定してください
APIホストが誤っている: --api-base-url / CALYPSO_API_BASE_URL が /v1 で終わっていることを確認してください
セルフホスト型デプロイ: https://api.calypso.so/v1 を使用していない場合のみベースURLを上書きしてください
Smithery起動時の不一致: 新規クローンから node dist/index.js を実行するのではなく、パッケージ化された npx -y @calypsohq/multimodal-rag-mcp-server パスを使用してください
FormData is not defined または Headers is not defined: 最新のパッケージにアップグレードしてください。MCPサーバーはアップロードツールが実行される前に、欠落しているWeb Fetch APIグローバルをブートストラップします。
/mnt/user-data/uploads/... のENOENT: そのパスはホスト型エージェントまたは添付ファイルサンドボックスに属するものであり、必ずしもMCPサーバーに属するものではありません。filePath の代わりに contentBase64 で再試行してください。
ローカル成果物の保存: Calypsoの回答はClaude Desktopのfilesystem MCPサーバーで使用できますが、最終出力を許可されたローカルパスに保存するようClaudeに明示的に依頼する必要があります。
filePath と contentBase64 の使い分けローカルMCPインストールでは filePath を使用してください。Claude DesktopやCursorの設定で、このパッケージを次のようなローカルコマンドで起動する場合が該当します:
npx -y @calypsohq/multimodal-rag-mcp-serverこの設定では、MCPサーバープロセスはお使いのマシン上で実行され、同じユーザーアカウントがアクセスできるパスを読み取ることができます。ローカルパスを直接渡してください。サーバーが生のバイトを読み取り、CalypsoのアップロードセッションURLを通じてアップロードします。ローカルファイルをbase64エンコードする必要はありません。
ホスト型またはリモートのMCPクライアントでは contentBase64 を使用してください。Smitheryホスト型サーバー、ブラウザ/クラウドランタイム、生成されたインメモリコンテンツ、エージェントコンテナなどが該当します。これらの環境では、Macやワークステーション上のパスはMCPサーバープロセスから読み取ることができません。
パスが /mnt/user-data/uploads、/mnt/data、/mnt/attachments、またはその他のホスト型サンドボックスプレフィックスで始まる場合、このMCPサーバーが同じサンドボックス内で実行されていない限り、それを filePath として送信しないでください。代わりに contentBase64 またはその他のインラインバイトソースを使用してください。
calypso-rag-agentCalypso RAGエージェントへの直接アクセス。
注意事項:
他のペルソナやエージェントへの自動ルーティングは行いません。
起動時にAPIキーで利用可能な calypso-rag-agent バリアントを自動的に検出します。
オプションの model 引数を使用して、calypso-rag-agent:pricing などの名前付きバリアントを選択できます。
各モデルバリアントは独自のMCP会話チェーンを保持するため、バリアントを切り替えても誤ったスレッドが継続されることはありません。
POST /v1/chat/completions ではなく POST /v1/responses を使用します。
最初のターンで名前付き会話が作成され、フォローアップターンは previous_response_id でチェーンされます。
オプションの fileIds は、取得スコープの質問でサポートされています。新しいアップロードは、永続的なナレッジアップロードツールを使用し、質問する前にインデックス作成を待つ必要があります。
プロンプトとして /new を使用すると、MCP会話をリセットできます。
calypso-list-buckets設定されたCalypso APIキーに紐づくチームのバケットを一覧表示します。
注意事項:
GET /v1/knowledge/buckets を使用します。
team_id は受け付けません。CalypsoはAPIキーからチームスコープを導出します。
バケットID、スラッグ、名前、ステータス、メンバー数、ソース数、バケットストアの準備状態を返します。
デフォルトではアクティブなバケットのみを返します。監査やクリーンアップでアーカイブ済みバケットが必要な場合は、includeArchived: true を渡してください。
宛先バケットを選択する必要がある場合は、calypso-upload-file または calypso-upload-files-batch の前にこれを使用してください。
calypso://rag-agent-models は、各RAGバリアントにどのバケットがバインドされているかを回答します。calypso-list-buckets は、APIキーのチームにどのバケットが存在するかを回答します。
例:
{
"includeArchived": false
}calypso-get-fileファイルIDで1つのナレッジファイルのメタデータとインデックス作成ステータスを取得します。
注意事項:
GET /v1/knowledge/files/{file_id} を使用します。
calypso-list-buckets の不透明な fileIds を、ファイル名、MIMEタイプ、サイズ、インデックス作成ステータス、バケットごとの同期状態に解決します。
verify: true を渡すと、プロバイダー（?verify=gemini）に対してクロスチェックします。遅くなりますが、ステータスが古いように見える場合の信頼できる情報源です。
例:
{
"fileId": "file_123",
"verify": true
}calypso-create-bucket作成してから入力するワークフローのために、空のバケットを作成します。
注意事項:
POST /v1/knowledge/buckets を使用します（このエンドポイントがデプロイされたバックエンドと、APIキーの knowledge:bucket:create 機能が必要です）。
サーバーはスラッグを正規化します。衝突すると、型付きの bucket_slug_exists エラーが返されます。
idempotencyKey のリプレイは、エラーにする代わりに既存のバケットを返します。
アップロードは bucketSlugs + createMissingBuckets を介してバケットを暗黙的に作成することもできます。このツールは、宛先を先に作成するために存在します。
例:
{
"name": "Product docs",
"slug": "product-docs",
"idempotencyKey": "create-product-docs-1"
}calypso-create-agent1つ以上のバケットにバインドされたRAGエージェントバリアントを作成します。
注意事項:
POST /v1/rag-agent/agents を使用します（このエンドポイントがデプロイされたバックエンドと、APIキーの rag:agent:create 機能が必要です）。
成功ペイロードは model で始まります。それをそのまま calypso-rag-agent に渡してください。
バケットバインディングはサーバー側で検証されます。不明またはアーカイブ済みのバケットは bucket_not_found を返し、エージェントIDの衝突は agent_id_exists を返し、プランのエージェント上限は agent_limit_reached を返します。
エージェントを作成するとモデルカタログが更新され、MCPの tools/list_changed および resources/list_changed 通知が発行されるため、再接続せずに新しいバリアントを使用できます。
例:
{
"agentId": "support",
"name": "Support agent",
"bucketSlugs": ["product-docs"],
"idempotencyKey": "create-support-agent-1"
}calypso-upload-fileファイルを永続的なバケットバックアップ型ナレッジストアとインデックス作成パイプラインにアップロードします。
注意事項:
POST /v1/knowledge/files/upload-session を使用し、バイトをストレージに直接アップロードしてから、POST /v1/knowledge/files/upload-session/{session_id}/finalize でファイナライズします。
アップロードはJSONセッションリクエストと署名付きバイナリ PUT を使用します。マルチパートフォームアップロードではありません。
チャット添付ファイルの file_id ではなく、ファイルとタスクのメタデータを返します。
bucketIds、bucketSlugs、または bucket を介して1つのバケット宛先が必要です。
サーバーがパスを読み取れるローカルClaude Desktop/Cursor MCPインストールでは filePath を使用してください。ローカルパスを読み取れないホスト型またはリモートのMCPクライアントでは contentBase64 を使用してください。
エージェントが /mnt/user-data/uploads/file.pdf のようなパスを見た場合、それを filePath として送信せず、ファイルバイトを contentBase64 として送信する必要があります。
オプションの title、tags、metadata、idempotencyKey をサポートします。
bucketIds または bucketSlugs で既存のバケットにアップロードをルーティングするか、bucket を単一スラッグのショートカットとして使用します。
アップロード中にCalypsoに欠落した宛先を作成させたい場合は、バケットスラッグとともに createMissingBuckets: true を渡してください。
オプションで、返す前にインデックス作成が準備完了状態に達するまで待機できます。
例:
{
"filename": "handbook.pdf",
"mimeType": "application/pdf",
"filePath": "/Users/me/Documents/handbook.pdf",
"bucket": "support-handbook",
"createMissingBuckets": true,
"waitForIndexing": true
}calypso-upload-files-batch1回のリクエストで1〜100個のファイルを永続的なナレッジストアにアップロードします。
注意事項:
POST /v1/knowledge/files:batch/upload-session を使用し、受け入れられた各アイテムをストレージに直接アップロードしてから、POST /v1/knowledge/files:batch/upload-session/{batch_id}/finalize でファイナライズします。
アップロードはJSONセッションリクエストと署名付きバイナリ PUT を使用します。マルチパートフォームアップロードではありません。
batchIdempotencyKey が必要です。Calypsoはこれを使用して、再試行用の永続的なバッチIDを導出します。
すべてのアイテムが独自のバケット宛先を提供しない限り、bucketIds、bucketSlugs、または bucket を介した共有バケット宛先が必要です。
共有の bucketIds、bucketSlugs、bucket、createMissingBuckets のデフォルトと、アイテムごとのオーバーライドをサポートします。
サーバーが各パスを読み取れるローカルClaude Desktop/Cursor MCPインストールでは、アイテムごとの filePath を使用してください。ローカルパスを読み取れないホスト型またはリモートのMCPクライアントでは、アイテムごとの contentBase64 を使用してください。
clientFileId が省略された場合、Firestoreセーフな client_file_id 値を生成します。
accepted または queued はアップロードが永続的であることを意味し、必ずしもクエリ可能であることを意味しません。waitForBatchReady: true を使用して GET /v1/knowledge/batches/{batch_id}?include_items=true をポーリングしてください。
アイテムごとのステータス、bucketSyncStatus、bucketSync を検査して、インデックス済みコンテンツとバケット準備完了の取得を区別してください。
例:
{
"batchIdempotencyKey": "kb-seed-2026-06-04",
"bucket": "support-handbook",
"createMissingBuckets": true,
"items": [
{
"filename": "faq.txt",
"mimeType": "text/plain",
"filePath": "/Users/me/Documents/faq.txt"
}
],
"waitForBatchReady": true
}calypso://server-infoパッケージバージョン、APIベースURL、トランスポート、認証モデル、公開された機能を含む、読み取り専用のサーバーメタデータ。
calypso://rag-agent-models設定されたAPIキーから検出された、チームスコープの calypso-rag-agent モデルバリアントの読み取り専用ランタイムカタログ。各バリアントのアクティブな buckets、bucket_ids、missing_bucket_ids が含まれます。検出が利用できない場合、このリソースは基本の calypso-rag-agent にフォールバックします。
calypso://buckets設定されたAPIキーに紐づくチームのナレッジバケットの読み取り専用ランタイムリスト。アップロード前にバケットID/スラッグとバケットストアの準備状態を検査するために使用します。
calypso://workflowsサポートされているRAGおよびファイルアップロードワークフローの簡潔なガイド。
calypso://securityAPIキー、ローカルファイル読み取り、アップロード、ロギングに関する運用上のセキュリティメモ。
calypso-question: calypso-rag-agent 用の根拠に基づくナレッジベースの質問をドラフトします
calypso-ingestion: 永続的なナレッジストアのアップロードとフォローアップクエリを準備します
calypso-reset-conversation: /new でクリーンなRAGスレッドを開始します
トピックの要約:
キャンペーン承認に関するナレッジベースのガイダンスを要約してください
特定の回答を求める:
ドキュメントはインデックス作成の再試行について何と言っていますか?
2つの概念の比較:
現在のアーキテクチャでファイルインデックス作成と取得実行を比較してください
新しいスレッドを開始:
/new
前の回答の絞り込み:
取り込みパスのみに焦点を当て、取得は無視してください
ソースまたは根拠を求める:
どのドキュメント化されたコンポーネントが関与し、その理由を説明してください
バケットの検出:
宛先を選択する前に calypso-list-buckets を呼び出すか、calypso://buckets を読み取ってください
永続的なナレッジのアップロード:
ファイルペイロードとオプションの title、tags、metadata を指定して calypso-upload-file を呼び出してください
ローカルClaude Desktop/Cursor MCPインストールでは filePath を優先し、ローカルパスを読み取れないホスト型またはリモートのMCPクライアントでは contentBase64 を使用してください
ナレッジをバケットにルーティング:
1つの宛先には bucket: "support-handbook"、複数のスラッグベースの宛先には bucketSlugs、安定したバケットIDがすでにある場合は bucketIds を使用してください
バケット宛先をオンデマンドで作成:
スラッグベースのバケット割り当てを使用していて、宛先がまだ存在しない可能性がある場合は、createMissingBuckets: true を追加してください
インデックス作成を待機:
ナレッジファイルがインデックス作成されるまでツールをブロックしたい場合は、waitForIndexing: true を渡してください
多数の永続ファイルをアップロード:
ローカルMCPインストールでは items、batchIdempotencyKey、アイテムごとの filePath を指定して calypso-upload-files-batch を呼び出してください。ホスト型またはリモートのMCPクライアントではアイテムごとに contentBase64 を使用してください
バッチをバケットにルーティング:
共有の bucket、bucketSlugs、bucketIds、または createMissingBuckets をツール呼び出しに置き、必要な場合のみアイテムごとにオーバーライドしてください
クエリ準備完了を待機:
waitForBatchReady: true を使用し、新しいコンテンツをクエリする前に、返されたアイテムステータスとバケット同期フィールドを検査してください
最初からやり直す: /new を使用してMCP会話をリセットします（新しい conversation_id + クリアされた応答チェーン）。
[CALYPSO LIST KNOWLEDGE BUCKETS] Lists knowledge buckets for the team tied to the configured Calypso API key.
Use this before uploads when you need bucket ids, slugs, names, member counts, or bucket-store readiness. This complements RAG model discovery: model discovery shows which buckets are bound to each agent variant, while this tool lists all buckets for the API key team.
| Name | Required | Description | Default |
|---|---|---|---|
| includeArchived | No | If true, include archived buckets. Defaults to false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of disclosing behavior. It indicates a read-only listing operation and clarifies scope (team tied to the API key), but does not disclose potential rate limits, pagination, or default behavior nuances beyond the schema. It is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the core action. The bracketed header repeats the tool name, adding slight redundancy, but every other sentence contributes meaningful usage context. It earns a high score for efficiency without unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with no output schema, the description provides a complete picture of purpose, usage context, and relationship to other tools. It hints at return values by listing retrievable fields, but does not explicitly describe the response format (e.g., array of objects). This is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with the includeArchived parameter already described in the schema. The description does not add parameter-specific meaning beyond the schema, only mentions the types of data returned (bucket ids, slugs, etc.), which are not directly parameter semantics. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('Lists'), resource ('knowledge buckets'), and scope ('for the team tied to the configured Calypso API key'). It also differentiates from sibling tools by explaining its use before uploads and how it complements model discovery.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: 'Use this before uploads when you need bucket ids, slugs, names, member counts, or bucket-store readiness.' It also contrasts with RAG model discovery. However, it lacks explicit when-not-to-use or alternative tool exclusions, so it falls short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[CALYPSO RAG AGENT] Sends each prompt directly to the Calypso RAG agent using the full conversation context.
Use this when you want Calypso knowledge retrieval and grounded answers from the RAG backend. Typical requests:
"Summarize the key points from our onboarding documentation"
"What does the knowledge base say about campaign approval rules?"
"Compare the documented indexing flow with the retrieval flow"
"Answer using the uploaded file ids: ["file_123"]"
Responses API behavior:
First turns start a named Calypso conversation via /v1/responses.
Follow-up turns chain with previous_response_id so the backend owns conversation state.
When fileIds are provided, the MCP uses rag_policy retrieval semantics instead of inline attachment stuffing.
MCP session behavior:
This tool maintains a stable conversation id in the background for multi-turn retrieval context.
Use /new to start a fresh conversation and clear the current context window.
Quick commands (examples):
"Summarize the latest indexed knowledge about WhatsApp templates"
"Find the source of truth for campaign approval behavior"
"Start a new topic" (or use /new)
Available RAG models: calypso-rag-agent.
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | Optional RAG model variant. Defaults to `calypso-rag-agent`. Available models: calypso-rag-agent. | |
| prompt | Yes | Your request. Include context, constraints, and desired output. | |
| fileIds | No | Optional uploaded agent-store `file_id` values to attach with `rag_policy` retrieval semantics. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully explains behavior: maintains conversation state, chains follow-up turns via previous_response_id, uses rag_policy for fileIds, and supports /new to reset context. This goes well beyond what the schema reveals.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is fairly long but organized into sections (Responses API, MCP session, quick commands). Every section adds value, though some repetition (model name listed twice) and length could be trimmed slightly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and no output schema/annotations, the description covers conversation state, file handling, and usage examples. Missing return format details, but the overall context is sufficiently complete for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining fileIds trigger rag_policy retrieval semantics, and clarifies model default. This enriches the parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool's verb and resource: 'Sends each prompt directly to the Calypso RAG agent using the full conversation context.' It clearly distinguishes this from sibling tools (which list/upload knowledge files) by focusing on retrieval and grounded answers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit usage context: 'Use this when you want Calypso knowledge retrieval and grounded answers from the RAG backend.' It provides typical request examples and quick commands. However, it does not explicitly mention when NOT to use it or name alternative tools for other actions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[CALYPSO UPLOAD KNOWLEDGE FILE] Uploads a file into the durable bucket-backed knowledge store and indexing pipeline.
Use this when you want a file indexed into the broader knowledge corpus instead of
attached directly to a single RAG chat turn. This tool returns knowledge-file and task metadata.
A bucket destination is required: pass bucketIds, bucketSlugs, or bucket.
Choose exactly one file source. Use filePath when this MCP server runs locally and can read the path, including Claude Desktop or Cursor configs that launch this package with npx. Use contentBase64 for hosted or remote MCP clients, browser uploads, generated in-memory content, or remote sandbox files that this MCP process cannot read. Do not base64-encode local files just to use this tool.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Optional tags for knowledge-store organization. | |
| title | No | Optional human-readable title stored with the knowledge file. | |
| bucket | No | Convenience single bucket slug for this upload. Required unless bucketIds or bucketSlugs is provided. | |
| filePath | No | Preferred for local MCP installs, including Claude Desktop and Cursor configs that run this package with a local command such as npx. Absolute or relative path readable by the machine running this MCP server. The server reads raw bytes and uploads them through the Calypso upload-session URL; no user-side base64 conversion is needed. | |
| filename | Yes | Display filename for the uploaded knowledge file. | |
| metadata | No | Optional metadata object serialized onto the upload request. | |
| mimeType | Yes | Content type for the uploaded knowledge file. | |
| bucketIds | No | Existing knowledge bucket ids to assign this upload to. Required unless bucketSlugs or bucket is provided. | |
| bucketSlugs | No | Knowledge bucket slugs to assign this upload to. Required unless bucketIds or bucket is provided. | |
| contentBase64 | No | Inline file bytes as base64. Use when filePath is not possible, such as hosted or remote MCP servers, browser-provided files, generated content, or remote sandbox attachment paths that the MCP process cannot read. | |
| idempotencyKey | No | Optional idempotency key for durable upload retries. | |
| waitForIndexing | No | If true, wait until indexing reaches a terminal ready state before returning. | |
| createMissingBuckets | No | If true, create missing bucket slugs before assignment. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the durable bucket-backed nature, the indexing pipeline, return metadata, the requirement to choose exactly one file source, and explains how filePath avoids base64 conversion. It also mentions idempotency for retries. Some aspects like error conditions or permission needs are not covered, but the description adds significant behavioral context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and then efficiently covers usage guidance, parameter selection, and constraints in a compact block. Every sentence adds value; no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite 13 parameters and no output schema, the description is complete: it states what the tool returns, when to use each source parameter, bucket requirements, and optional behaviors like waitForIndexing and createMissingBuckets. It addresses the complexity effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds substantial meaning: it explains the trade-offs between filePath and contentBase64, clarifies the bucket alternatives (bucketIds, bucketSlugs, bucket), and notes the idempotency key's purpose. This goes beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Uploads a file into the durable bucket-backed knowledge store and indexing pipeline', which is a specific verb+resource action. It also distinguishes from siblings by noting this is for the broader knowledge corpus rather than a single RAG chat turn, and indirectly from the batch upload tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: 'Use this when you want a file indexed into the broader knowledge corpus instead of attached directly to a single RAG chat turn.' It also details when to use filePath vs contentBase64 with concrete examples (local vs hosted/remote), and implies batch tool for multiple files. No alternatives are excluded but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[CALYPSO UPLOAD KNOWLEDGE FILES BATCH] Uploads 1 to 100 files into the durable knowledge store and indexing queue in one request.
Use this for bulk corpus ingestion. Shared bucket fields apply to every item unless an item
provides its own bucket fields. The tool returns batch-level status and, when requested,
polls until the batch reaches active, partially_active, partially_failed, failed, or timeout.
A shared bucket destination is required unless every item provides its own bucket destination.
Choose exactly one file source per item. Use filePath when this MCP server runs locally and can read each path, including Claude Desktop or Cursor configs that launch this package with npx. Use contentBase64 for hosted or remote MCP clients, browser uploads, generated in-memory content, or remote sandbox files that this MCP process cannot read. Do not base64-encode local files just to use this tool.
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | Knowledge files to upload in this batch. | |
| bucket | No | Convenience single bucket slug applied to all items by default. Required unless every item has a bucket destination. | |
| bucketIds | No | Existing bucket ids applied to all items by default. Required unless every item has a bucket destination. | |
| bucketSlugs | No | Bucket slugs applied to all items by default. Required unless every item has a bucket destination. | |
| waitForBatchReady | No | If true, poll batch status with include_items=true until terminal or timeout. | |
| batchIdempotencyKey | Yes | Required idempotency key used to derive the durable batch id. | |
| createMissingBuckets | No | If true, create missing shared bucket slugs before assignment. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses write side-effects (durable store, indexing queue), batch status return, optional polling with terminal states, and bucket field override rules. It does not mention all possible failure semantics or idempotency behavior in depth, but the core workflow is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than minimal but every sentence serves a purpose: purpose, usage, file-source selection, bucket rules, and status behavior. It is well-structured and front-loaded with the main action, then details, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema or annotations, the description is remarkably complete: it covers the tool's operation, return behavior, polling, and preconditions (bucket destination). It could add more on error handling or what 'batch-level status' contains, but it covers the essentials for a batch upload tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds important contextual meaning: when to use filePath vs contentBase64, and that shared bucket fields are overridden by item-specific fields. This enriches parameter understanding beyond the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool uploads 1 to 100 files into the durable knowledge store and indexing queue in one request, with the explicit use case of bulk corpus ingestion. This distinguishes it from the sibling single-file upload tool by scope and batch behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage guidance: use for bulk corpus ingestion. It also provides specific direction on choosing filePath for local MCP installs and contentBase64 for hosted/remote clients, plus a warning not to base64 local files. However, it does not explicitly reference the singular alternative tool (calypso-upload-knowledge-file), so it lacks full alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.40calypso-list-knowledge-bucketscalypso-rag-agentcalypso-upload-knowledge-filecalypso-upload-knowledge-files-batchScored across 4 tools
Each tool has a clearly distinct purpose: listing buckets, uploading a single file, uploading a batch of files, and querying the RAG agent. The two upload tools are well-separated by single vs. batch semantics, and the descriptions reinforce the boundaries.
Most tools follow a consistent `calypso-<verb>-<object>` pattern (list-knowledge-buckets, upload-knowledge-file, upload-knowledge-files-batch). The `calypso-rag-agent` tool deviates as it names a service rather than an action, but the prefix and hyphenation maintain a readable, predictable style.
Four tools is well-scoped for a focused multimodal RAG server. Each tool addresses a core need (bucket discovery, ingestion, bulk ingestion, and retrieval/chat), and none feel redundant or unnecessary.
The core workflow is covered: list buckets to find destinations, upload files (single or batch), and query via the RAG agent. Minor gaps exist (no explicit file deletion/update or bucket creation), but they are likely outside the intended scope and do not block the primary use case.
Hosted MCP server: convert PDFs to clean, LLM-ready Markdown with tables, formulas and OCR.
Hosted MCP server for AI-driven data ops. Create apps, manage schemas, and CRUD structured data.
The CustomGPT.ai MCP server is a fully managed, RAG-powered endpoint that connects large language models with private knowledge bases and external data sources. It provides tools for retrieval-augmented generation queries (send_message), data ingestion (upload_file), and source listing, enabling AI agents to query private documents like PDFs with high accuracy and real-time citations.
Hosted MCP server for LLM cost estimation, model comparison, and budget-aware routing.
