Calypso MCP Server

Hosted multimodal RAG for Claude Desktop, Cursor, and agent workflows — in one `npx` command.

Ask 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.

> This server is a Calypso Context surface — the same knowledge layer that backs Calypso on WhatsApp, exposed to MCP clients. How the pieces fit →

• One-command setup: `npx -y @calypsohq/multimodal-rag-mcp-server --api-key sk-your-key-here`
• True multimodal RAG: handles text and visuals natively through Gemini File Search
• Upload and query: dedicated tools for durable knowledge files and batch uploads
• Multi-turn conversations: context-aware answers with `/new` reset
• Discoverable workflows: resources and prompts for safe RAG, upload, and ingestion flows

GitHub | Docs | Smithery | Official MCP Registry

Tags: `multimodal-rag`, `gemini-rag`, `hosted-rag-mcp`, `mcp-server`

Instead 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.

Quick Start

# One-liner with npx
npx -y @calypsohq/multimodal-rag-mcp-server --api-key "sk-your-key-here"

Or with environment variables:

CALYPSO_API_KEY="sk-..." npx -y @calypsohq/multimodal-rag-mcp-server

Then add the same command to Claude Desktop, Cursor, or Smithery using the configuration examples below.

Why Choose Calypso

No 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.

• Zero infrastructure: one `npx` command; nothing to host or operate.
• 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.
• Answers carry evidence: responses include source references and retrieval metadata.
• Read and write: query knowledge and add to it — files, batches, and websites — from the same server.

What you get

• Production multimodal Calypso agent with multi-turn memory
• Built-in upload tools for single files and batch knowledge uploads
• Automatic discovery of your team's RAG variants and knowledge buckets
• Verifiable citations with source references and retrieval metadata
• Read-only resources and reusable prompts for safe workflows

Why Multimodal-First RAG

Most 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.

• Search the formats users actually rely on: documentation, PDFs, screenshots, charts, diagrams, product images, support articles, manuals, policies, FAQs, and reports.
• 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.
• Show the evidence trail: responses can include source references, page-aware grounding, and retrieval metadata so people can verify before they trust.
• Scope retrieval with metadata: use workspace, team, customer, language, file type, status, or other metadata to keep answers relevant without duplicating knowledge bases.
• 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.

In practice, this means your agent can answer questions like:

• "Explain this setup screenshot and the attached policy PDF. What should the support rep do next?"
• "What does this onboarding PDF say about approval rules?"
• "Why is this setup screen failing?"
• "Compare the pricing chart with our plan documentation and recommend the right tier."
• "Summarize the policy that applies to this support ticket."
• "Which product plan fits this customer based on our pricing docs?"
• "Compare the diagrammed ingestion flow with the retrieval flow."

What this MCP does

With `calypso-agent` you can:

• Ask grounded questions against the configured Calypso knowledge base
• Select any discovered team RAG variant with the optional `model` argument
• Continue a multi-turn conversation via the native `/v1/responses` conversation model
• Reset the conversation context with `/new`
• Use the same OpenAI-compatible Responses endpoint that serves `calypso-agent`
• Discover built-in resources and prompts for the supported Calypso workflows

Requirements

• Node.js 18+
• 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.
• A Calypso API endpoint that exposes:
  • `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}`
• A Calypso API key (`sk-...`)

Configuration

Environment variables:

• `CALYPSO_API_KEY` (required)
• `CALYPSO_API_BASE_URL` (optional, default `https://api.calypso.so/v1`)

CLI flags:

• `--api-key`
• `--api-base-url`

Configuration precedence:

1. CLI flags / Smithery-provided command arguments

2. Environment variables

3. Default base URL (`https://api.calypso.so/v1`)

Run with npx

npx -y @calypsohq/multimodal-rag-mcp-server --api-key "sk-..."

Run with environment variables

env CALYPSO_API_KEY="sk-..." CALYPSO_API_BASE_URL="https://api.calypso.so/v1" npx -y @calypsohq/multimodal-rag-mcp-server

Configure in Cursor

Add a new MCP server (command type) like:

npx -y @calypsohq/multimodal-rag-mcp-server --api-key sk-... --api-base-url https://api.calypso.so/v1

Configure in Claude Desktop

1. Open Claude Desktop MCP config

In Claude Desktop:

`Claude -> Settings -> Developer -> Edit Config`

On macOS, the file is usually:

~/Library/Application Support/Claude/claude_desktop_config.json

Claude 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`.

2. Add the Calypso MCP server

Paste this into `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"
      }
    }
  }
}

Replace:

• `sk-your-calypso-api-key`

with your real Calypso API key.

3. Restart Claude Desktop fully

Fully quit Claude Desktop, then reopen it.

Do not only close the window. On macOS:

Cmd + Q

After restart, the MCP should appear in Claude with these tools available:

• `calypso-agent`
• `calypso-list-buckets`
• `calypso-upload-file`
• `calypso-upload-files-batch`

Optional: Save Claude Artifacts To Your Mac

Calypso provides hosted multimodal RAG tools. It does not write generated reports, summaries, CSVs, JSON files, or web-search artifacts directly to your local computer.

To let Claude Desktop save generated files locally, add the standard filesystem MCP server alongside Calypso and restrict it to a dedicated safe folder.

Create the folder first:

mkdir -p ~/Claude

Then add both servers to `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"
      ]
    }
  }
}

Fully quit and reopen Claude Desktop after changing the config.

Example prompt:

Use Calypso for the grounded RAG answer, then save the final report as /Users/yourname/Claude/report.md using the filesystem tool.

For safety, only grant filesystem access to a dedicated folder such as `~/Claude`, not your whole home directory.

Smithery

The server is available on Smithery and launches through the same `npx` package path used by desktop clients.

Smithery user config:

• `calypsoApiKey` (required)
• `calypsoApiBaseUrl` (optional, defaults to `https://api.calypso.so/v1`)

The Smithery launch path is equivalent to:

npx -y @calypsohq/multimodal-rag-mcp-server --api-key sk-... --api-base-url https://api.calypso.so/v1

Use `calypsoApiBaseUrl` only when targeting a self-hosted Calypso-compatible deployment. The cloud default does not need an override.

Troubleshooting

• Missing API key: provide `--api-key` or `CALYPSO_API_KEY`
• Wrong API host: make sure `--api-base-url` / `CALYPSO_API_BASE_URL` ends in `/v1`
• Self-hosted deployment: only override the base URL if you are not using `https://api.calypso.so/v1`
• 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
• `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.
• 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`.
• 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.

Choosing `filePath` vs `contentBase64`

Use `filePath` for local MCP installs, including Claude Desktop and Cursor configs that launch this package with a local command such as:

npx -y @calypsohq/multimodal-rag-mcp-server

In 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.

Use `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.

If 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.

Available tools

`calypso-agent`

Direct Calypso agent access.

Notes:

• It does not auto-route to other personas or agents.
• It automatically discovers the API key's available `calypso-agent` variants at startup.
• Use the optional `model` argument to choose a named variant such as `calypso-agent:pricing`.
• Each model variant keeps its own MCP conversation chain, so switching variants does not continue the wrong thread.
• It uses `POST /v1/responses` instead of `POST /v1/chat/completions`.
• First turns create a named conversation, and follow-up turns chain with `previous_response_id`.
• Optional `fileIds` are supported for retrieval-scoped questions. New uploads should use the durable knowledge upload tools and wait for indexing before asking.
• Use `/new` as the prompt to reset the MCP conversation.

`calypso-search`

Searches your knowledge directly and returns matching passages, without asking an agent to compose an answer.

Use 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.

Notes:

• Uses `POST /v1/search`.
• `query` is required.
• `agent` scopes the search to one agent variant's knowledge; `buckets` narrows it to specific buckets.
• `maxResults` is clamped to 1–20.

Example:

{
  "query": "annual plan refund window",
  "buckets": ["support-handbook"],
  "maxResults": 5
}

`calypso-list-buckets`

Lists buckets for the team tied to the configured Calypso API key.

Notes:

• Uses `GET /v1/knowledge/buckets`.
• Does not accept `team_id`; Calypso derives team scope from the API key.
• Returns bucket ids, slugs, names, status, member counts, source counts, and bucket-store readiness.
• Defaults to active buckets only. Pass `includeArchived: true` when you need archived buckets for audits or cleanup.
• Use this before `calypso-upload-file` or `calypso-upload-files-batch` when you need to choose a destination bucket.
• `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.

Example:

{
  "includeArchived": false
}

`calypso-get-file`

Fetches one knowledge file's metadata and indexing status by file id.

Notes:

• Uses `GET /v1/knowledge/files/{file_id}`.
• Resolves the opaque `fileIds` from `calypso-list-buckets` into filename, mime type, size, indexing status, and per-bucket sync state.
• Pass `verify: true` to cross-check against the provider (`?verify=gemini`) — slower, but authoritative when a status looks stale.

Example:

{
  "fileId": "file_123",
  "verify": true
}

`calypso-add-website`

Ingests a website into a knowledge bucket, so page content becomes queryable alongside uploaded files.

Notes:

• Uses `POST /v1/knowledge/websites`.
• `url` is required, and so is a destination — one of `bucketIds`, `bucketSlugs`, or `bucket`.
• Optional `title`, `tagsHint`, and `preferredLanguage` help classify the source.
• Pass `idempotencyKey` to make a retry safe; it is sent as the `Idempotency-Key` header.
• Like file uploads, acceptance is not the same as being queryable — the page still has to finish indexing.

Example:

{
  "url": "https://example.com/pricing",
  "bucket": "pricing",
  "title": "Public pricing page",
  "idempotencyKey": "pricing-page-2026-08"
}

`calypso-create-bucket`

Creates an empty bucket for the create-then-fill workflow.

Notes:

• Uses `POST /v1/knowledge/buckets` (requires a backend with this endpoint deployed and the `knowledge:bucket:create` capability on the API key).
• The server normalizes the slug; collisions return a typed `bucket_slug_exists` error.
• `idempotencyKey` replays return the existing bucket instead of erroring.
• Uploads can still create buckets implicitly via `bucketSlugs` + `createMissingBuckets`; this tool exists for creating the destination first.

Example:

{
  "name": "Product docs",
  "slug": "product-docs",
  "idempotencyKey": "create-product-docs-1"
}

`calypso-create-agent`

Creates a Calypso agent variant bound to one or more buckets.

Notes:

• Uses `POST /v1/rag-agent/agents` (requires a backend with this endpoint deployed and the `rag:agent:create` capability on the API key).
• The success payload leads with `model` — pass it straight to `calypso-agent`.
• 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`.
• 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.

Example:

{
  "agentId": "support",
  "name": "Support agent",
  "bucketSlugs": ["product-docs"],
  "idempotencyKey": "create-support-agent-1"
}

`calypso-upload-file`

Uploads a file into the durable bucket-backed knowledge store and indexing pipeline.

Notes:

• Uses `POST /v1/knowledge/files/upload-session`, uploads bytes directly to storage, then finalizes with `POST /v1/knowledge/files/upload-session/{session_id}/finalize`.
• Uploads use JSON session requests plus signed binary `PUT`s, not multipart form uploads.
• Returns file and task metadata, not a chat attachment `file_id`.
• Requires one bucket destination via `bucketIds`, `bucketSlugs`, or `bucket`.
• 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.
• 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`.
• Supports optional `title`, `tags`, `metadata`, and `idempotencyKey`.
• Route uploads into existing buckets with `bucketIds` or `bucketSlugs`, or use `bucket` as a single-slug shortcut.
• Pass `createMissingBuckets: true` with bucket slugs when you want Calypso to create missing destinations during upload.
• Can optionally wait until indexing reaches a ready state before returning.

Example:

{
  "filename": "handbook.pdf",
  "mimeType": "application/pdf",
  "filePath": "/Users/me/Documents/handbook.pdf",
  "bucket": "support-handbook",
  "createMissingBuckets": true,
  "waitForIndexing": true
}

`calypso-upload-files-batch`

Uploads 1 to 100 files into the durable knowledge store in one request.

Notes:

• 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`.
• Uploads use JSON session requests plus signed binary `PUT`s, not multipart form uploads.
• Requires `batchIdempotencyKey`; Calypso uses it to derive the durable batch id for retries.
• Requires a shared bucket destination via `bucketIds`, `bucketSlugs`, or `bucket`, unless every item provides its own bucket destination.
• Supports shared `bucketIds`, `bucketSlugs`, `bucket`, and `createMissingBuckets` defaults, plus per-item overrides.
• 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.
• Generates Firestore-safe `client_file_id` values when `clientFileId` is omitted.
• `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`.
• Inspect per-item status, `bucketSyncStatus`, and `bucketSync` to distinguish indexed content from bucket-ready retrieval.

Example:

{
  "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
}

Available resources

`calypso://server-info`

Read-only server metadata, including package version, API base URL, transport, authentication model, and exposed capabilities.

`calypso://rag-agent-models`

Read-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`.

`calypso://buckets`

Read-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.

`calypso://workflows`

A compact guide to the supported RAG and file-upload workflows.

`calypso://security`

Operational security notes for API keys, local file reads, uploads, and logging.

Available prompts

• `calypso-question`: draft a grounded knowledge-base question for `calypso-agent`
• `calypso-ingestion`: prepare a durable knowledge-store upload and follow-up query
• `calypso-reset-conversation`: start a clean RAG thread with `/new`

Common workflows (copy/paste)

Knowledge retrieval

• Summarize a topic:
  • `Summarize the knowledge base guidance for campaign approvals`
• Ask for a specific answer:
  • `What does our documentation say about indexing retries?`
• Compare two concepts:
  • `Compare file indexing with retrieval execution in the current architecture`
• Start a fresh thread:
  • `/new`

Multi-turn follow-up

• Refine a previous answer:
  • `Focus only on the ingestion path and ignore retrieval`
• Ask for sources or justification:
  • `Explain which documented components are involved and why`

Knowledge-store file flow

• Discover buckets:
  • Call `calypso-list-buckets` or read `calypso://buckets` before choosing a destination
• Upload durable knowledge:
  • Call `calypso-upload-file` with the file payload and optional `title`, `tags`, or `metadata`
  • Prefer `filePath` for local Claude Desktop/Cursor MCP installs; use `contentBase64` for hosted or remote MCP clients that cannot read local paths
• Route knowledge into buckets:
  • Use `bucket: "support-handbook"` for one destination, `bucketSlugs` for multiple slug-based destinations, or `bucketIds` when you already have stable bucket ids
• Create bucket destinations on demand:
  • Add `createMissingBuckets: true` when using slug-based bucket assignment and the destination may not exist yet
• Wait for indexing:
  • Pass `waitForIndexing: true` if you want the tool to block until the knowledge file is indexed

Knowledge-store batch flow

• Upload many durable files:
  • 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
• Route the batch into buckets:
  • Put shared `bucket`, `bucketSlugs`, `bucketIds`, or `createMissingBuckets` on the tool call, then override per item only when needed
• Wait for query readiness:
  • Use `waitForBatchReady: true` and inspect returned item status plus bucket sync fields before querying fresh content

Tips

• Start over: use `/new` to reset the MCP conversation (new `conversation_id` + cleared response chain).

Version history

See CHANGELOG.md for detail.

Upgrading to 3.0.0

Two renames landed across 2.4.0 and 3.0.0, and neither is aliased.

• 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.
• 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.

The `calypso://rag-agent-models` resource URI is deliberately unchanged. It is a published address, not a compatibility shim.