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 UI root 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

The server runs up to 10 normal Cascade API operations concurrently by default. Set CASCADE_MAX_CONCURRENT_REQUESTS to a positive safe integer to change the limit. Each permit covers one complete logical client operation, including upstream retries. Additional operations wait in FIFO order until a permit becomes available; the normal-operation waiting queue has no fixed limit. CASCADE_TIMEOUT_MS begins when the queued operation starts, not while it waits.

This is a logical-operation limit, not an exact physical-fetch limit. One upstream operation may issue multiple HTTP requests, so physical request concurrency can exceed CASCADE_MAX_CONCURRENT_REQUESTS.

Rare timeout limitation: the upstream client reports a timeout without aborting the underlying fetch. A timed-out fetch may remain active briefly after the logical operation releases its permit.

CASCADE_MAX_CONCURRENT_REQUESTS applies only to normal Cascade client calls. Purely local operations do not consume permits, and browser-backed operations use the separate serialized queue below. Composite workflows acquire a permit for each normal client call rather than for the entire MCP tool invocation.

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 UI root differs from the origin derived from CASCADE_URL. It must use HTTPS. The hosts must match, have a parent/subdomain relationship, or both be under cascadecms.com (for example, tenant.cascadecms.com and tenant-admin.cascadecms.com). Credentials, queries, and fragments are rejected.

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 session operations run one at a time per MCP session so login, site selection, cookie use, expiry recovery, and retries cannot interleave. Up to 20 additional browser session operations wait in FIFO order. Browser-backed physical requests still start at most once every 3 seconds per MCP session to avoid pressuring Cascade's browser UI endpoints. Standard Cascade API operations use the separate concurrency limit above.

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 api_list_sites 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 local_read_cached_response with that handle to page through the full serialized response. characters_total, characters_returned, and offsets use JavaScript UTF-16 code units. bytes_total and bytes_returned remain as deprecated compatibility aliases and are not byte counts. Handles are process-scoped and may be evicted after later calls.

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

Direct Cascade REST tools use the api_ prefix. Browser-backed, cached-asset, file-data, draft, and local utility tools keep their distinct namespaces.

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.

Read-only cached-asset JSON Pointer and pointer-prefix fields reject the reserved object-key segments __proto__, prototype, and constructor.

File data tools:

Use these for Cascade file assets whose binary content is stored in file.data. Each tool accepts an asset_handle from api_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.

api_create, api_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 api_create or api_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_open and local_draft_validate return cascade_url, asset_title, asset_display_name, asset_path, asset_parent_id, asset_parent_path, asset_type, asset_name, asset_site_name, and asset_site_id. Unavailable values are null.

• They also return approval_asset, approval_path, and approval_url for clients with compact approval previews. approval_asset uses the first nonempty display name, title, or asset name.

• If a patch could change any approval field, run local_draft_validate afterward and pass its final values to local_draft_submit; otherwise the values from local_draft_open remain current.

• local_draft_submit verifies the asset fields and any supplied preview aliases, 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": "api_read",
  "arguments": {
    "identifier": {
      "id": "d3631e59ac1easd2434bd70be3fbfe8148abc",
      "type": "page"
    }
  }
}

Read a folder by path:

{
  "tool": "api_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 api_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": {
    "approval_asset": "Example Page",
    "approval_path": "/example",
    "approval_url": "https://example.cascadecms.com/entity/open.act?id=page-001&type=page",
    "cascade_url": "https://example.cascadecms.com/entity/open.act?id=page-001&type=page",
    "asset_title": "Example page",
    "asset_display_name": "Example Page",
    "asset_path": "/example",
    "asset_parent_id": null,
    "asset_parent_path": "/",
    "asset_type": "page",
    "asset_name": "example",
    "asset_site_name": "my-site",
    "asset_site_id": null,
    "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 api_create or api_edit when the same rule should also block direct calls and matching local draft workflows before local draft work continues. For api_create, path rules match the intended parent path plus asset name once both are known.

New rules should use current tool names. Existing unprefixed and cascade_* direct REST names remain compatible during rule matching.

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 api_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": "api_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": ["api_remove", "api_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 api_read and use the current raw_hash.

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