{
  "markdown": "# Calypso MCP Server\n\n**Hosted multimodal RAG for Claude Desktop, Cursor, and agent workflows — in one `npx` command.**\n\nAsk questions across PDFs, screenshots, charts, and diagrams, and upload new source material, without running a vector store, a Docker stack, or an OCR pipeline. Answers come back with citations you can check.\n\n[![Smithery](https://img.shields.io/badge/Smithery-calypso--mcp--server-6f42c1)](https://smithery.ai/servers/multimodal-rag/calypso-mcp-server)\n[![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/calypso-so/calypso-mcp-server)](https://archestra.ai/mcp-catalog/calypso-so__calypso-mcp-server)\n[![npm version](https://img.shields.io/npm/v/@calypsohq/multimodal-rag-mcp-server)](https://www.npmjs.com/package/@calypsohq/multimodal-rag-mcp-server)\n[![GitHub stars](https://img.shields.io/github/stars/calypso-so/calypso-mcp-server?style=social)](https://github.com/calypso-so/calypso-mcp-server)\n[![Multimodal RAG](https://img.shields.io/badge/Multimodal_RAG-Gemini_File_Search-blue)](https://docs.calypso.so)\n[![One command](https://img.shields.io/badge/One_Command-npx-success)](https://www.npmjs.com/package/@calypsohq/multimodal-rag-mcp-server)\n[![License](https://img.shields.io/github/license/calypso-so/calypso-mcp-server)](./LICENSE)\n[![CI](https://github.com/calypso-so/calypso-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/calypso-so/calypso-mcp-server/actions/workflows/ci.yml)\n\n> This server is a **Calypso Context** surface — the same knowledge layer that backs Calypso on WhatsApp, exposed to MCP clients. [How the pieces fit →](https://www.calypso.so/#learn)\n\n- **One-command setup**: `npx -y @calypsohq/multimodal-rag-mcp-server --api-key sk-your-key-here`\n- **True multimodal RAG**: handles text and visuals natively through Gemini File Search\n- **Upload and query**: dedicated tools for durable knowledge files and batch uploads\n- **Multi-turn conversations**: context-aware answers with `/new` reset\n- **Discoverable workflows**: resources and prompts for safe RAG, upload, and ingestion flows\n\n[GitHub](https://github.com/calypso-so/calypso-mcp-server) | [Docs](https://docs.calypso.so) | [Smithery](https://smithery.ai/servers/multimodal-rag/calypso-mcp-server) | [Official MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.calypso-so/multimodal-rag-mcp-server)\n\nTags: `multimodal-rag`, `gemini-rag`, `hosted-rag-mcp`, `mcp-server`\n\nInstead of wiring each agent or workflow to a one-off document search stack, use this MCP as the agent-facing entry point to one reusable answer layer: upload source material once, retrieve across text and visual content, and return answers with evidence users can verify.\n\n## Quick Start\n\n```bash\n# One-liner with npx\nnpx -y @calypsohq/multimodal-rag-mcp-server --api-key \"sk-your-key-here\"\n```\n\nOr with environment variables:\n\n```bash\nCALYPSO_API_KEY=\"sk-...\" npx -y @calypsohq/multimodal-rag-mcp-server\n```\n\nThen add the same command to Claude Desktop, Cursor, or Smithery using the configuration examples below.\n\n## Why Choose Calypso\n\nNo local vector store, no Docker Compose, and no separate OCR or vision pipeline before an agent can ask a grounded question. Point the server at a Calypso API key and it discovers your team's agents and knowledge buckets on connect.\n\n- **Zero infrastructure**: one `npx` command; nothing to host or operate.\n- **Multimodal without a second pipeline**: text and visuals are indexed together, so a chart or a screenshot is queryable the same way a paragraph is.\n- **Answers carry evidence**: responses include source references and retrieval metadata.\n- **Read and write**: query knowledge and add to it — files, batches, and websites — from the same server.\n\n## What you get\n\n- Production multimodal Calypso agent with multi-turn memory\n- Built-in upload tools for single files and batch knowledge uploads\n- Automatic discovery of your team's RAG variants and knowledge buckets\n- Verifiable citations with source references and retrieval metadata\n- Read-only resources and reusable prompts for safe workflows\n\n## Why Multimodal-First RAG\n\nMost company knowledge is not only text. The answer often lives across a setup screenshot, a PDF table, a product diagram, a help-center page, or a chart inside a report. Calypso packages that full knowledge surface into a single retrieval layer so agents can ask grounded questions without guessing from generic model memory.\n\n- **Search the formats users actually rely on**: documentation, PDFs, screenshots, charts, diagrams, product images, support articles, manuals, policies, FAQs, and reports.\n- **Ground answers before the model writes**: Gemini File Search retrieves relevant text and visual context first, then the Calypso agent answers from that source material.\n- **Show the evidence trail**: responses can include source references, page-aware grounding, and retrieval metadata so people can verify before they trust.\n- **Scope retrieval with metadata**: use workspace, team, customer, language, file type, status, or other metadata to keep answers relevant without duplicating knowledge bases.\n- **Reuse the same knowledge layer everywhere**: connect Cursor, Claude Desktop, AI agents, n8n workflows, product UI, support flows, and website experiences to the same source-backed layer.\n\nIn practice, this means your agent can answer questions like:\n\n- \"Explain this setup screenshot and the attached policy PDF. What should the support rep do next?\"\n- \"What does this onboarding PDF say about approval rules?\"\n- \"Why is this setup screen failing?\"\n- \"Compare the pricing chart with our plan documentation and recommend the right tier.\"\n- \"Summarize the policy that applies to this support ticket.\"\n- \"Which product plan fits this customer based on our pricing docs?\"\n- \"Compare the diagrammed ingestion flow with the retrieval flow.\"\n\n## What this MCP does\n\nWith `calypso-agent` you can:\n\n- Ask grounded questions against the configured Calypso knowledge base\n- Select any discovered team RAG variant with the optional `model` argument\n- Continue a multi-turn conversation via the native `/v1/responses` conversation model\n- Reset the conversation context with `/new`\n- Use the same OpenAI-compatible Responses endpoint that serves `calypso-agent`\n- Discover built-in resources and prompts for the supported Calypso workflows\n\n## Requirements\n\n- Node.js 18+\n- The server uses Web Fetch API primitives (`fetch`, `Headers`, `Request`, `Response`, `FormData`, `Blob`, and `File`) for API calls and SDK compatibility. The package bootstraps missing globals at startup for MCP runtimes that expose only part of the Node 18+ Web API surface.\n- A Calypso API endpoint that exposes:\n  - `POST /v1/responses`\n  - `GET /v1/rag-agent/models`\n  - `GET /v1/knowledge/buckets`\n  - `POST /v1/knowledge/files/upload-session`\n  - `POST /v1/knowledge/files/upload-session/{session_id}/finalize`\n  - `POST /v1/knowledge/files:batch/upload-session`\n  - `POST /v1/knowledge/files:batch/upload-session/{batch_id}/finalize`\n  - `GET /v1/knowledge/batches/{batch_id}`\n- A Calypso API key (`sk-...`)\n\n## Configuration\n\nEnvironment variables:\n\n- `CALYPSO_API_KEY` (required)\n- `CALYPSO_API_BASE_URL` (optional, default `https://api.calypso.so/v1`)\n\nCLI flags:\n\n- `--api-key`\n- `--api-base-url`\n\nConfiguration precedence:\n\n1. CLI flags / Smithery-provided command arguments\n2. Environment variables\n3. Default base URL (`https://api.calypso.so/v1`)\n\n## Run with npx\n\n```bash\nnpx -y @calypsohq/multimodal-rag-mcp-server --api-key \"sk-...\"\n```\n\n## Run with environment variables\n\n```bash\nenv CALYPSO_API_KEY=\"sk-...\" CALYPSO_API_BASE_URL=\"https://api.calypso.so/v1\" npx -y @calypsohq/multimodal-rag-mcp-server\n```\n\n## Configure in Cursor\n\nAdd a new MCP server (command type) like:\n\n```bash\nnpx -y @calypsohq/multimodal-rag-mcp-server --api-key sk-... --api-base-url https://api.calypso.so/v1\n```\n\n## Configure in Claude Desktop\n\n### 1. Open Claude Desktop MCP config\n\nIn Claude Desktop:\n\n`Claude -> Settings -> Developer -> Edit Config`\n\nOn macOS, the file is usually:\n\n```bash\n~/Library/Application Support/Claude/claude_desktop_config.json\n```\n\nClaude Desktop uses `claude_desktop_config.json` for desktop MCP servers. Claude Code uses separate config locations such as `~/.claude.json` or project-level `.mcp.json`.\n\n### 2. Add the Calypso MCP server\n\nPaste this into `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"Calypso Multimodal RAG\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@calypsohq/multimodal-rag-mcp-server\"\n      ],\n      \"env\": {\n        \"CALYPSO_API_KEY\": \"sk-your-calypso-api-key\",\n        \"CALYPSO_API_BASE_URL\": \"https://api.calypso.so/v1\"\n      }\n    }\n  }\n}\n```\n\nReplace:\n\n- `sk-your-calypso-api-key`\n\nwith your real Calypso API key.\n\n### 3. Restart Claude Desktop fully\n\nFully quit Claude Desktop, then reopen it.\n\nDo not only close the window. On macOS:\n\n```bash\nCmd + Q\n```\n\nAfter restart, the MCP should appear in Claude with these tools available:\n\n- `calypso-agent`\n- `calypso-list-buckets`\n- `calypso-upload-file`\n- `calypso-upload-files-batch`\n\n### Optional: Save Claude Artifacts To Your Mac\n\nCalypso provides hosted multimodal RAG tools. It does not write generated reports, summaries, CSVs, JSON files, or web-search artifacts directly to your local computer.\n\nTo let Claude Desktop save generated files locally, add the standard filesystem MCP server alongside Calypso and restrict it to a dedicated safe folder.\n\nCreate the folder first:\n\n```bash\nmkdir -p ~/Claude\n```\n\nThen add both servers to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"Calypso Multimodal RAG\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@calypsohq/multimodal-rag-mcp-server\"\n      ],\n      \"env\": {\n        \"CALYPSO_API_KEY\": \"sk-your-calypso-api-key\",\n        \"CALYPSO_API_BASE_URL\": \"https://api.calypso.so/v1\"\n      }\n    },\n    \"filesystem\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@modelcontextprotocol/server-filesystem\",\n        \"/Users/yourname/Claude\"\n      ]\n    }\n  }\n}\n```\n\nFully quit and reopen Claude Desktop after changing the config.\n\nExample prompt:\n\n```text\nUse Calypso for the grounded RAG answer, then save the final report as /Users/yourname/Claude/report.md using the filesystem tool.\n```\n\nFor safety, only grant filesystem access to a dedicated folder such as `~/Claude`, not your whole home directory.\n\n| Concern | Best Owner |\n| --- | --- |\n| Source-backed RAG answers | Calypso MCP |\n| Uploading files into Calypso | Calypso MCP |\n| Writing `.md`, `.pdf`, `.json`, `.csv`, etc. to your Mac | filesystem MCP |\n| Web search artifacts from Claude | Claude plus filesystem MCP prompt |\n\n## Smithery\n\nThe server is available on [Smithery](https://smithery.ai/servers/multimodal-rag/calypso-mcp-server) and launches through the same `npx` package path used by desktop clients.\n\nSmithery user config:\n\n- `calypsoApiKey` (required)\n- `calypsoApiBaseUrl` (optional, defaults to `https://api.calypso.so/v1`)\n\nThe Smithery launch path is equivalent to:\n\n```bash\nnpx -y @calypsohq/multimodal-rag-mcp-server --api-key sk-... --api-base-url https://api.calypso.so/v1\n```\n\nUse `calypsoApiBaseUrl` only when targeting a self-hosted Calypso-compatible deployment. The cloud default does not need an override.\n\n## Troubleshooting\n\n- **Missing API key**: provide `--api-key` or `CALYPSO_API_KEY`\n- **Wrong API host**: make sure `--api-base-url` / `CALYPSO_API_BASE_URL` ends in `/v1`\n- **Self-hosted deployment**: only override the base URL if you are not using `https://api.calypso.so/v1`\n- **Smithery launch mismatch**: use the packaged `npx -y @calypsohq/multimodal-rag-mcp-server` path instead of running `node dist/index.js` from a fresh clone\n- **`FormData is not defined` or `Headers is not defined`**: upgrade to the latest package. The MCP server bootstraps missing Web Fetch API globals before upload tools run.\n- **ENOENT for `/mnt/user-data/uploads/...`**: that path belongs to a hosted agent or attachment sandbox, not necessarily to the MCP server. Retry with `contentBase64` instead of `filePath`.\n- **Local artifact saving**: Calypso answers can be used with Claude Desktop's filesystem MCP server, but Claude must be explicitly asked to save the final output to an allowed local path.\n\n## Choosing `filePath` vs `contentBase64`\n\nUse `filePath` for local MCP installs, including Claude Desktop and Cursor configs that launch this package with a local command such as:\n\n```bash\nnpx -y @calypsohq/multimodal-rag-mcp-server\n```\n\nIn that setup, the MCP server process runs on your machine and can read paths available to the same user account. Pass the local path directly; the server reads raw bytes and uploads them through the Calypso upload-session URL. You do not need to base64-encode local files.\n\nUse `contentBase64` for hosted or remote MCP clients, including Smithery-hosted servers, browser/cloud runtimes, generated in-memory content, and agent containers. In those environments, a path on your Mac or workstation is not readable by the MCP server process.\n\nIf a path starts with `/mnt/user-data/uploads`, `/mnt/data`, `/mnt/attachments`, or another hosted sandbox prefix, do not send it as `filePath` unless this MCP server is running in that same sandbox. Use `contentBase64` or another inline byte source instead.\n\n## Available tools\n\n### `calypso-agent`\nDirect Calypso agent access.\n\nNotes:\n- It does not auto-route to other personas or agents.\n- It automatically discovers the API key's available `calypso-agent` variants at startup.\n- Use the optional `model` argument to choose a named variant such as `calypso-agent:pricing`.\n- Each model variant keeps its own MCP conversation chain, so switching variants does not continue the wrong thread.\n- It uses `POST /v1/responses` instead of `POST /v1/chat/completions`.\n- First turns create a named conversation, and follow-up turns chain with `previous_response_id`.\n- Optional `fileIds` are supported for retrieval-scoped questions. New uploads should use the durable knowledge upload tools and wait for indexing before asking.\n- Use `/new` as the prompt to reset the MCP conversation.\n\n### `calypso-search`\nSearches your knowledge directly and returns matching passages, without asking an agent to compose an answer.\n\nUse it when you want evidence rather than prose — checking whether something is indexed at all, gathering sources before a decision, or letting a calling agent do its own reasoning over the passages.\n\nNotes:\n- Uses `POST /v1/search`.\n- `query` is required.\n- `agent` scopes the search to one agent variant's knowledge; `buckets` narrows it to specific buckets.\n- `maxResults` is clamped to 1–20.\n\nExample:\n\n```json\n{\n  \"query\": \"annual plan refund window\",\n  \"buckets\": [\"support-handbook\"],\n  \"maxResults\": 5\n}\n```\n\n### `calypso-list-buckets`\nLists buckets for the team tied to the configured Calypso API key.\n\nNotes:\n- Uses `GET /v1/knowledge/buckets`.\n- Does not accept `team_id`; Calypso derives team scope from the API key.\n- Returns bucket ids, slugs, names, status, member counts, source counts, and bucket-store readiness.\n- Defaults to active buckets only. Pass `includeArchived: true` when you need archived buckets for audits or cleanup.\n- Use this before `calypso-upload-file` or `calypso-upload-files-batch` when you need to choose a destination bucket.\n- `calypso://rag-agent-models` answers which buckets are bound to each RAG variant. `calypso-list-buckets` answers which buckets exist for the API key's team.\n\nExample:\n\n```json\n{\n  \"includeArchived\": false\n}\n```\n\n### `calypso-get-file`\nFetches one knowledge file's metadata and indexing status by file id.\n\nNotes:\n- Uses `GET /v1/knowledge/files/{file_id}`.\n- Resolves the opaque `fileIds` from `calypso-list-buckets` into filename, mime type, size, indexing status, and per-bucket sync state.\n- Pass `verify: true` to cross-check against the provider (`?verify=gemini`) — slower, but authoritative when a status looks stale.\n\nExample:\n\n```json\n{\n  \"fileId\": \"file_123\",\n  \"verify\": true\n}\n```\n\n### `calypso-add-website`\nIngests a website into a knowledge bucket, so page content becomes queryable alongside uploaded files.\n\nNotes:\n- Uses `POST /v1/knowledge/websites`.\n- `url` is required, and so is a destination — one of `bucketIds`, `bucketSlugs`, or `bucket`.\n- Optional `title`, `tagsHint`, and `preferredLanguage` help classify the source.\n- Pass `idempotencyKey` to make a retry safe; it is sent as the `Idempotency-Key` header.\n- Like file uploads, acceptance is not the same as being queryable — the page still has to finish indexing.\n\nExample:\n\n```json\n{\n  \"url\": \"https://example.com/pricing\",\n  \"bucket\": \"pricing\",\n  \"title\": \"Public pricing page\",\n  \"idempotencyKey\": \"pricing-page-2026-08\"\n}\n```\n\n### `calypso-create-bucket`\nCreates an empty bucket for the create-then-fill workflow.\n\nNotes:\n- Uses `POST /v1/knowledge/buckets` (requires a backend with this endpoint deployed and the `knowledge:bucket:create` capability on the API key).\n- The server normalizes the slug; collisions return a typed `bucket_slug_exists` error.\n- `idempotencyKey` replays return the existing bucket instead of erroring.\n- Uploads can still create buckets implicitly via `bucketSlugs` + `createMissingBuckets`; this tool exists for creating the destination first.\n\nExample:\n\n```json\n{\n  \"name\": \"Product docs\",\n  \"slug\": \"product-docs\",\n  \"idempotencyKey\": \"create-product-docs-1\"\n}\n```\n\n### `calypso-create-agent`\nCreates a Calypso agent variant bound to one or more buckets.\n\nNotes:\n- Uses `POST /v1/rag-agent/agents` (requires a backend with this endpoint deployed and the `rag:agent:create` capability on the API key).\n- The success payload leads with `model` — pass it straight to `calypso-agent`.\n- Bucket bindings are validated server-side: unknown or archived buckets return `bucket_not_found`; agent id collisions return `agent_id_exists`; the plan's agent cap returns `agent_limit_reached`.\n- Creating an agent refreshes the model catalog and emits MCP `tools/list_changed` + `resources/list_changed` notifications, so the new variant is usable without reconnecting.\n\nExample:\n\n```json\n{\n  \"agentId\": \"support\",\n  \"name\": \"Support agent\",\n  \"bucketSlugs\": [\"product-docs\"],\n  \"idempotencyKey\": \"create-support-agent-1\"\n}\n```\n\n### `calypso-upload-file`\nUploads a file into the durable bucket-backed knowledge store and indexing pipeline.\n\nNotes:\n- Uses `POST /v1/knowledge/files/upload-session`, uploads bytes directly to storage, then finalizes with `POST /v1/knowledge/files/upload-session/{session_id}/finalize`.\n- Uploads use JSON session requests plus signed binary `PUT`s, not multipart form uploads.\n- Returns file and task metadata, not a chat attachment `file_id`.\n- Requires one bucket destination via `bucketIds`, `bucketSlugs`, or `bucket`.\n- Use `filePath` for local Claude Desktop/Cursor MCP installs where the server can read the path. Use `contentBase64` for hosted or remote MCP clients that cannot read local paths.\n- If an agent sees a path like `/mnt/user-data/uploads/file.pdf`, it should not send that as `filePath`; it should send the file bytes as `contentBase64`.\n- Supports optional `title`, `tags`, `metadata`, and `idempotencyKey`.\n- Route uploads into existing buckets with `bucketIds` or `bucketSlugs`, or use `bucket` as a single-slug shortcut.\n- Pass `createMissingBuckets: true` with bucket slugs when you want Calypso to create missing destinations during upload.\n- Can optionally wait until indexing reaches a ready state before returning.\n\nExample:\n\n```json\n{\n  \"filename\": \"handbook.pdf\",\n  \"mimeType\": \"application/pdf\",\n  \"filePath\": \"/Users/me/Documents/handbook.pdf\",\n  \"bucket\": \"support-handbook\",\n  \"createMissingBuckets\": true,\n  \"waitForIndexing\": true\n}\n```\n\n### `calypso-upload-files-batch`\nUploads 1 to 100 files into the durable knowledge store in one request.\n\nNotes:\n- Uses `POST /v1/knowledge/files:batch/upload-session`, uploads each accepted item directly to storage, then finalizes with `POST /v1/knowledge/files:batch/upload-session/{batch_id}/finalize`.\n- Uploads use JSON session requests plus signed binary `PUT`s, not multipart form uploads.\n- Requires `batchIdempotencyKey`; Calypso uses it to derive the durable batch id for retries.\n- Requires a shared bucket destination via `bucketIds`, `bucketSlugs`, or `bucket`, unless every item provides its own bucket destination.\n- Supports shared `bucketIds`, `bucketSlugs`, `bucket`, and `createMissingBuckets` defaults, plus per-item overrides.\n- Use per-item `filePath` for local Claude Desktop/Cursor MCP installs where the server can read each path. Use per-item `contentBase64` for hosted or remote MCP clients that cannot read local paths.\n- Generates Firestore-safe `client_file_id` values when `clientFileId` is omitted.\n- `accepted` or `queued` means the upload is durable, not necessarily query-ready. Use `waitForBatchReady: true` to poll `GET /v1/knowledge/batches/{batch_id}?include_items=true`.\n- Inspect per-item status, `bucketSyncStatus`, and `bucketSync` to distinguish indexed content from bucket-ready retrieval.\n\nExample:\n\n```json\n{\n  \"batchIdempotencyKey\": \"kb-seed-2026-06-04\",\n  \"bucket\": \"support-handbook\",\n  \"createMissingBuckets\": true,\n  \"items\": [\n    {\n      \"filename\": \"faq.txt\",\n      \"mimeType\": \"text/plain\",\n      \"filePath\": \"/Users/me/Documents/faq.txt\"\n    }\n  ],\n  \"waitForBatchReady\": true\n}\n```\n\n## Available resources\n\n### `calypso://server-info`\nRead-only server metadata, including package version, API base URL, transport, authentication model, and exposed capabilities.\n\n### `calypso://rag-agent-models`\nRead-only runtime catalog of team-scoped `calypso-agent` model variants discovered from the configured API key, including each variant's active `buckets`, `bucket_ids`, and `missing_bucket_ids`. If discovery is unavailable, this resource falls back to the base `calypso-agent`.\n\n### `calypso://buckets`\nRead-only runtime list of knowledge buckets for the team tied to the configured API key. Use it to inspect bucket ids/slugs and bucket-store readiness before uploads.\n\n### `calypso://workflows`\nA compact guide to the supported RAG and file-upload workflows.\n\n### `calypso://security`\nOperational security notes for API keys, local file reads, uploads, and logging.\n\n## Available prompts\n\n- **`calypso-question`**: draft a grounded knowledge-base question for `calypso-agent`\n- **`calypso-ingestion`**: prepare a durable knowledge-store upload and follow-up query\n- **`calypso-reset-conversation`**: start a clean RAG thread with `/new`\n\n## Common workflows (copy/paste)\n\n### Knowledge retrieval\n\n- **Summarize a topic**:\n  - `Summarize the knowledge base guidance for campaign approvals`\n- **Ask for a specific answer**:\n  - `What does our documentation say about indexing retries?`\n- **Compare two concepts**:\n  - `Compare file indexing with retrieval execution in the current architecture`\n- **Start a fresh thread**:\n  - `/new`\n\n### Multi-turn follow-up\n\n- **Refine a previous answer**:\n  - `Focus only on the ingestion path and ignore retrieval`\n- **Ask for sources or justification**:\n  - `Explain which documented components are involved and why`\n\n### Knowledge-store file flow\n\n- **Discover buckets**:\n  - Call `calypso-list-buckets` or read `calypso://buckets` before choosing a destination\n- **Upload durable knowledge**:\n  - Call `calypso-upload-file` with the file payload and optional `title`, `tags`, or `metadata`\n  - Prefer `filePath` for local Claude Desktop/Cursor MCP installs; use `contentBase64` for hosted or remote MCP clients that cannot read local paths\n- **Route knowledge into buckets**:\n  - Use `bucket: \"support-handbook\"` for one destination, `bucketSlugs` for multiple slug-based destinations, or `bucketIds` when you already have stable bucket ids\n- **Create bucket destinations on demand**:\n  - Add `createMissingBuckets: true` when using slug-based bucket assignment and the destination may not exist yet\n- **Wait for indexing**:\n  - Pass `waitForIndexing: true` if you want the tool to block until the knowledge file is indexed\n\n### Knowledge-store batch flow\n\n- **Upload many durable files**:\n  - Call `calypso-upload-files-batch` with `items`, `batchIdempotencyKey`, and `filePath` per item for local MCP installs; use `contentBase64` per item for hosted or remote MCP clients\n- **Route the batch into buckets**:\n  - Put shared `bucket`, `bucketSlugs`, `bucketIds`, or `createMissingBuckets` on the tool call, then override per item only when needed\n- **Wait for query readiness**:\n  - Use `waitForBatchReady: true` and inspect returned item status plus bucket sync fields before querying fresh content\n\n## Tips\n\n- **Start over**: use `/new` to reset the MCP conversation (new `conversation_id` + cleared response chain).\n\n## Version history\n\n| Version | Notes |\n| --- | --- |\n| **3.0.0** | **Breaking.** Removed legacy `calypso-rag-agent` model-id support — an unrecognized id is now an error rather than being rewritten to the canonical family. Documented `calypso-search` and `calypso-add-website`, and fixed `calypso://server-info`, which had been omitting `calypso-add-website`. |\n| **2.4.0** | Renamed the ask tool `calypso-rag-agent` → `calypso-agent`. The model catalog now takes its default from discovery instead of a hardcoded constant. |\n| **2.3.x** | Search release and follow-up fixes. |\n\nSee [CHANGELOG.md](CHANGELOG.md) for detail.\n\n### Upgrading to 3.0.0\n\nTwo renames landed across 2.4.0 and 3.0.0, and neither is aliased.\n\n- **The ask tool is `calypso-agent`** (was `calypso-rag-agent`). MCP clients pick this up on their next `tools/list`, but any saved prompt, agent instruction, or documentation that names the tool as a string needs updating.\n- **Model ids must be canonical.** `calypso-rag-agent` and `calypso-rag-agent:{id}` are no longer rewritten to `calypso-agent[:{id}]`. Passing one now fails with `Unknown Calypso agent model`, which names `calypso://rag-agent-models` as the place to find valid ids. Read that resource, or omit `model` to use the discovered default.\n\nThe `calypso://rag-agent-models` resource URI is deliberately unchanged. It is a published address, not a compatibility shim.\n",
  "bytes": 26231,
  "sha": "629f0efbc09703a80fd85f24493bedecd8df3205fa43fb6bd647c9f7e28093dc",
  "repo_slug": "calypso-so/calypso-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_calypso_so_multimodal_rag_mcp__96d7ee95/readme"
}