Windsurf

Overview

Windsurf's standout feature is Cascade — a flow-style agent that can span many steps and many files. Once you give Cascade access to the chisel.to MCP server, a single flow can: read your existing schema, propose a change, execute it, regenerate types, write the client code, run the test suite, and patch anything that breaks.

Three patterns this enables:

• Vertical slices in one flow. Backend table + endpoints + client component + tests, all in one continuous run.
• Self-healing iterations. When the test fails, Cascade reads the failure, checks the live endpoint and adjusts.
• Project-wide refactors with backend awareness. Renaming a column? Cascade can change the schema, regenerate types and update every call site without losing track.

Requirements

• Windsurf (current release with MCP / Cascade support).
• Node.js 18+ on your PATH — the chisel.to MCP bridge runs through npx.
• A chisel.to project with at least one API key.

node --version
# v20.x.x

Get the MCP config from the Connect page

1. Open your project in the chisel.to dashboard.
2. Open the Connect card.
3. Click Download mcp.json. You'll get a file scoped to your specific project.

{
  "mcpServers": {
    "chisel-myapp": {
      "command": "npx",
      "args": [
        "-y",
        "@chisel-to/mcp",
        "--base-url", "https://api.example.com/v1/myapp",
        "--api-key-env", "CHISEL_API_KEY"
      ]
    }
  }
}

Install in Windsurf

Windsurf accepts MCP servers via its settings UI or a config file in your user directory. Either approach works — pick the one that fits your workflow.

Via Windsurf Settings (recommended)

1. Open Windsurf.
2. Go to Settings → Cascade → MCP Servers.
3. Click Add and paste the contents of the mcp.json you downloaded.
4. Save. Windsurf reloads the MCP layer automatically.

Via config file

Save the downloaded JSON to your Windsurf config directory (the exact path appears in Windsurf's MCP settings panel). Windsurf reads it on startup and on reload.

Either way, you can keep a copy of the file inside your repo (e.g. at tools/chisel.mcp.json) so teammates have a reference — even if they install via the UI.

API key as an environment variable

Windsurf passes the parent shell's environment to MCP servers it spawns. Export your key in the shell config file:

export CHISEL_API_KEY="ck_live_…"

Use a test-mode key locally and reserve live keys for production:

# Local dev
export CHISEL_API_KEY="ck_test_…"

# CI / production deploys
export CHISEL_API_KEY="ck_live_…"

Confirm the variable is set in the shell Windsurf launches from:

env | grep CHISEL_API_KEY

Restart Windsurf so it inherits the new environment.

Verify it works

1. Open your workspace in Windsurf.
2. Open Cascade.
3. Inspect the MCP indicator (in the Cascade toolbar). You should see chisel-myapp connected with N tools available.
4. Try the verification prompt below.

List the resources on the chisel.to backend connected to this workspace. For
each, show the column names with their types, and which CRUD operations are
exposed.

If Cascade returns your project's real schema, you're wired up. If it can't see the server, jump to Troubleshooting.

How Cascade flows interact with chisel.to

Cascade's distinguishing trait is that one prompt becomes a multi-step plan. With the MCP server attached, the steps it can take include calling chisel.to tools — list resources, create a table, run a custom endpoint, fetch a record. Two things shape how well it does that:

• Plan visibility. Cascade shows you the plan before it runs. Read it before approving. If it's about to drop a column you wanted to rename, you'll catch it.
• Step-level approval. For destructive operations (delete tables, mass-delete rows), require approval. Workspace rules below set that policy by default.

Common workflows

1. Build a vertical slice

Add a "messages" feature to this app.

Backend (via chisel.to MCP tools):
  - Create a "messages" table: thread_id (FK to threads), user_id (FK to users),
    body (text_long, required), created_at (timestamp, default now).
  - Add an index on (thread_id, created_at).
  - Add a custom query "for_thread" that filters by thread_id and sorts by
    created_at ascending.

Client (this repo):
  - Add MessageList and MessageComposer components in src/messages/.
  - Use the chisel.to TS SDK; do not roll raw fetch calls.
  - Subscribe to realtime channel "thread:{thread_id}" for live updates.

Tests:
  - Add an integration test that posts a message and asserts it appears in
    the for_thread query.

Plan it first; I'll approve before any destructive step.

2. Rename a column safely

Rename the "headline" column on posts to "title". Plan first:
  - Confirm the column exists with the chisel.to tools.
  - Identify every reference in this repo (grep across src/).
  - Decide on a strategy: add new column, backfill, switch reads, drop old.
  - Show me the plan before executing.

When you execute, do the schema change through the MCP tools, then update the
code, then run the type check.

3. Generate an admin tool

Generate an internal admin page at /admin/posts.

Use the chisel.to MCP tools to discover the posts schema, then build a Next.js
page that lists posts with column-aware filters (status, author), supports
inline editing of mutable fields, and triggers the "publish" action on a row
with a button.

Auth: admin pages require a signed-in user with role=admin from the chisel.to
auth endpoints. Render an access-denied state otherwise.

4. End-to-end smoke test

Write a Playwright test that:
  - Calls the chisel.to sign-up endpoint to create a throwaway user.
  - Signs in through the UI.
  - Creates a post in the editor.
  - Asserts it appears in the feed.
  - Cleans up by deleting the user and post via the chisel.to tools at the end.

Use a test-mode API key, not the live key.

5. Investigate a 500

The "publish" action on posts is returning 500 for some rows but not others.
Find a failing row, reproduce the call through the chisel.to MCP tools, read
the response, and tell me what's different. Don't change any code yet —
just diagnose.

Workspace rules for safer Cascade behavior

Windsurf supports workspace-level rules. A short policy file keeps Cascade from doing surprising things with the platform tools.

This project's backend is chisel.to, connected via the MCP server
"chisel-myapp". Prefer calling its tools over guessing endpoint URLs or shapes.

Schema policy:
- Never drop tables or columns without explicit confirmation in the chat.
- Never delete more than 10 rows in a single tool call without confirmation.
- Schema-changing operations must be in the plan and approved before execution.

Coding policy:
- Client code uses the @chisel-to/sdk package. Don't roll raw fetch calls.
- Auth: the SDK persists tokens; don't put them in localStorage directly.
- Validation errors are 422 with { message, errors } — surface the field errors,
  not the whole object.

The write & test loop

One of the highest-yield Cascade patterns is having the flow run tests after each change. With chisel.to MCP attached, the loop becomes:

1. Cascade makes the schema change.
2. Cascade regenerates types or updates the SDK reference.
3. Cascade writes / updates the client code.
4. Cascade runs the tests in the integrated terminal.
5. If a test fails, Cascade reads the failure, hits the live endpoint to verify the contract, and patches whichever side is wrong.

You can prime that loop with a single prompt:

Add the "favorites" feature. After each step, run `npm test`. If a test fails,
diagnose with the chisel.to tools before changing code.

Refreshing context

MCP servers are queried per-prompt, so schema changes flow through automatically on the next message. Two ops reminders:

• If you regenerate the TypeScript SDK, restart your dev server.
• If you change MCP config in Settings, Cascade reloads automatically. If you edit the JSON on disk while Windsurf is running, hit Reload MCP Servers.

Security & key hygiene

• Use a publishable test key locally; a live key only on production.
• Don't store the API key in .windsurfrules or other repo files. Keep it in your shell environment.
• Cascade can rack up many platform calls per flow. Watch your project's Analytics dashboard if a long flow is mid-run.
• If an IP allowlist is on the key, your dev machine has to be on it.

Troubleshooting

"No MCP servers connected" in Cascade

Open Settings → Cascade → MCP Servers and confirm the config is present and saved. If it's there but Cascade can't see it, hit Reload and reopen Cascade.

The server appears but lists zero tools

The MCP bridge ran but couldn't reach your project. Check CHISEL_API_KEY is set in the shell Windsurf launched from (open the integrated terminal and run env | grep CHISEL_API_KEY). If missing, fix the shell config and restart Windsurf.

Cascade plans the change but tries to write SQL files instead of calling the tools

Make sure your workspace rules tell it to prefer the MCP tools over file-based migrations. Without that, the default behavior leans toward writing migration files.

Tool call fails with 401

Wrong key, wrong project, revoked key, or excluded by an IP allowlist — same shortlist as the other MCP guides.

Cascade is too cautious / pauses too often

Loosen the workspace rules around destructive operations, or pre-approve a category in your prompt: "You may freely create tables and indexes without confirmation; only ask before deleting or dropping anything."

Cascade is not cautious enough

Tighten the rules. "Every step must appear in the plan before execution. No tool call without a corresponding plan step."

Next steps

• The same mcp.json drops into Cursor and Claude Code with minor path differences.
• Pair this with the TypeScript SDK guide on the runtime side — or follow the Unreal Engine 5 SDK (coming soon).
• Browse the auto-generated API reference for the exact field types and validation rules.