cascade-cms-mcp-server

An MCP (Model Context Protocol) server that exposes Cascade CMS operations to LLMs and agents. It wraps cascade-cms-api with Zod validation, JSON responses, structuredContent, and actionable errors.

Built in TypeScript on Bun. It provides Cascade asset tools, draft workflows, file-data helpers, browser-backed tools, guardrails, and local cache inspection.

Start with Setup for required values and client config. Use What It Can Do to judge fit. Agent Reference covers tool-call mechanics.

Setup

Requirements

• Node 20+.

• 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 command, args, CASCADE_API_KEY, and CASCADE_URL. Browser-backed tools also need CASCADE_BROWSER_USERNAME, CASCADE_BROWSER_PASSWORD, and CASCADE_BROWSER_SITE_ID. Use bunx when available; use npx otherwise.

The credentials below are placeholders. Use your MCP client's secret/env handling, local environment, or dotseal-encrypted values for real credentials.

For Cascade API access, consider using a dedicated service/API user when your organization can provide one. Give that user only the permissions needed for the MCP workflows instead of using a personal account.

MCP Client Config

Use one of these shapes for JSON-based MCP configs.

{
  "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/",
        "CASCADE_BROWSER_USERNAME": "browser_username",
        "CASCADE_BROWSER_PASSWORD": "browser_password",
        "CASCADE_BROWSER_SITE_ID": "production_site_id",
        "CASCADE_BROWSER_URL": "https://yourorg.cascadecms.com/"
      }
    }
  }
}

Node/npm fallback:

{
  "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/",
        "CASCADE_BROWSER_USERNAME": "browser_username",
        "CASCADE_BROWSER_PASSWORD": "browser_password",
        "CASCADE_BROWSER_SITE_ID": "production_site_id",
        "CASCADE_BROWSER_URL": "https://yourorg.cascadecms.com/"
      }
    }
  }
}

Omit CASCADE_BROWSER_URL when the browser login host matches the origin derived from CASCADE_URL.

For UI-based clients, enter the same values:

Restart the client after config changes. Call cascade_server_version to confirm the server is running.

Client-Specific Examples

Client-specific setup screens and config file locations vary. Use the same command, args, and env values above.

Codex uses ~/.codex/config.toml:

[mcp_servers.cascade-cms]
command = "bunx"
args = ["cascade-cms-mcp-server"]

[mcp_servers.cascade-cms.env]
CASCADE_API_KEY = "your_api_key_here"
CASCADE_URL = "https://yourorg.cascadecms.com/api/v1/"
CASCADE_BROWSER_USERNAME = "browser_username"
CASCADE_BROWSER_PASSWORD = "browser_password"
CASCADE_BROWSER_SITE_ID = "production_site_id"
CASCADE_BROWSER_URL = "https://yourorg.cascadecms.com/"

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. 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 configs that use npx may need command: "cmd" with args ["/c", "npx", "-y", "cascade-cms-mcp-server"].

Encrypted Environment Values

All environment values below may use dotseal ciphertexts in enc:<iv>:<authTag>:<ciphertext> format. Plaintext values still work.

Generate ciphertext with dotseal:

bunx dotseal encrypt "your_api_key_here"

Example:

"env": {
  "CASCADE_API_KEY": "enc:...",
  "CASCADE_URL": "https://yourorg.cascadecms.com/api/v1/",
  "CASCADE_BROWSER_USERNAME": "browser_username",
  "CASCADE_BROWSER_PASSWORD": "enc:...",
  "CASCADE_BROWSER_SITE_ID": "production_site_id",
  "CASCADE_BROWSER_URL": "https://yourorg.cascadecms.com/"
}

Environment Variables

Browser API Setup

Standard Cascade API tools only require CASCADE_API_KEY and CASCADE_URL. Browser-backed tools also log in through Cascade's browser UI, cache a session cookie in the MCP process, and call browser-only endpoints.

Recommended browser setup:

1. Set CASCADE_BROWSER_USERNAME, CASCADE_BROWSER_PASSWORD, and CASCADE_BROWSER_SITE_ID together before starting the MCP server.

2. Use the production site ID for CASCADE_BROWSER_SITE_ID unless you intentionally want browser tools scoped to another site.

3. Set CASCADE_BROWSER_URL only when the browser login host differs from the origin derived from CASCADE_URL. The browser host must match CASCADE_URL or share its parent domain.

The site ID is required because Cascade's browser UI keeps an active site context. Browser login calls switchSite.act after authentication to mirror selecting a site in Cascade's site picker.

Browser-backed requests start at most once every 3 seconds per MCP session to avoid pressuring Cascade's browser UI endpoints. This applies to startup login, auto-login, retries, draft checks, and snippet tools. Standard Cascade API tools are unaffected.

Find the Site ID

CASCADE_BROWSER_SITE_ID is the browser setup value users usually need to look up. To get the recommended production site ID:

1. Log in to Cascade in a browser.

2. Select the production site from the site picker.

3. Open Manage Site.

4. Copy the site ID from the browser URL into CASCADE_BROWSER_SITE_ID.

If CASCADE_API_KEY and CASCADE_URL are already configured, you can ask your MCP agent to list Cascade sites. The agent can call the cascade_list_sites tool and use the production site's ID from that response. This depends on the API user's permissions and may not show the intended production site.

When all three browser values are present, startup attempts browser login and caches the session. If startup login fails, the MCP server still starts and standard API tools remain available. Without CASCADE_BROWSER_SITE_ID, call cascade_browser_login with site_id before other browser-backed tools in the same MCP session.

Related MCP server: TDX MCP Server

What It Can Do

Use this section to decide whether this MCP covers the job. Your MCP client or agent reads the exact tool schemas and chooses the tool calls.

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

Agent Reference

These sections are mainly for agents and users configuring MCP approvals. They cover response handling, tool groups, workflow examples, guardrails, and MCP resources.

Response Model

Most tool responses put JSON text in content[0]. When present, 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 plus an asset_handle by default. Use read_mode: "raw" only when you need the full Cascade payload immediately. Follow-up tools inspect cached data and do not call Cascade again.

cascade_file_data_image returns image-only MCP content. Call cascade_file_data_info separately for JSON metadata.

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, change Cascade state, or mutate local MCP state such as drafts and guardrails.

Read-only tools:

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.

Structured-data selectors support expected_matches to assert exact match counts.

File data tools:

Use these for Cascade file assets whose binary content is stored in file.data. Each tool accepts an asset_handle from cascade_read or a direct file identifier.

cascade_create, cascade_edit, and cascade_draft_submit accept file.data as signed Java bytes (-128..127) or unsigned file bytes (0..255) and send Cascade signed bytes. cascade_file_data_export writes to an explicit local path, refuses overwrites unless overwrite: true, and can verify expected_sha256.

Draft workflow tools:

Drafts are mutable, in-memory payloads for cascade_create or cascade_edit.

• Edit drafts start from a cached asset_handle; create drafts start from an asset envelope or scaffold.

• Patch tools mutate only the local draft addressed by draft_handle.

• cascade_draft_set_file_data reads exactly one of input_path or base64_data, normalizes bytes to signed file.data, and keeps bytes outside draft JSON until submit.

• cascade_draft_submit validates the final payload, checks tool-block rules, re-reads edit sources to reject stale drafts, and then calls Cascade.

Approval recommended:

High-impact approval recommended:

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

Edit from a cached read without reconstructing the full payload in chat:

{
  "tool": "cascade_draft_open",
  "arguments": {
    "operation": "edit",
    "asset_handle": "a_550e8400-e29b-41d4-a716-446655440000",
    "expected_raw_hash": "ce4136fed2dd50c2a7eaf8f6802a5f7820515dda57f0a7f91a47861db6c8fff4"
  }
}

{
  "tool": "cascade_draft_apply_patch",
  "arguments": {
    "draft_handle": "d_550e8400-e29b-41d4-a716-446655440001",
    "expected_revision": 1,
    "operations": [
      {
        "op": "replace",
        "path": "/asset/page/structuredData/structuredDataNodes/4/structuredDataNodes/9/text",
        "value": "<p>Updated HTML</p>"
      }
    ]
  }
}

{
  "tool": "cascade_draft_submit",
  "arguments": {
    "draft_handle": "d_550e8400-e29b-41d4-a716-446655440001",
    "expected_revision": 2,
    "discard_on_success": true
  }
}

Rules meant to block submitted drafts may target cascade_draft_submit. Use cascade_create and/or cascade_edit when the same rule should also block direct create/edit calls.

Scaffold a create draft when starting from an asset type instead of a read:

{
  "tool": "cascade_draft_scaffold_create",
  "arguments": {
    "asset_type": "page",
    "relationship_style": "path"
  }
}

The response includes the draft handle, scaffolded asset envelope, and required placeholders to patch before validation or submit. To scaffold from a cached asset, use cascade_draft_scaffold_from_asset with the asset_handle and raw_hash from cascade_read.

Set binary file data on a file draft before submit:

{
  "tool": "cascade_draft_set_file_data",
  "arguments": {
    "draft_handle": "d_550e8400-e29b-41d4-a716-446655440001",
    "expected_revision": 1,
    "input_path": "C:\\tmp\\image.jpg"
  }
}

Provide exactly one of input_path or base64_data. The tool normalizes bytes to Cascade signed file.data, preserves existing string text, and keeps the byte payload outside draft JSON until submit.

Search for pages:

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

Guardrails: Blocked Tool Calls

Use cascade_tool_blocks to list or add local rules that block matching tool calls before they reach Cascade. Rules live at ~/.cascade-cms-mcp-server/tool-blocks.json.

Each rule needs tools plus at least one selector: url, id, or path. Explicit id and path selectors also need type. reason is optional and appears in the blocked-call error.

Use cascade_protect_site_removal to generate removal safeguards for accessible sites and their root folders. It replaces its previous generated rules and preserves unrelated rules.

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

Resources

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 cascade_draft_open reports an expected_raw_hash mismatch, rerun cascade_read and use the current raw_hash.

• If cascade_draft_submit reports that the source asset changed, rerun cascade_read and open a fresh draft.

• If a draft patch or submit reports an expected_revision mismatch, inspect the draft and retry with the current revision.

• 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

• Credentials are loaded from environment variables only. Keep real values in the local MCP client environment, a client secret store, or dotseal-encrypted env values.

• Cached reads, drafts, and browser sessions are in-memory and process-scoped. Restart the MCP server to clear them.

• Draft and write tools check blocked-call rules before mutating local state or calling Cascade.

• Error messages are redacted before being logged or returned.

• Input validation rejects unknown fields at the MCP boundary.

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