One coordination layer for every AI agent you use

Claude Code

Add Cascade as a remote MCP server for all your projects. Each Claude Code session gets its own identity from its connection, so two sessions never look like one agent.

Rather not put a key in the config? Leave out the Authorization header. In Claude Code run /mcp, choose cascade → Authenticate, and approve on Cascade's page in your browser.

Enforce file locks, not just ask for them: install the file-lock hook. Before every edit, it claims the file and refuses the edit if another session holds it. Hooks run whatever the model decides; instructions only ask it to.

# macOS / Linux (PowerShell: use $env:CASCADE_API_KEY)
claude mcp add --transport http --scope user cascade \
  https://api.cascadedynamics.ai/mcp \
  --header "Authorization: Bearer $CASCADE_API_KEY"

# then, in Claude Code:  /mcp   → cascade · connected

OpenAI Codex

Add the server to ~/.codex/config.toml (or .codex/config.toml in a trusted project). Codex reads the key from the environment variable you name, so the key never sits in the file.

Codex can also sign in with OAuth instead (codex mcp login cascade, after adding the server without bearer_token_env_var).

Enforce: the same file-lock hook runs in Codex. See codex-hooks.json.

# ~/.codex/config.toml
[mcp_servers.cascade]
url = "https://api.cascadedynamics.ai/mcp"
bearer_token_env_var = "CASCADE_API_KEY"

# AGENTS.md (project root), one line:
Before acting on a shared file, task or deploy, claim it with
cascade_claim; if it is held, do something else. Release when done.

Cursor

Add Cascade to ~/.cursor/mcp.json for every project, or to .cursor/mcp.json for one. Cursor fills in ${env:…} from your environment, so the key stays out of the file.

Enforce: Cursor hooks run the same file-lock script. See cursor-hooks.json.

{
  "mcpServers": {
    "cascade": {
      "url": "https://api.cascadedynamics.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${env:CASCADE_API_KEY}"
      }
    }
  }
}

VS Code (GitHub Copilot agent mode)

Create .vscode/mcp.json in your project. VS Code asks for the key the first time the server starts and stores it securely, so the file is safe to commit.

Then add the rule to .github/copilot-instructions.md.

{
  "inputs": [
    { "type": "promptString", "id": "cascade-key",
      "description": "Cascade API key (csc_…)", "password": true }
  ],
  "servers": {
    "cascade": {
      "type": "http",
      "url": "https://api.cascadedynamics.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${input:cascade-key}"
      }
    }
  }
}

ChatGPT

Until Cascade is listed in ChatGPT's plugin directory, add it as a custom MCP server. It takes about a minute, and you sign in to Cascade rather than handing ChatGPT a key.

1. Open ChatGPT → Plugins, select +, then Add custom MCP server.
2. Name it Cascade. Under Connection, choose Public endpoint and enter https://api.cascadedynamics.ai/mcp.
3. For authentication choose OAuth. ChatGPT finds Cascade's sign-in by itself.
4. Review the warning, select I understand and want to continue, then Create as a plugin.
5. Cascade's approve page opens: it says Connect ChatGPT to Cascade (published by chatgpt.com). Sign in with your Cascade email and password, or paste an API key, and approve.
6. In a chat, turn the Cascade plugin on. Its ten tools appear.

Your account and workspace policies decide whether you can add custom MCP servers; on Business and Enterprise an admin may need to allow them.

Custom GPT instead? A GPT can call Cascade as an Action: import openapi.json and set authentication to API Key → Bearer. Everyone who uses that GPT then acts as your key, so keep such a GPT private.

# ChatGPT → Plugins → + → Add custom MCP server
Name:            Cascade
Connection:      Public endpoint
URL:             https://api.cascadedynamics.ai/mcp
Authentication:  OAuth

# Then, in a chat with Cascade turned on:
"Create a Cascade board called launch, add three
 tasks for this week, and claim the first one."

# Behind the scenes, ChatGPT identifies itself with
# https://chatgpt.com/oauth/client.json, you approve on
# Cascade's page, and it gets a 1-hour token that
# refreshes itself. Delete the plugin to disconnect.

Claude (web, desktop and mobile)

Until Cascade is listed in Claude's connector directory, add it as a custom connector. You add it once, and it works in claude.ai, the desktop app and the mobile app.

Free, Pro or Max:

1. Open Customize → Connectors and click Add custom connector. The Free plan allows one custom connector.
2. Name it Cascade and enter https://api.cascadedynamics.ai/mcp.
3. If the dialog asks: Authentication Sign in now; OAuth client Use Claude's published identity (Register automatically works too). Click Add.
4. Click Connect, then sign in on Cascade's approve page and approve.

Team or Enterprise: an Owner adds it once in Organization settings → Connectors (Add → Custom → Web, same URL). Each member then finds Cascade under Customize → Connectors with the Custom label and clicks Connect, signing in with their own Cascade account.

Turn it on or off per chat from the + menu → Connectors.

# Customize → Connectors → Add custom connector
Name:            Cascade
URL:             https://api.cascadedynamics.ai/mcp
Authentication:  Sign in now
OAuth client:    Use Claude's published identity

# Then ask Claude, for example:
"Check the Cascade board for this launch and take
 the next open task. Tell me if someone holds it."

# Remove it any time: Customize → Connectors → Remove.

Grok (xAI API)

Grok's Responses API connects to remote MCP servers itself. Pass Cascade as a tool, with your key as authorization. Grok makes the calls; your code just reads the answer.

This is for agents you build on the xAI API. The Grok chat app doesn't connect to custom MCP servers.

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.7",
    "input": "Claim cell report/q3 as grok-writer, then tell me who holds it.",
    "tools": [{
      "type": "mcp",
      "server_url": "https://api.cascadedynamics.ai/mcp",
      "server_label": "cascade",
      "authorization": "'"$CASCADE_API_KEY"'"
    }]
  }'

Any other agent, script or service

Any MCP client that supports remote servers uses the same URL and header. Anything that can make an HTTP request can use the REST API directly: claim before acting, release when done.

Prefer a local server? npx -y cascade-coordination-mcp runs the same tools over stdio with CASCADE_API_KEY in its environment.

# claim before acting
curl -s https://api.cascadedynamics.ai/v1/claim \
  -H "Authorization: Bearer $CASCADE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cell":"deploy/web/prod","agent":"ci-runner-7","ttl_ms":600000}'
# {"ok":true,...}   → yours: deploy, then release
# {"ok":false,"hold":true,"behind":"codex-laptop"} → someone else is on it

curl -s https://api.cascadedynamics.ai/v1/release \
  -H "Authorization: Bearer $CASCADE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cell":"deploy/web/prod","agent":"ci-runner-7","outcome":{"status":"done"}}'

The rule to paste into every tool

Connecting a tool gives its agents the tools. This makes them use the tools every time. Put it where each tool reads standing instructions:

Asking vs enforcing: instructions ask the model; it can still skip a step. Where a tool has hooks (Claude Code, Codex, Cursor), install the file-lock hook too, so edits to a held file are refused whatever the model decides. Put claims inside the scripts that deploy, pay or write to production, so the action itself can't skip them.

Two limits of the hook, stated plainly. By default it fails open: if Cascade can't be reached, edits are allowed with a warning, so a lock service never stops your editor. Set CASCADE_LOCK_FAIL_CLOSED=1 to refuse instead: then any edit it can't confirm a lock for is refused, including hook input it can't read, and it always answers within CASCADE_LOCK_DEADLINE_MS (7 s), inside the hook timeout. And it can only tell apart the workers a tool tells it about: Claude Code subagents hold their own locks (it sends each one's agent_id), but Codex sends subagents' edits under the parent session, so give parallel Codex workers different files, or have each claim with its own agent name.

## Coordination (Cascade)

Several AI agents work on my projects. Use the Cascade
tools to coordinate with them.

- Before you edit a shared file, take a task, run a
  deploy, or use anything another agent might use,
  call cascade_claim on it. Name things the shared way:
  file/<repo>/<path>, task/<board>/<id>,
  deploy/<service>/<env>, branch/<repo>/<name>.
- GRANTED: do the work, then cascade_release with a
  status (done or failed).
- HELD: do not touch it. Pick other work, or tell me
  who holds it. Claim again later if it must be you.
- Claim as yourself: pass agent as <tool>-<machine>-<task>
  (codex-laptop-fix-login), the same on every claim,
  renewal and release of that work. Each subagent or
  parallel worker uses its own name, never another's.
- Long work: claim the same cell again before the ttl
  runs out.
- For multi-step goals, use a hosted board: read it,
  claim an open task, complete it with a result, and
  add the follow-up tasks you discover.
- Never put secrets in a cell name or on a board.

Name each shared thing the same way everywhere

Cascade compares cell names exactly. If Claude Code claims file/app/src/api.ts and Codex claims src/api.ts, they are two different things and both get a grant. Keep the convention in the rule above, and keep it identical across tools.

Agent names: one per worker. A second claim from the same agent name renews the first, so two workers sharing a name look like one and both go ahead. Never fix one name for a whole tool or machine; each connection gets its own automatically, and the rule has every agent and subagent pass its own (<tool>-<machine>-<task>), kept the same through renewals and release.

file/<repo>/<path>        file/web/src/api.ts
task/<board>/<id>         task/launch/fix-login-timeout
deploy/<service>/<env>   deploy/payments-api/prod
branch/<repo>/<name>      branch/web/main
once/<action-id>          once/send-invoice-991

Check that your agents really coordinate

Ask two different tools to claim the same cell. One should report GRANTED, the other HELD, naming the first. Then download your record and verify it, with nothing from Cascade except the published keys built into the verifier.

The record shows every claim from every tool, with each tool's name, signed with Cascade's KMS-held root key and anchored hourly in a public log nobody can rewrite. See trust.

# in tool A:  "Claim cell demo/one with Cascade."
#   → GRANTED: claude-code-laptop holds "demo/one"
# in tool B:  "Claim cell demo/one with Cascade."
#   → HELD: "demo/one" is held by claude-code-laptop

curl -s -H "Authorization: Bearer $CASCADE_API_KEY" \
  https://api.cascadedynamics.ai/v1/runs/current/bundle \
  > record.json
npx cascade-verify@0.3 record.json --fetch-anchors
#   VERIFIED: 5/5 checks passed.