Calypso Multimodal RAG MCP

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": "[PopNx MCP ตัดค่าที่หน้าตาเหมือนกุญแจออก]", "CALYPSO_API_BASE_URL": "https://api.calypso.so/v1" } } } }

Replace:

• [PopNx MCP ตัดค่าที่หน้าตาเหมือนกุญแจออก]

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": "[PopNx MCP ตัดค่าที่หน้าตาเหมือนกุญแจออก]", "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/..