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:

| 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, browser env values when using browser-backed tools, optional CASCADE_TIMEOUT_MS | Same |

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

| 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 | | CASCADE_BROWSER_USERNAME | Browser API | Browser UI username for browser-backed tools | | CASCADE_BROWSER_PASSWORD | Browser API | Browser UI password for browser-backed tools | | CASCADE_BROWSER_SITE_ID | Browser API | Cascade site ID for browser-backed tools. Use the production site ID by default | | CASCADE_BROWSER_URL | No | HTTPS browser UI root URL. Defaults to the origin derived from CASCADE_URL. Set this when the browser login host or root path differs |

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.

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.

| 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 | | Inspect binary file.data, read bounded byte ranges, return image content, and export files locally | Yes | | Build, inspect, patch, validate, and submit complete create/edit asset drafts | Yes | | Authenticate to the Cascade browser UI and cache a browser session | Yes | | Check the browser-only active editing draft notification for an asset | Yes; requires browser API config or prior browser_login, plus asset_id and asset_type | | List, create, update, and delete browser-admin snippets | Yes; requires browser API config or prior browser_login | | Fetch additional bytes from large/truncated responses | Yes | | Persist blocked-call rules that prevent matching MCP 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.

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:

| Tool | Purpose | | --------------------------- | -------------------------------------------------- | | read | Read an asset and return a preview or raw response | | search | Search Cascade assets | | list_sites | List Cascade sites | | read_access_rights | Read access rights for an asset | | read_workflow_settings | Read workflow settings for a folder | | read_workflow_information | Read workflow information for an asset | | list_subscribers | List subscribers for an asset | | list_messages | List Cascade messages | | read_audits | Read audit log entries | | read_preferences | Read system preferences |

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.

| Tool | Purpose | | ----------------------- | ----------------------------------------------------------------- | | browser_check_draft | Check browser-only active editing draft notification for an asset | | browser_list_snippets | List browser-admin snippets with pagination |

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.

| Tool | Purpose | | ----------------------------- | ------------------------------------------------------------------ | | server_version | Read this MCP server's name and version | | read_response | Fetch more text from a cached oversized response | | asset_list_facts | List indexed raw JSON facts from a cached read | | asset_search_values | Search scalar values in a cached read | | asset_search_keys | Search object keys in a cached read | | asset_get_value | Fetch one raw JSON value from a cached read | | asset_list_scalar_artifacts | List links, paths, and similar scalar artifacts from a cached read | | asset_list_references | List Cascade references found in a cached read | | asset_list_nodelets | List structured-data nodelets from a cached read | | asset_get_nodelet | Fetch one structured-data nodelet from a cached read | | asset_resolve_nodes | Resolve structured-data nodes by semantic criteria | | asset_assert_values | Assert structured-data field values from a cached read |

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.

| Tool | Purpose | | ------------------ | ----------------------------------------------------------------------- | | file_data_info | Return byte count, SHA-256, detected MIME/kind, and a short hex preview | | file_data_read | Return a bounded byte range as hex or base64 | | file_data_image | Return magic-byte verified image files as image-only MCP content | | file_data_export | Write exact bytes to an explicit local output_path |

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:

| Tool | Purpose | | ----------------------------------- | ---------------------------------------------------- | | local_draft_get_value | Fetch one JSON value from a draft | | local_draft_list_facts | List indexed JSON facts from a draft | | local_draft_search_values | Search scalar values in a draft | | local_draft_search_keys | Search object keys in a draft | | local_draft_list_references | List references in a draft | | local_draft_list_scalar_artifacts | List links, paths, and similar artifacts in a draft | | local_draft_list_nodelets | List structured-data nodelets in a draft | | local_draft_get_nodelet | Fetch one structured-data nodelet from a draft | | local_draft_resolve_nodes | Resolve structured-data nodes by semantic criteria | | local_draft_assert_values | Assert structured-data field values in a draft | | local_draft_validate | Validate a draft without calling Cascade |

Approval recommended for local MCP state or filesystem changes:

| Tool | State change | | ----------------------------------- | ----------------------------------------------------------------------------------------- | | local_draft_open | Creates a mutable local draft from a read snapshot or initial asset payload | | local_draft_scaffold_create | Creates a mutable local create draft with required placeholders for one asset type | | local_draft_scaffold_from_asset | Creates a mutable local create draft from a cached asset shape | | local_draft_apply_patch | Mutates a local draft with JSON Pointer patch operations | | local_draft_apply_semantic_patch | Mutates a local draft after resolving structured-data nodes semantically | | local_draft_mutation_plan_execute | Runs local draft workflow steps sequentially and stops on first failure | | local_draft_set_file_data | Sets signed Cascade file bytes on a local file draft from exactly one path or base64 payload | | file_data_export | Writes Cascade file bytes to an explicit local filesystem path | | browser_login | Authenticates to the browser UI and stores a local browser session for later browser tools | | tool_blocks | Changes the local blocked-call repository | | protect_site_removal | Changes the local blocked-call repository after reading accessible sites and root folders |

Approval recommended for Cascade or browser-admin changes:

| Tool | State change | | ----------------------------- | ------------------------------------------------------------------- | | create | Creates an asset | | edit | Edits an asset | | local_draft_submit | Creates or edits an asset from the complete validated draft payload | | move | Moves or renames an asset | | copy | Copies an asset | | site_copy | Copies a site | | edit_access_rights | Changes asset access rights | | edit_workflow_settings | Changes workflow settings | | perform_workflow_transition | Performs a workflow transition | | mark_message | Marks a message | | check_out | Checks out an asset | | check_in | Checks in an asset | | edit_preference | Changes a system preference | | browser_create_snippet | Creates a browser-admin snippet | | browser_update_snippet | Updates a browser-admin snippet by ID | | browser_delete_snippets | Deletes one or more browser-admin snippets by ID |

High-impact approval recommended:

| Tool | State change | | --------------------------- | --------------------------------- | | remove | Deletes an asset, except sites and root-folder path / requests | | delete_message | Deletes a message | | publish_unpublish | Publishes or unpublishes an asset |

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

| 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 read preview | | cascade://draft/{handle}/raw | Template | Exact draft JSON unless blocked by draft read tool-block rules, the tool-block repository cannot be read, or the handle is invalid/missing |

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