bewell-catalyst-mcp

An MCP (Model Context Protocol) server for managing an organization's activity library on the BeWell Catalyst platform. From any MCP-capable Claude session you can create, update, list, fetch and delete library activities of every type, including uploading their media (images, video, audio).

The server contains no business logic: every tool call is a thin RPC to a Catalyst cloud function, where authentication, authorization and domain rules live. The one thing it does locally is read media files from disk and upload them through a signed URL.

What publishing means: a published activity lands in the organization's library and appears immediately in the teachers' Manage Activities screen. Participants see it only once a teacher places it in a course. Publishing stocks the library; it does not push content to participants.

Install

Requires Node.js 20 or newer.

Add to your .mcp.json (Claude Code) or MCP client configuration:

{
  "mcpServers": {
    "bewell-catalyst": {
      "command": "npx",
      "args": ["-y", "bewell-catalyst-mcp"],
      "env": {
        "BEWELL_CATALYST_API_KEY": "bwc_...",
        "BEWELL_CATALYST_FUNCTIONS_BASE_URL": "https://europe-west1-bewellit-prod-eu.cloudfunctions.net"
      }
    }
  }
}

Related MCP server: rustici-mcp-server

Environment variables

API keys and storage are per-environment: a key minted for the EU environment only works against the EU base URL, and media uploaded in one environment cannot be referenced from the other.

Getting an API key

Keys are minted by a platform administrator in the Catalyst admin UI (there is no self-serve issuance). A key manages one or more organizations and carries the publishing scope, which covers every tool in this server. Keys can expire and can be revoked at any time; treat them as secrets. If you don't know which organizationId values a key manages, call list_organizations.

Tools (15)

Identity and idempotency

Activities are addressed by (organizationId, contentSlug). The slug namespace is shared across all types: one slug names exactly one activity per organization, and its type can never change after creation. Creating with an existing slug (same type, MCP-created) acts as an update; retries are safe.

Only activities created through this MCP can be updated or deleted. Activities authored in-app are readable via get_activity / list_activities but never writable here.

Working with multiple organizations

A single key can manage several organizations. There is still one key and one config entry — you choose which organization a call targets purely through the organizationId argument on each tool. Switching organizations means passing a different organizationId; there is no config edit and no restart.

• Discover what a key manages with list_organizations (no inputs). It returns { "organizations": [{ "id": "...", "name": "..." }, ...] } (name is the display name, or null if the record is unavailable). Start here whenever you don't already know the organizationId to use.

• Target an organization by passing one of those ids as organizationId to any other tool.

The server enforces membership on every call: a key may only act on the organizations attached to it. A call for an unattached organization is refused with PERMISSION_DENIED — call list_organizations to see the valid ids.

Locking a workspace to one organization (recommended)

When a workspace should only ever touch one organization, set BEWELL_CATALYST_ORG_LOCK to that organization's id. Every org-scoped tool then refuses any other organizationId client-side, before any network call, naming both the locked and the attempted organization. list_organizations remains available (read-only discovery is harmless).

The recommended pattern is one .mcp.json entry per project, each locked to that project's organization — so a Claude session working in that project physically cannot drift to another organization even though the key could reach several:

{
  "mcpServers": {
    "bewell-catalyst": {
      "command": "npx",
      "args": ["-y", "bewell-catalyst-mcp"],
      "env": {
        "BEWELL_CATALYST_API_KEY": "bwc_...",
        "BEWELL_CATALYST_FUNCTIONS_BASE_URL": "https://europe-west1-bewellit-prod-eu.cloudfunctions.net",
        "BEWELL_CATALYST_ORG_LOCK": "your-org-id"
      }
    }
  }
}

Multi-organization sessions (rare, operator-driven) simply omit the lock. The lock is a convenience guard against accidental cross-organization writes; the server-side membership check remains the hard boundary either way.

Per-type contracts

Common required fields: organizationId, contentSlug, name. Common optional fields: description, tags, author, analyticsId, isPractice, includeInAiChat.

durationSeconds is a positive integer (max 86400) and is not probed server-side: measure the real duration locally (for example with ffprobe) and pass it.

analyticsId enables completion tracking and is write-once: it can be set on create (recommended value: the contentSlug) or added later, but never changed or cleared once set. Without it the activity is untracked.

Media workflow

Always upload_media first, then pass the returned finalUrl into the create/update call. Media URL fields only accept finalUrl values minted for your own organization and environment: external URLs are rejected.

filePath must be a local path on the machine running the MCP server. The MIME type is inferred from the extension (pass contentType explicitly to override). Re-uploading with the same role and the same file extension overwrites the previous file; the same role with a different extension creates a sibling file instead. That is harmless: only the finalUrl you pass to create/update is referenced, and delete_activity's folder cleanup collects any orphans. inline creates a new file per call.

Update semantics (PATCH)

update_* tools patch, they do not replace:

• Omitted optional field: the stored value is preserved.

• Explicit null: the stored value is cleared (tags: [] clears tags).

• name and the type's required fields (for example contentUrl + durationSeconds for video) must be re-sent on every update.

• analyticsId: omit to preserve. Changing or clearing an existing value is refused.

• type is immutable; the update tools re-assert it and the server verifies it matches.

Deleting

delete_activity removes the activity document and best-effort deletes its uploaded media. Two caveats:

1. Placements are not checked. If a teacher has placed the activity in a course template or course, deleting it leaves a dangling reference (the app renders nothing for it). Check with the teacher before deleting anything that may be in use.

2. Only MCP-created activities can be deleted.

Deletion is idempotent: a missing slug returns {"deleted": false, "reason": "not-found"} without error. In a successful response, mediaCleanedUp: false means the document was deleted but the media folder could not be cleaned up.

Error glossary

Development

npm install
npm run build   # tsc -> dist/
npm run lint    # eslint
npm test        # vitest

License

MIT