MCP Server

What The MCP Integration Is For

Use the Calypso MCP server when you want an AI client to talk to the same grounded RAG layer you already manage in Calypso.

The MCP server is the agent-facing integration path for:

• asking grounded questions with calypso-rag-agent
• selecting team-scoped RAG agent variants such as calypso-rag-agent:pricing
• uploading durable knowledge into required bucket destinations
• exposing read-only workflow, model, and security resources to MCP clients

Package

The server runs from the public npm package:

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

GitHub repository: calypso-so/calypso-mcp-server

The default API base URL is:

https://api.calypso.so/v1

Only override the base URL when you are targeting a self-hosted or environment-specific Calypso-compatible deployment.

Requirements

You need:

• Node.js 18 or newer
• a Calypso project API key
• a Calypso API host exposing /v1/responses, /v1/rag-agent/models, /v1/knowledge/buckets, and the knowledge upload-session endpoints
• at least one active knowledge bucket for upload workflows

The API key scopes discovery and usage to its team. When the MCP starts, it uses that key to load the RAG agent variants and bucket metadata available to the team.

Configure Cursor

Add the server as a command-based MCP server:

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

Use the project API key for the Calypso team you want the MCP client to access.

Configure Claude Desktop

Open the Claude Desktop MCP config:

Claude -> Settings -> Developer -> Edit Config

On macOS, the file is usually:

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

Add the server:

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

Fully quit and restart Claude Desktop after editing the config.

Runtime Discovery

On startup, the MCP calls GET /v1/rag-agent/models with your API key.

That endpoint returns the RAG agent variants available to the key's team, including bucket metadata. The MCP uses that catalog to:

• expose named variants like calypso-rag-agent:legal
• keep separate conversation chains per model variant
• auto-select the only active bucket when a selected variant has exactly one
• require explicit bucketId when a selected variant has multiple active buckets
• guide knowledge uploads toward active bucket destinations

Read the calypso://rag-agent-models resource in your MCP client when you need to inspect the discovered variants and their buckets array.

For a team-wide bucket list, use calypso-list-knowledge-buckets or read calypso://knowledge-buckets. Model discovery answers which buckets are bound to each agent variant. Bucket listing answers which buckets exist for the API key's team.

Tools

Ask A RAG Agent

Use calypso-rag-agent for normal grounded questions.

Important behavior:

• pass model to choose a discovered variant such as calypso-rag-agent:pricing
• omit model to use the default calypso-rag-agent
• send /new as the prompt to reset the MCP conversation
• follow-up turns keep their own conversation chain per model variant

Example tool input:

{
  "model": "calypso-rag-agent:support",
  "prompt": "What does our support handbook say about escalation timing?"
}

List Knowledge Buckets

Use calypso-list-knowledge-buckets before upload workflows when you need stable bucket ids, slugs, names, member counts, source counts, or bucket-store readiness.

Example:

{
  "includeArchived": false
}

The tool calls GET /v1/knowledge/buckets with the configured API key. It never accepts team_id; Calypso derives team scope from the key.

Typical result:

{
  "team_id": "team_123",
  "buckets": [
    {
      "id": "bucket_abc",
      "slug": "support-handbook",
      "name": "Support Handbook",
      "status": "active",
      "memberCount": 12,
      "counts": {
        "total": 12,
        "file": 10,
        "retrievable": 9
      },
      "bucketStore": {
        "status": "active",
        "member_count": 12,
        "indexed_member_count": 9,
        "pending_member_count": 3
      }
    }
  ]
}

Upload Durable Knowledge

Use calypso-upload-knowledge-file when the source should become reusable workspace knowledge.

Every durable knowledge upload must include a bucket destination:

• bucketIds for existing bucket ids
• bucketSlugs for one or more bucket slugs
• bucket as a shorthand for one bucket slug
• createMissingBuckets: true when slug destinations may need to be created

Example:

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

If no bucket destination is provided, Calypso rejects the request with bucket_required.

Upload Durable Batches

Use calypso-upload-knowledge-files-batch for 1 to 100 files.

A batch must include either:

• one shared bucket destination on the tool call
• bucket destinations on every item

Example:

{
  "batchIdempotencyKey": "support-seed-2026-06-04",
  "bucket": "support-handbook",
  "createMissingBuckets": true,
  "items": [
    {
      "filename": "faq.txt",
      "mimeType": "text/plain",
      "filePath": "/Users/me/Desktop/faq.txt"
    },
    {
      "filename": "refund-policy.pdf",
      "mimeType": "application/pdf",
      "filePath": "/Users/me/Desktop/refund-policy.pdf"
    }
  ],
  "waitForBatchReady": true
}

Upload Local Directories

The MCP server accepts explicit file items, not a raw directory path.

For directory-style ingestion, have the MCP client or a helper script:

1. enumerate the directory
2. filter the files you want to ingest
3. split them into batches of up to 100
4. call calypso-upload-knowledge-files-batch
5. wait for batch and bucket readiness before querying the new content

This keeps local folder uploads aligned with Calypso's durable batch status, idempotency, and bucket sync behavior.

Resources And Prompts

The MCP exposes read-only resources:

• calypso://server-info
• calypso://rag-agent-models
• calypso://knowledge-buckets
• calypso://workflows
• calypso://security

Use calypso://knowledge-buckets as the resource form of calypso-list-knowledge-buckets when your MCP client prefers reading context over calling a tool.

It also exposes prompts for common workflows:

• calypso-knowledge-question
• calypso-knowledge-ingestion
• calypso-reset-conversation

Troubleshooting

Next:

• Upload API
• n8n