Cursor

Overview

Cursor supports the Model Context Protocol natively. Once you've registered chisel.to as an MCP server, the editor sees a set of tools the agent can call — one per platform operation (create a table, list resources, run a custom endpoint, issue an API key, etc.). The same configuration powers Chat, Composer and the inline editor's "Ask" panel.

You get three things from this setup:

• Schema-aware autocomplete when you ask the agent to write client code — it sees the real column names and types from your project.
• Direct platform actions when you tell the agent to make a change ("add a leaderboards table") — it executes the change against your project instead of writing migration files.
• Live verification when something doesn't work — the agent can hit your endpoints, read the error and fix the client code in the same step.

Requirements

• Cursor 0.45 or newer (MCP support is stable in current releases).
• Node.js 18+ available on your PATH — the MCP bridge that connects Cursor to chisel.to is an npx-runnable package.
• A chisel.to project with at least one API key. Free-tier projects work fine.

Check Node is present in the same shell environment Cursor launches from:

node --version
# v20.x.x

Get the MCP config from the Connect page

1. Sign in to the chisel.to dashboard.
2. Open your project and click the Connect card.
3. Under "Drop into your AI tool," click Download mcp.json. You'll get a file shaped like the snippet below — generated for your specific project slug and API base URL.

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

Two things worth noticing in that snippet:

• The server is named after your project (chisel-myapp) so multiple projects can coexist if you work on more than one.
• The API key is read from an environment variable, not hard-coded — that keeps secrets out of the repo.

Install in Cursor

Cursor reads MCP servers from two places. Pick one based on whether the integration is per-workspace or system-wide.

Per-workspace (recommended)

Use this when one project = one repo. The config travels with the code and you can commit it without leaking the API key (which lives in the env var).

1. In the repo root, create a folder named .cursor.
2. Save the downloaded mcp.json inside it as .cursor/mcp.json.
3. Commit the folder.

mkdir -p .cursor
mv ~/Downloads/mcp.json .cursor/mcp.json
git add .cursor/mcp.json
git commit -m "Add chisel.to MCP config for Cursor"

Global (all workspaces)

Use this when you want chisel.to available regardless of which folder you opened Cursor in.

• macOS / Linux: ~/.cursor/mcp.json
• Windows: %USERPROFILE%\.cursor\mcp.json

If the global file already exists with other MCP servers, add the chisel-* entry under mcpServers rather than overwriting the whole file.

API key as an environment variable

Export your project's API key so Cursor inherits it when it spawns the MCP process:

export CHISEL_API_KEY="ck_live_…"

Open a fresh terminal, then launch Cursor from that terminal (or restart Cursor if it was open). Cursor inherits the parent shell's environment, so the MCP server picks the key up automatically.

If you'd rather not put a live key in your shell rc, two alternatives work:

• Direnv — put export CHISEL_API_KEY=… in a .envrc file at your repo root. Cursor inherits it when launched from a direnv-enabled shell.
• Test key — issue a ck_test_ key from the Connect page and use that on your machine. Live keys live on production only.

Verify it works

1. Open the workspace in Cursor (or restart Cursor for the global config).
2. Open the command palette and run MCP: Reload Servers. If you don't see it, restart Cursor entirely.
3. Open Chat or Composer. You should see a tool icon (often a hammer or plug) — clicking it lists the available MCP servers, including chisel-<your-slug>.
4. Ask the agent the verification prompt below.

List the resources on the chisel.to backend connected to this workspace.
Return them as a bullet list with the column names for each.

You should see your real tables come back. If you see "no MCP servers connected" or a list that doesn't match your project, jump to the troubleshooting section below.

Common workflows

1. Add a feature end-to-end

One of the highest-value flows. The agent runs the schema change against your project, then writes the matching client code.

Add a "favorites" feature to this app.

On the chisel.to backend:
  - Create a "favorites" table with user_id (FK to users) and post_id (FK to posts).
  - Add a unique composite index on (user_id, post_id).
  - Add a custom action "toggle" on the favorites table.

On the client (this repo):
  - Add toggleFavorite(postId) and isFavorited(postId) helpers in src/lib/favorites.ts.
  - Update PostCard to render a heart icon and call toggleFavorite on tap.

When you're done, run the type check and fix anything that doesn't compile.

2. Generate a typed client wrapper

If you want a thin facade over the auto-generated SDK so the rest of the app doesn't import it directly:

Wrap the chisel.to TypeScript SDK in src/lib/api.ts. Expose one function per screen's
data need (loadFeed, signIn, signOut, uploadAvatar). Throw friendly errors, not raw
HTTP errors. The wrapper should re-export types where the screens need them.

3. Debug a failing endpoint

When something returns 422 or 500, the agent can hit the endpoint, read the actual response, and fix the call.

The createPost call in src/screens/Compose.tsx fails with a 422. Call the chisel.to
endpoint with the same payload and tell me what the validation error is. Then fix
the screen so it doesn't trip that rule.

4. Backfill data after a schema change

I just added a "slug" column to posts. Read the existing posts via the chisel.to
API, generate a kebab-case slug from each title, and update the rows in batches of
20. Skip anything that already has a slug.

5. Refresh after the schema changed elsewhere

The schema changed on the dashboard. Pull the current list of resources from
chisel.to and update the local types in src/types/api.ts to match. Don't touch
files outside that folder.

Use .cursorrules to keep behavior consistent

Cursor reads a .cursorrules file at the repo root and injects it into every prompt. A short rules file dramatically improves how the agent uses the chisel.to MCP server.

This project uses chisel.to as its backend. The MCP server "chisel-myapp" is
connected — prefer calling its tools over guessing endpoint URLs or shapes.

Conventions:
- Never invent table or column names. If you need one that doesn't exist,
  create it via the MCP tools.
- Client code uses the @chisel-to/sdk package. Don't roll raw fetch calls.
- Auth: the SDK persists tokens; don't store them in localStorage directly.
- Validation errors come back as 422 with { message, errors } — surface
  errors.field.0 to the user, not the whole object.

When in doubt, ask the chisel.to tools for the source of truth before writing code.

Commit this file alongside .cursor/mcp.json and every teammate gets the same baseline behavior.

Composer agent tips

Composer (the multi-file agent) benefits the most from the MCP setup because it can read the schema, make the change and edit several files in one pass. A few specific patterns that pay off:

• Lead with the change, then the constraints. "Add a leaderboard. Don't touch authentication. Keep all changes inside src/leaderboard/." The agent respects scope better when you state it up-front.
• Pin the file you want it to look at. Drag src/types/api.ts into the Composer context window before asking it to align types — saves a round-trip where it would otherwise discover the file on its own.
• Ask for tests after the change. "Then add a Jest test that asserts the leaderboard query returns sorted results." The agent will call the live endpoint to seed the test data.

Refreshing context after a schema change

MCP servers are queried per-prompt — so when the schema changes (either through the dashboard or through the agent itself), the next prompt sees the new shape. There's nothing to manually refresh on the Cursor side.

Two exceptions worth knowing about:

• If you regenerate and re-download the TypeScript SDK from the Connect page, restart any dev server so the new types are picked up.
• If you change the mcp.json file itself (renamed the server, added a second project), run MCP: Reload Servers from the command palette.

Security & key hygiene

• Publishable vs server keys. The Connect page hands out a publishable key by default. That's the right key for Cursor and the device. Server-scoped keys (with write access to billing, projects, etc.) should never leave a server-side context.
• Test mode in dev. Issue a test key in the API keys page and use it locally. Live keys ship to production only.
• Repo safety. Commit .cursor/mcp.json; never commit the env file holding CHISEL_API_KEY.
• IP allowlist. If you've enabled an IP allowlist on the key, your laptop's egress IP needs to be in it — otherwise the MCP tools return 401 from the platform side, not from Cursor.

Troubleshooting

"No MCP servers connected"

The mcp.json file isn't being found. Confirm the file lives at .cursor/mcp.json inside the workspace you opened (not a parent folder), then run MCP: Reload Servers. If Cursor still doesn't see it, restart Cursor entirely.

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 Cursor inherited from (run env | grep CHISEL_API_KEY from Cursor's integrated terminal). If the variable isn't there, fix your shell config and relaunch Cursor.

Every tool call returns 401

The API key is being read but the platform rejects it. Three usual causes:

• You used a key from a different project (the URL in mcp.json belongs to one project; the key has to come from the same project's Connect page).
• The key was revoked from the dashboard.
• An IP allowlist is in effect and your current IP isn't on it.

The agent hits real endpoints in dev — is that safe?

Yes, when the key is a test key. The same data plane handles both; the test key just keeps the changes scoped to whatever you treat as test data. For destructive operations (delete tables, wipe records), prefer asking the agent to write the SQL and confirm it before running, rather than executing in one step.

"npm command not found" in the MCP bridge log

Cursor couldn't find Node when spawning the MCP server. Either fix the PATH inherited by Cursor (see the macOS callout in Requirements), or change the command in mcp.json from npx to an absolute path like /Users/you/.nvm/versions/node/v20.11.0/bin/npx.

Composer keeps "forgetting" to use the MCP tools

Add the .cursorrules snippet from earlier in this guide. The agent's default behavior is to write code, not call tools — the rules file rebalances that.

Next steps

• If you also write inside Windsurf or Claude Code, the same mcp.json works there too.
• Pair this with the TypeScript SDK guide on the runtime side — or follow the Unreal Engine 5 SDK (coming soon).
• Browse your project's auto-generated API reference for exact validation rules and field shapes.