cascade-cms-mcp-server

An MCP (Model Context Protocol) server that exposes the Cascade CMS REST API to LLMs and agents. It wraps the cascade-cms-api library with Zod validation, JSON response text, structuredContent, and actionable error messages.

Built in TypeScript on Bun. The published server provides 37 MCP tools and 4 resources/templates for Cascade CMS asset reads/writes, search, sites, access rights, workflow, messages, check in/out, audits/preferences, publish, blocked-call management, site-removal safeguarding, server version checks, and cached response retrieval.

Requirements

• Node 18+.
• Bun 1.0+ for the preferred bunx setup.
• A Cascade CMS instance with REST API access and an API key.
• An MCP client that can launch stdio servers, such as Claude, Codex, Cline, MCP Inspector, or another compliant client.

Quick Start

Most MCP clients need the same four values: command, args, CASCADE_API_KEY, and CASCADE_URL. Add them wherever your client manages MCP servers. bunx is the preferred runner; use npx if Bun is not installed.

The example credentials below are placeholders. For real credentials, use your MCP client's secret or environment management when available, or dotseal-encrypted values. Do not commit MCP config files that contain API keys.

MCP Client Config

Use one of these shapes for JSON-based MCP configs. Prefer the Bun example when available. If you prefer to encrypt your API key at rest, continue to Encrypted Environment Values.

Preferred, with Bun:

{
  "mcpServers": {
    "cascade-cms": {
      "command": "bunx",
      "args": ["cascade-cms-mcp-server"],
      "env": {
        "CASCADE_API_KEY": "your_api_key_here",
        "CASCADE_URL": "https://yourorg.cascadecms.com/api/v1/"
      }
    }
  }
}

Fallback, with Node/npm:

{
  "mcpServers": {
    "cascade-cms": {
      "command": "npx",
      "args": ["-y", "cascade-cms-mcp-server"],
      "env": {
        "CASCADE_API_KEY": "your_api_key_here",
        "CASCADE_URL": "https://yourorg.cascadecms.com/api/v1/"
      }
    }
  }
}

For clients with a UI instead of JSON, enter the same values:

Field	Bun value	Node/npm value
Command	bunx	npx
Arguments	cascade-cms-mcp-server	-y, cascade-cms-mcp-server
Environment	CASCADE_API_KEY, CASCADE_URL, optional CASCADE_TIMEOUT_MS	Same

Restart the client after changing its MCP config. Then call cascade_server_version to confirm the running server name and version.

Client-Specific Examples

Client-specific setup screens and config file locations vary. The examples below use the same server values from the generic config above.

Codex uses ~/.codex/config.toml. Prefer Bun when available.

Preferred, with Bun:

[mcp_servers.cascade-cms]
command = "bunx"
args = ["cascade-cms-mcp-server"]
env = { CASCADE_API_KEY = "your_api_key_here", CASCADE_URL = "https://yourorg.cascadecms.com/api/v1/" }

Fallback, with Node/npm:

[mcp_servers.cascade-cms]
command = "npx"
args = ["-y", "cascade-cms-mcp-server"]
env = { CASCADE_API_KEY = "your_api_key_here", CASCADE_URL = "https://yourorg.cascadecms.com/api/v1/" }

Claude Desktop uses claude_desktop_config.json:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Claude Code can use its normal MCP config flow with the same command, args, and env values. This repo also includes a Claude Code plugin manifest in .claude-plugin/plugin.json; if you install the plugin, set credentials in the shell environment that launches Claude Code:

Native Windows Claude Code configs that use npx may need command: "cmd" with args ["/c", "npx", "-y", "cascade-cms-mcp-server"].

POSIX:

export CASCADE_API_KEY="your_api_key_here"
export CASCADE_URL="https://yourorg.cascadecms.com/api/v1/"

Windows PowerShell:

$env:CASCADE_API_KEY = "your_api_key_here"
$env:CASCADE_URL = "https://yourorg.cascadecms.com/api/v1/"

Environment Variables

Variable	Required	Description
CASCADE_API_KEY	Yes	API key generated from your Cascade dashboard
CASCADE_URL	Yes	Cascade API URL, for example https://yourorg.cascadecms.com/api/v1/
CASCADE_TIMEOUT_MS	No	Request timeout in milliseconds. Default: 30000

Encrypted Environment Values

If you prefer keeping your env values encrypted at rest, CASCADE_API_KEY, CASCADE_URL, and CASCADE_TIMEOUT_MS may also be dotseal ciphertexts with the enc:<iv>:<authTag>:<ciphertext> format. This package includes dotseal as a runtime dependency, so encrypted enc: values work when the server runs through bunx or npx. Plaintext values pass through without loading dotseal.

The bundled runtime dependency is not exposed as a dotseal shell command. Use bunx, npx, or a separate global install when you want to generate ciphertexts:

bunx dotseal encrypt "your_api_key_here"

Alternative with npm:

npx dotseal encrypt "your_api_key_here"

Paste the enc:... output into your MCP config or shell environment. If you prefer a global CLI install, bun install -g dotseal or npm install -g dotseal is also fine; it is not required for this server to decrypt values at runtime.

Example MCP config with an encrypted API key:

{
  "mcpServers": {
    "cascade-cms": {
      "command": "bunx",
      "args": ["cascade-cms-mcp-server"],
      "env": {
        "CASCADE_API_KEY": "enc:...",
        "CASCADE_URL": "https://yourorg.cascadecms.com/api/v1/"
      }
    }
  }
}

Response Model

Tool responses are JSON text. When the response fits, structuredContent is the authoritative machine-readable result.

Oversized responses return bounded _cache metadata. Use cascade_read_response with that handle to page through the full serialized response. Handles are process-scoped and may be evicted after later calls.

cascade_read returns a compact preview by default plus an asset_handle for follow-up inspection. Use read_mode: "raw" only when you need the full Cascade payload in the initial response. Follow-up tools inspect the cached asset and do not call Cascade again.

The beta response_format option was removed. Callers should parse content[0].text as JSON or prefer structuredContent when their client exposes it.

Capabilities

Use this section to decide whether this MCP covers the job. Your MCP client or agent will see the exact tool schemas and choose the specific tool calls.

Need	Supported
Read Cascade assets by id or path	Yes
Search assets by terms, fields, type, and site	Yes
Create, edit, move, copy, rename, or delete assets	Yes
Publish or unpublish assets	Yes
List sites	Yes
Read or edit access rights	Yes
Read or update workflow settings and perform workflow transitions	Yes
List messages, mark messages, delete messages, and inspect subscribers/relationships	Yes
Read audit logs and system preferences	Yes
Inspect raw asset content, references, strings, links, paths, and structured-data nodelets after a read	Yes
Fetch additional bytes from large/truncated responses	Yes
Persist blocked-call rules that prevent matching Cascade tool calls from running	Yes
Generate site and root-folder removal safeguards	Yes

Use your MCP client's tool list or inspector for exact request schemas.

Tool Permissions

Use these groups when configuring MCP client approvals. Client config syntax varies, but a common policy is to allow read-only tools by default and require approval for tools that create, update, delete, publish, check in/out, or otherwise change Cascade state.

Read-only tools:

Tool	Purpose
cascade_read	Read an asset and return a preview or raw response
cascade_search	Search Cascade assets
cascade_list_sites	List Cascade sites
cascade_read_access_rights	Read access rights for an asset
cascade_read_workflow_settings	Read workflow settings for a folder or site
cascade_read_workflow_information	Read workflow information for an asset
cascade_list_subscribers	List subscribers for an asset
cascade_list_messages	List Cascade messages
cascade_read_audits	Read audit log entries
cascade_read_preferences	Read system preferences
cascade_server_version	Read this MCP server's name and version
cascade_read_response	Fetch more text from a cached oversized response

cascade_read helper tools:

These tools do not call Cascade directly. They inspect the in-memory asset_handle created by a prior cascade_read preview response.

Tool	Purpose
cascade_asset_list_facts	List indexed raw JSON facts from a cached read
cascade_asset_search_values	Search scalar values in a cached read
cascade_asset_search_keys	Search object keys in a cached read
cascade_asset_get_value	Fetch one raw JSON value from a cached read
cascade_asset_list_scalar_artifacts	List links, paths, and similar scalar artifacts from a cached read
cascade_asset_list_references	List Cascade references found in a cached read
cascade_asset_list_nodelets	List structured-data nodelets from a cached read
cascade_asset_get_nodelet	Fetch one structured-data nodelet from a cached read

Approval recommended:

Tool	State change
cascade_create	Creates an asset
cascade_edit	Edits an asset
cascade_move	Moves or renames an asset
cascade_copy	Copies an asset
cascade_site_copy	Copies a site
cascade_edit_access_rights	Changes asset access rights
cascade_edit_workflow_settings	Changes workflow settings
cascade_perform_workflow_transition	Performs a workflow transition
cascade_mark_message	Marks a message
cascade_check_out	Checks out an asset
cascade_check_in	Checks in an asset
cascade_edit_preference	Changes a system preference
cascade_tool_blocks	Changes the local blocked-call repository
cascade_protect_site_removal	Changes the local blocked-call repository after reading accessible sites and root folders

High-impact approval recommended:

Tool	State change
cascade_remove	Deletes an asset, except sites and root-folder path / requests
cascade_delete_message	Deletes a message
cascade_publish_unpublish	Publishes or unpublishes an asset

Examples

Read a page by id:

{
  "tool": "cascade_read",
  "arguments": {
    "identifier": {
      "id": "d3631e59ac1easd2434bd70be3fbfe8148abc",
      "type": "page"
    }
  }
}

Read a folder by path:

{
  "tool": "cascade_read",
  "arguments": {
    "identifier": {
      "path": { "path": "/about/team", "siteName": "www" },
      "type": "folder"
    }
  }
}

Inspect cached read data after a preview:

{
  "tool": "cascade_asset_search_values",
  "arguments": {
    "asset_handle": "a_550e8400-e29b-41d4-a716-446655440000",
    "value_contains": "admissions"
  }
}

Use the asset_handle returned by cascade_read; cascade_asset_* tools are follow-ups, not first-step Cascade reads.

Search for pages:

{
  "tool": "cascade_search",
  "arguments": {
    "searchInformation": {
      "searchTerms": "admissions",
      "searchTypes": ["page"],
      "searchFields": ["title", "summary"],
      "siteName": "www"
    },
    "limit": 100,
    "offset": 0
  }
}

Create a page:

{
  "tool": "cascade_create",
  "arguments": {
    "asset": {
      "page": {
        "name": "new-page",
        "parentFolderPath": "/about",
        "siteName": "www",
        "contentTypePath": "/standard/content-type"
      }
    }
  }
}

Publish an asset:

{
  "tool": "cascade_publish_unpublish",
  "arguments": {
    "identifier": { "id": "abc123", "type": "page" },
    "publishInformation": { "unpublish": false }
  }
}

Guardrails: Blocked Tool Calls

Use cascade_tool_blocks to list or add blocked Cascade tool-call rules. The rules live in a local JSON file at ~/.cascade-cms-mcp-server/tool-blocks.json. If the file does not exist, the repository is treated as empty; deleting the file removes all stored blocks until new rules are added.

Each rule requires a non-empty tools array plus url, id, or path. url means an HTTPS Cascade CMS asset URL on a .cascadecms.com host at /entity/open.act with id and type query parameters; it does not match published site URLs or symlink/feed/destination target URLs. Explicit id or path selectors require type. URL selectors and explicit selectors can be combined in the same rule; URL selectors use the URL's own type, while explicit id and path selectors use the rule's top-level type. Each selector may be a string or an array of strings. reason is optional and appears in the blocked-call error.

Before a checked Cascade tool runs, the server reads this JSON repository and blocks the call if the tool name and payload match a rule. If the JSON file is malformed or cannot be read, checked Cascade tools fail closed before calling Cascade. Local helper tools (cascade_asset_*), cascade_read_response, and cascade_server_version do not consult the repository because they only inspect cached local data or server metadata.

Because cascade_tool_blocks can add guardrails, MCP clients should require user approval before calling it. It cannot remove or replace existing guardrails; delete or edit the local JSON file directly when intentional cleanup is required.

Use cascade_protect_site_removal to generate removal safeguards for accessible sites and their root folders. It lists sites, blocks cascade_remove for those site IDs and site names/paths, reads each root folder at /, blocks readable root folders by ID, and also blocks folder path / as a path-based root-folder fallback. Existing generated rules from this tool are replaced when it runs again; unrelated rules stay in place. The response reports unreadable root folders so you know which root IDs could not be added.

Example stored rules:

[
  {
    "type": "site",
    "id": ["site-123", "site-456"],
    "path": ["Protected Site"],
    "tools": ["cascade_remove", "cascade_edit"],
    "reason": "No site edits or deletes"
  },
  {
    "url": [
      "https://college.cascadecms.com/entity/open.act?id=link-1&type=symlink",
      "https://college.cascadecms.com/entity/open.act?id=link-2&type=symlink"
    ],
    "tools": ["cascade_edit"]
  }
]

Example management calls:

{
  "tool": "cascade_tool_blocks",
  "arguments": {
    "action": "add",
    "rule": {
      "url": "https://college.cascadecms.com/entity/open.act?id=block-1&type=block",
      "tools": ["cascade_remove", "cascade_edit"],
      "reason": "Protected block"
    }
  }
}

{
  "tool": "cascade_tool_blocks",
  "arguments": { "action": "list" }
}

Resources

URI	Kind	Description
cascade://entity-types	Static	Cascade entity type strings with short descriptions
cascade://sites	Dynamic	Live listSites() result
cascade://text-encoding	Static	Text, rich text, XML, format, and template encoding rules
cascade://asset/{handle}/raw	Template	Exact raw JSON cached from a prior cascade_read preview

Troubleshooting

• If tools appear unavailable, verify the MCP client can start the server and that CASCADE_API_KEY and CASCADE_URL are set in the environment used by that client.
• If a cached handle is missing, rerun the originating tool. Handles are in-memory and process-scoped.
• If a rendered response is truncated, call cascade_read_response with the returned handle, offset, and length.
• Most MCP clients write server stderr to client logs. This server keeps stdout reserved for MCP JSON-RPC.

Security Notes

• API keys are loaded from environment variables only. Do not commit MCP config files that contain real credentials.
• cascade_read preview mode caches exact raw asset JSON in memory for follow-up inspection. Restart the MCP server to clear cached asset data.
• Error messages are redacted before being logged or returned.
• Input validation rejects unknown fields at the MCP boundary except for bounded passthrough cases.

License

MIT - see LICENSE.

Related

• cascade-cms-api - underlying JavaScript client library
• dotseal - optional encrypted environment value helper
• Model Context Protocol - protocol specification
• Cascade CMS REST API - upstream API documentation