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 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 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 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 read_response with that handle to page through the full serialized response. Handles are process-scoped and may be evicted after later calls.

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.

file_data_image returns image-only MCP content. Call file_data_info separately for JSON metadata.

Tool Permissions

Use these groups when configuring MCP client approvals. Client config syntax varies. A common policy is to allow read-only inspection by default and require approval for tools that create, update, delete, publish, check in/out, change browser-admin state, write local files, or mutate local MCP state such as drafts and guardrails.

"Read-only" means the tool does not persist a change. It may still call Cascade unless the group says it is local-only.

Cascade API read-only tools:

Browser-backed read-only tools:

These tools call Cascade browser UI endpoints. They use a cached browser session or log in automatically when browser env values are configured.

Local cache and utility read tools:

These tools do not call Cascade directly. They inspect in-memory handles created by earlier tool calls or return MCP server metadata.

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 read or a direct file identifier. With an asset_handle, the tool uses the local cache. With an identifier, it reads the file from Cascade first and caches it.

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

Local draft workflow tools:

Drafts are mutable, in-memory payloads for create or edit. Local draft tools do not change Cascade until local_draft_submit.

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

• local_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.

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

Local draft inspection tools:

Approval recommended for local MCP state or filesystem changes:

Approval recommended for Cascade or browser-admin changes:

High-impact approval recommended:

Workflow Examples

Read a page by id:

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

Read a folder by path:

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

Inspect cached read data after a preview:

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

Use the asset_handle returned by read; asset_* tools are follow-ups, not first-step reads.

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

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

{
  "tool": "local_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": "local_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 local_draft_submit. Use create or edit when the same rule should also block direct calls and matching local draft workflows before local draft work continues. For create, path rules match the intended parent path plus asset name once both are known.

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

{
  "tool": "local_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 local_draft_scaffold_from_asset with the asset_handle and raw_hash from read.

Set binary file data on a file draft before submit:

{
  "tool": "local_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": "search",
  "arguments": {
    "searchInformation": {
      "searchTerms": "admissions",
      "searchTypes": ["page"],
      "searchFields": ["title", "summary"],
      "siteName": "www"
    },
    "limit": 100,
    "offset": 0
  }
}

Guardrails: Blocked Tool Calls

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

The safest access control is still Cascade/API permissions. Tool blocks are an additional MCP-local guardrail for defense in depth, not a replacement for server-side permissions.

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 protect_site_removal to generate remove and move safeguards for accessible sites and their root folders. It replaces its previous generated rules and preserves unrelated rules.

{
  "tool": "tool_blocks",
  "arguments": {
    "action": "add",
    "rule": {
      "url": "https://college.cascadecms.com/entity/open.act?id=block-1&type=block",
      "tools": ["remove", "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 local_draft_open reports an expected_raw_hash mismatch, rerun read and use the current raw_hash.

• If local_draft_submit reports that the source asset changed, rerun 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 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