Claude Code

Overview

Claude Code is a terminal-first agent. It runs inside your repo, reads files directly, runs shell commands, and — once an MCP server is wired up — calls platform tools. With the chisel.to MCP server attached, Claude can list your tables, change your schema, run custom endpoints and write the client code that consumes them. All from the same prompt loop.

Three things this unlocks:

• Backend + frontend in one prompt. "Add a leaderboard" becomes a single message that creates the table, exposes the endpoints, and writes the React or Swift code that queries them.
• Verification without leaving the terminal. Claude can hit a live endpoint, read the response and decide whether the client code matches.
• Long sessions stay coherent. The MCP server is queried per-prompt, so the agent always sees the current schema — no stale-context drift.

Requirements

• Claude Code installed and signed in.
• Node.js 18+ on your PATH — the chisel.to MCP bridge is an npx-runnable package.
• A chisel.to project with at least one API key. Free-tier projects work fine.

node --version
# v20.x.x

claude --version
# claude code x.y.z

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. The file is generated for your specific project slug and 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"
      ]
    }
  }
}

The server name (chisel-myapp) is how you'll refer to the project in prompts. If you connect a second project later, give it a distinct name so you can tell them apart.

Install per-repo

Claude Code looks for .mcp.json at the workspace root. Save the file you downloaded there with the leading dot:

cd /path/to/your-app
mv ~/Downloads/mcp.json .mcp.json
git add .mcp.json
git commit -m "Add chisel.to MCP config for Claude Code"

Committing the file is safe — the API key lives in an environment variable, not inside the JSON. Teammates who clone the repo just need to export the same variable on their machine and they're set.

Multiple projects in one repo

If your monorepo has more than one chisel.to project, list them as separate servers under mcpServers:

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

You can then refer to a specific server by name in your prompts ("use the chisel-game tools to add a leaderboard").

API key as an environment variable

Export the key from the shell rc you launch Claude Code from:

export CHISEL_API_KEY="ck_live_…"

Or for direnv users, drop it into .envrc at the repo root:

export CHISEL_API_KEY="ck_test_…"
direnv allow

Confirm the variable is present in the shell you'll launch Claude from:

env | grep CHISEL_API_KEY

Verify it works

1. From the repo root, start Claude Code: claude.
2. Inside the session, list connected MCP servers with the slash command for MCP status (or just ask Claude). You should see chisel-myapp listed.
3. Try the verification prompt below.

List the resources on the chisel.to backend connected to this repo. For each
resource, show the columns and which CRUD operations are enabled.

If Claude returns the real list of tables in your project, you're connected. If the answer is "I don't see any MCP servers" or the list is empty, skip to Troubleshooting.

Common workflows

1. Ship a feature end-to-end

Add a "comments" feature to this app.

Backend (use the chisel.to MCP tools):
  - Create a "comments" table with post_id (FK to posts), user_id (FK to users),
    body (text_long, required), approved (boolean, default false).
  - Add an action "approve" that sets approved=true.

Client (this repo):
  - Add a CommentList and CommentForm component.
  - List endpoint should filter approved=true unless the user is the author.

Then run the type check and fix anything broken.

2. Migrate an existing schema in

If you have a legacy schema in db/schema.sql you want to import:

Read db/schema.sql. Import the CREATE TABLE statements into the chisel.to project
using the schema importer. Skip any tables that already exist. After the import,
verify each table is present and tell me which ones were skipped.

3. Investigate a failing endpoint

Claude can hit the endpoint, read the actual error, and fix the call. This is gold for the "it works on my machine" class of bug.

POST /v1/myapp/posts is returning 422 in production. Reproduce it with the
chisel.to MCP tools using a realistic payload, read the validation errors, and
patch the code in src/api/posts.ts so it matches the schema.

4. Generate types from the live schema

Read the current resource list from the chisel.to MCP server. Generate
TypeScript types into src/types/chisel.ts — one interface per resource, with
the column names and types as in the schema. Don't import any third-party
codegen; emit plain interfaces.

5. Seed and clean test data

Seed the chisel.to "posts" table with 25 realistic-looking entries (varied titles,
statuses, dates spread across the last 14 days). Stop and confirm before doing it.

After we're done testing, write a one-shot cleanup script in scripts/cleanup.ts
that deletes everything where the title starts with "[SEED]".

CLAUDE.md memory

Claude Code reads a CLAUDE.md file at the repo root as project memory — it's automatically included in every prompt. A short note about the chisel.to integration meaningfully improves how the agent uses the MCP tools.

# Project: my-app

## Backend

This project's backend is chisel.to, connected via the MCP server "chisel-myapp"
in `.mcp.json`. Prefer calling the MCP tools over guessing endpoint URLs.

### Conventions

- Never invent table or column names. If a column you need doesn't exist,
  create it via the MCP tools first.
- Auth tokens are handled by the @chisel-to/sdk client — don't store them in
  localStorage directly.
- Validation errors come back as 422 with `{ message, errors }`.
- For destructive changes (dropping tables, deleting many rows), explain the
  plan before running it.

### Common files

- `src/lib/chisel.ts` — the singleton client.
- `src/types/chisel.ts` — generated types; regenerate when the schema changes.
- `src/api/` — thin wrappers around resource methods.

Keep CLAUDE.md short and durable — it's read on every prompt, so noise costs tokens.

Subagents for chisel.to operations

Claude Code lets you define subagents — purpose-built sub-prompts the main agent can delegate to. A "schema-keeper" subagent that knows about your chisel.to project is useful for repeated schema work.

---
name: schema-keeper
description: Use proactively when the user mentions adding tables, columns, indexes
  or custom endpoints to the chisel.to backend. Owns all interactions with the
  "chisel-myapp" MCP server for schema changes.
tools: mcp__chisel-myapp__*
---

You are the schema authority for the chisel.to project connected to this repo.

When asked to change the schema:
1. List the relevant resources first to confirm the current state.
2. Plan the change (which tables, which columns, which indexes).
3. Show the plan and ask for confirmation if any operation is destructive.
4. Execute the operation through the MCP tools.
5. Report what changed.

Never invent tables or columns. If the user describes something that doesn't
exist, create it explicitly rather than pretending it does.

Then the main agent can hand off: "Use the schema-keeper to add a votes table with a unique index on (user_id, post_id)."

Slash commands

Define repeatable chisel.to commands as slash commands so you don't have to remember the prompt phrasing:

---
description: Regenerate TypeScript types from the live chisel.to schema.
---

Pull the current resource list from the chisel.to MCP server. Generate plain
TypeScript interfaces into src/types/chisel.ts. One interface per resource. Mark
columns as optional only when nullable. Include id, created_at and updated_at.

Run it inside Claude with /chisel-types whenever the schema moves.

Refreshing context

MCP servers are queried per-prompt, so when the schema changes (through the dashboard or through the agent), the next prompt sees the new shape automatically. Two operational reminders:

• If you regenerate and re-download the TypeScript SDK, restart any dev server so the new types load.
• If you edit .mcp.json while a Claude session is running, exit and relaunch Claude — MCP servers are started once per session.

Security & key hygiene

• Use a test-mode key (ck_test_) locally and a live key only in production. Both come from the API keys page in the dashboard.
• Commit .mcp.json freely — it contains no secrets. Never commit your .envrc or shell rc.
• If you've enabled an IP allowlist on the key, your dev machine's IP needs to be on it.
• Long, agent-driven sessions can rack up many calls. Watch your project's Analytics page to spot runaway loops early.

Troubleshooting

"No MCP servers connected"

Claude Code didn't find .mcp.json. Confirm you started Claude from the repo root (not a subdirectory) and that the file is exactly .mcp.json (with the leading dot).

The server starts but has zero tools

The MCP bridge ran but couldn't reach your project. Check that CHISEL_API_KEY is set in the shell Claude inherited from (env | grep CHISEL_API_KEY), and that the value matches a key listed on your project's API keys page.

Every tool call returns 401

Either the key is wrong, the key belongs to a different project than the URL in .mcp.json, the key was revoked, or an IP allowlist is excluding your current IP.

npx fails to install the package

Behind a corporate proxy or firewall? Pre-install the bridge once with npm i -g @chisel-to/mcp and change the command in .mcp.json from npx to the absolute path of the installed binary.

Schema changes appear to "succeed" but aren't visible in the dashboard

Refresh the schema page; the dashboard usually polls but isn't realtime. If a change really didn't land, the MCP tool would have surfaced the error — re-run the operation with verbose logging and Claude will tell you what came back.

Agent loops on a failing operation

Tell it to stop and explain the plan before retrying. "Stop. Don't retry. Tell me exactly which call failed and why." Claude responds well to a hard reset.

Next steps

• The same .mcp.json works in Cursor and Windsurf with minor location changes.
• Pair this with the TypeScript SDK guide on the runtime side — or follow the Unreal Engine 5 SDK (coming soon).
• Browse your project's API reference for the exact field types and validation rules.