MCP tools

whoamiread-only

Who am I. The signed-in user, the token's scopes and its workspace(s).

Scope

any token

Output

The signed-in user, credential kind, scopes and workspaces.

Input schema

No arguments.

{
  "name": "whoami",
  "arguments": {}
}

{
  "userId": "u_1",
  "email": "dev@example.com",
  "auth": "pat",
  "scopes": [
    "read",
    "apply",
    "deploy"
  ],
  "workspaces": [
    {
      "id": "6a1f…",
      "name": "Acme",
      "role": "owner"
    }
  ]
}

RelatedGET /api/dev/v1/me

Source: services/api/src/mcp/server.ts:127

get_guideread-only

Contract guide. The contract reference for authors (markdown). Without a section: the loop, rules, contract shape, access and workflows, plus an index. With a section id: that part (pages, blocks, coordinates, seeds, patch ops, icons). The whole guide is also the appbricx://docs/guide resource.

Scope

any token

Output

Markdown. Without section: the loop, rules, contract shape, access and workflows, plus an index of sections. With section: that part.

Input schema

{
  "name": "get_guide",
  "arguments": {
    "section": "components"
  }
}

# appbricx contract guide

Loop: get_contract → edit → check_contract …

RelatedGET /api/dev/v1/docs

Source: services/api/src/mcp/server.ts:134

list_projectsread-only

List projects. Projects this token can reach (newest first).

Scope

any token

Output

Projects the token can reach, newest first.

Input schema

No arguments.

{
  "name": "list_projects",
  "arguments": {}
}

{
  "projects": [
    {
      "id": "3b7e9a52-6c1d-4f0e-9a8b-2c4d6e8f0a1b",
      "name": "Tablefor",
      "slug": "tablefor",
      "workspace_id": "6a1f…",
      "updated_at": "…"
    }
  ]
}

RelatedGET /api/dev/v1/projects

Source: services/api/src/mcp/server.ts:141

create_projectwrites

Create project. Create an empty project in the token's workspace. Then apply_contract to build it. Needs the apply scope.

Scope

apply

Output

The new project's id, name and slug.

Errors

FORBIDDEN_SCOPE without apply.

Input schema

{
  "name": "create_project",
  "arguments": {
    "name": "Tablefor",
    "description": "Table bookings for a small restaurant"
  }
}

{
  "project": {
    "id": "3b7e9a52-6c1d-4f0e-9a8b-2c4d6e8f0a1b",
    "name": "Tablefor",
    "slug": "tablefor",
    "workspaceId": "6a1f…"
  }
}

RelatedPOST /api/dev/v1/projects

Source: services/api/src/mcp/server.ts:147

get_projectread-only

Project state. Whether the project has been built, the last build failure if any, and its preview path.

Scope

any token

Output

Whether the project is built, the last build failure, and the preview path.

Input schema

{
  "name": "get_project",
  "arguments": {
    "project_id": "3b7e9a52-6c1d-4f0e-9a8b-2c4d6e8f0a1b"
  }
}

{
  "project": {
    "id": "3b7e9a52-6c1d-4f0e-9a8b-2c4d6e8f0a1b",
    "name": "Tablefor"
  },
  "state": {
    "built": true,
    "lastError": null
  },
  "previewPath": "/preview/3b7e9a52-6c1d-4f0e-9a8b-2c4d6e8f0a1b/"
}

RelatedGET /api/dev/v1/projects/:id

Source: services/api/src/mcp/server.ts:153

get_contractread-only

Get contract. The project's current contract (null before the first apply). Seeds come back as "UNCHANGED" — rows live in the database; use query_data to read them.

Scope

any token

Output

The current contract (null before the first apply). Seeds come back as "UNCHANGED".

Input schema

{
  "name": "get_contract",
  "arguments": {
    "project_id": "3b7e9a52-6c1d-4f0e-9a8b-2c4d6e8f0a1b"
  }
}

{
  "contract": {
    "app": {
      "name": "Tablefor"
    },
    "entities": [
      {
        "name": "bookings"
      }
    ],
    "seeds": "UNCHANGED"
  },
  "built": true
}

RelatedGET /api/dev/v1/projects/:id/contract

Source: services/api/src/mcp/server.ts:160

check_contractread-only

Check contract. Normalize a contract and report errors (must be empty to apply), fixes (what the normalizer matched or filled — make them explicit) and warnings. No side effects.

Scope

any token

Output

The check report: errors (must be empty to apply), fixes, warnings.

Input schema

{
  "name": "check_contract",
  "arguments": {
    "project_id": "3b7e9a52-6c1d-4f0e-9a8b-2c4d6e8f0a1b",
    "contract": {
      "app": {
        "name": "Tablefor"
      },
      "personas": [
        {
          "id": "staff",
          "kind": "staff"
        }
      ],
      "entities": [
        {
          "name": "bookings",
          "fields": [
            {
              "name": "date",
              "type": "date"
            }
          ]
        }
      ]
    }
  }
}

{
  "report": {
    "ok": true,
    "errors": [],
    "fixes": [
      "entities.bookings.fields.status: enum_values filled from seeds"
    ],
    "warnings": []
  }
}

RelatedPOST /api/dev/v1/projects/:id/check

Source: services/api/src/mcp/server.ts:167

apply_contractwrites

Apply contract. Build the DEV environment from a full contract: database created or evolved additively (rows kept), pages compiled, workflows armed. Returns the check report, a build summary with demo sign-ins per role, and warnings. 422 = contract invalid (see report). Needs the apply scope.

Scope

apply

Output

The check report, a build summary with demo sign-ins per role, and warnings. A tool error with 422 means the contract is invalid (see report).

Errors

CONTRACT_INVALID (422), PROJECT_BUSY (409), HAND_EDITED_FILES (409, pass force), BUILD_FAILED (500).

Input schema

{
  "name": "apply_contract",
  "arguments": {
    "project_id": "3b7e9a52-6c1d-4f0e-9a8b-2c4d6e8f0a1b",
    "contract": {
      "app": {
        "name": "Tablefor"
      }
    }
  }
}

{
  "report": {
    "ok": true,
    "errors": []
  },
  "summary": "Built 4 tables, 9 pages, 2 workflows. Demo sign-ins: staff@demo.app",
  "warnings": []
}

RelatedPOST /api/dev/v1/projects/:id/apply

Source: services/api/src/mcp/server.ts:174

patch_contractwrites

Patch contract. Apply typed edit ops to the current contract, then rebuild (dry_run: report only). Ops: add_entity {name, fields[], personas?} · adopt_table {table, personas?, access?, title?, label_field?, page?} (a table made by hand with SQL becomes an entity; columns read from the dev database, rows kept) · add_field {entity, field} · update_field {entity, name, enum_values?, optional?} · remove_field {entity, name} · set_workflow {workflow} · remove_workflow {id} · add_page {page} · set_page {page, title?, icon?, personas?, layout?, form?} · remove_page {page} · set_component {component} (add/replace by name; code components carry source) · remove_component {name} · set_entity {entity, access?, owner_refs?, actor_ref?, label_field?} · set_demo_logins {logins[{persona,row}]} · set_app {theme?, direction?, nav_style?, density?, brand_color?, auth?} · edit_component {name, edits[{find, replace}]} (part of a code component's source; each find must occur exactly once).

Scope

apply

Output

As apply_contract, for the patched contract (dry_run: the report only).

Input schema

{
  "name": "patch_contract",
  "arguments": {
    "project_id": "3b7e9a52-6c1d-4f0e-9a8b-2c4d6e8f0a1b",
    "edits": [
      {
        "op": "add_field",
        "entity": "bookings",
        "field": {
          "name": "party_size",
          "type": "number"
        }
      }
    ],
    "dry_run": false
  }
}

{
  "report": {
    "ok": true,
    "errors": []
  },
  "summary": "Added bookings.party_size"
}

RelatedPOST /api/dev/v1/projects/:id/patch

Source: services/api/src/mcp/server.ts:184

check_componentread-only

Check a custom component. Run one custom code component through every gate — static import/capability allowlist, strict TypeScript against the real kit types, compile, and a sandboxed server render with the sample props and with empty props. Seconds, no project change. Use it before putting the component into the contract. See get_guide section "components" for the standard signature (props + app: AppHandle).

Scope

any token

Output

Which gates passed, or the failing stage and its errors.

Input schema

{
  "name": "check_component",
  "arguments": {
    "name": "OpenNow",
    "source": "import type { AppHandle } from \"@app/kit/primitives\";\nexport default function OpenNow({ app }: { app?: AppHandle }) {\n  return <p>Open until 22:00</p>;\n}",
    "sample": {}
  }
}

{
  "ok": true,
  "passed": [
    "static",
    "types",
    "compile",
    "render"
  ]
}

RelatedPOST /api/dev/v1/components/check

Source: services/api/src/mcp/server.ts:199

verifyread-only

Verify. Run appbricx verify on the DEV environment (takes a few minutes: if it answers status "running", call verify again to get the result): static (contract, reachability, typecheck) → data (demo sign-ins, role × table permission matrix with rolled-back writes, signed-out access, workflows armed) → browser. Each failing check has evidence and a fix. 'skipped' is never 'pass'.

Scope

any token

Output

The verify report: static, data and browser stages, each failing check with evidence and a fix. Answers { status: "running" } after about 45 seconds; call again to join the same run.

Input schema

{
  "name": "verify",
  "arguments": {
    "project_id": "3b7e9a52-6c1d-4f0e-9a8b-2c4d6e8f0a1b"
  }
}

{
  "report": {
    "status": "fail",
    "stages": [
      {
        "name": "data",
        "status": "fail",
        "checks": [
          {
            "id": "rls.customer.bookings.update",
            "status": "fail",
            "evidence": "customer updated another customer's booking",
            "fix": "set access.update to own"
          }
        ]
      }
    ]
  }
}

RelatedPOST /api/dev/v1/projects/:id/verify

Source: services/api/src/mcp/server.ts:210

screenshotread-only

Screenshot the app. See the app as a user does: opens the DEV preview in a real browser at phone size (390×844 unless you pass width/height), signed in as a demo role (default: the first persona; pass a persona id or a demo login email) or as="guest" to see the sign-in screen, goes to `route`, and returns the PNG plus page errors, horizontal overflow and the visible text. Use it after apply_contract to check every screen against your reference — layout, colours, fonts, nothing cut off — and fix what you see.

Scope

any token

Output

An image (PNG) plus JSON: route, persona, page errors, horizontal overflow and the visible text.

Input schema

{
  "name": "screenshot",
  "arguments": {
    "project_id": "3b7e9a52-6c1d-4f0e-9a8b-2c4d6e8f0a1b",
    "route": "/bookings",
    "as": "customer",
    "width": 390
  }
}

{
  "route": "/bookings",
  "as": "staff",
  "errors": [],
  "overflowX": 0,
  "text": "Bookings · Today · 3 tables free"
}

RelatedPOST /api/dev/v1/projects/:id/screenshot

Source: services/api/src/mcp/server.ts:217

deploywrites

Deploy. Publish the app to https://<subdomain>.<publish domain> (takes a few minutes: if it answers status "running", call deploy again to get the result). Runs verify first and refuses on red unless skip_verify. Pass `subdomain` to choose a meaningful host name (e.g. "tablefor"); omitted, the project keeps the one it has. Needs the deploy scope.

Scope

deploy

Output

The deployment id, live URL, status, duration and the verify report. Answers { status: "running" } after about 45 seconds; call again to join.

Errors

VERIFY_FAILED (422) unless skip_verify; SUBDOMAIN_TAKEN, INVALID_SUBDOMAIN; a deployment already in progress (409).

Input schema

{
  "name": "deploy",
  "arguments": {
    "project_id": "3b7e9a52-6c1d-4f0e-9a8b-2c4d6e8f0a1b",
    "subdomain": "tablefor"
  }
}

{
  "deploymentId": "d_9",
  "url": "https://tablefor.apps.appbricx.com",
  "status": "live",
  "durationMs": 142000
}

RelatedPOST /api/dev/v1/projects/:id/deploy

Source: services/api/src/mcp/server.ts:267

sign_in_providerswrites

Sign-in providers. Read or change the app's social sign-in. With no `provider`, lists Google and GitHub and whether each is on. {provider: "google", enabled: true} turns on Continue with Google through Appbricx's own Google client (no Google Cloud setup). Pass client: "own" with client_id and client_secret to use your own OAuth client (register https://<app host>/__appbricx/auth/oauth/<provider>/callback). The contract switch `auth.google` does the same on apply. Changing needs the apply scope.

Scope

read to list; apply to change

Output

Google and GitHub and whether each is on.

Input schema

{
  "name": "sign_in_providers",
  "arguments": {
    "project_id": "3b7e9a52-6c1d-4f0e-9a8b-2c4d6e8f0a1b",
    "provider": "google",
    "enabled": true
  }
}

{
  "providers": [
    {
      "provider": "google",
      "enabled": true,
      "client": "platform"
    },
    {
      "provider": "github",
      "enabled": false
    }
  ]
}

RelatedGET /api/dev/v1/projects/:id/sign-inPOST /api/dev/v1/projects/:id/sign-in

Source: services/api/src/mcp/server.ts:281

query_dataread-only

Query data. Read rows from a table in the DEV database (read-only, max 200). Filters are equality on column values.

Scope

any token

Output

Up to 200 rows of a dev table.

Input schema

{
  "name": "query_data",
  "arguments": {
    "project_id": "3b7e9a52-6c1d-4f0e-9a8b-2c4d6e8f0a1b",
    "entity": "bookings",
    "where": {
      "status": "confirmed"
    },
    "limit": 10
  }
}

{
  "table": "bookings",
  "rows": [
    {
      "id": "b_1",
      "date": "2026-10-12",
      "status": "confirmed"
    }
  ],
  "rowCount": 1
}

RelatedPOST /api/dev/v1/projects/:id/data/query

Source: services/api/src/mcp/server.ts:242

logsread-only

Workflow logs. Recent workflow runs (status, error, last log lines) and in-app notifications for the project.

Scope

any token

Output

Recent runs with their last log lines, and notifications.

Input schema

{
  "name": "logs",
  "arguments": {
    "project_id": "3b7e9a52-6c1d-4f0e-9a8b-2c4d6e8f0a1b",
    "workflow": "send-invoice",
    "limit": 10
  }
}

{
  "runs": [
    {
      "workflow_id": "send-invoice",
      "status": "failed",
      "error": "SMTP timeout",
      "log": []
    }
  ],
  "notifications": []
}

RelatedGET /api/dev/v1/projects/:id/logs

Source: services/api/src/mcp/server.ts:256

describe_schemaread-only

Describe schema. The real schema of the dev or prod database: tables with columns (type, nullable, default), primary and foreign keys, unique and check constraints, indexes, triggers and policies; views, functions and enums in the public schema. Each table's origin says whether the contract manages it (contract), Appbricx made it (platform), it is an internal _appbricx_* runtime table (internal), or it was made by hand (hand-made, for example with sql). Columns of contract tables are marked managedByContract.

Scope

read

Output

Tables (columns, keys, constraints, indexes, triggers, policies, origin), views, functions and enums.

Input schema

{
  "name": "describe_schema",
  "arguments": {
    "project_id": "3b7e9a52-6c1d-4f0e-9a8b-2c4d6e8f0a1b",
    "env": "prod"
  }
}

{
  "env": "dev",
  "tables": [
    {
      "name": "bookings",
      "origin": "contract",
      "columns": [
        {
          "name": "date",
          "type": "date",
          "managedByContract": true
        }
      ]
    }
  ]
}

RelatedGET /api/dev/v1/projects/:id/schema

Source: services/api/src/mcp/server.ts:337

tailread-only

Tail events and requests. Recent activity of the running app. kind "events": change events (row writes) and topic messages; "requests": the app's runtime requests (every error and about 10% of the rest, 7 days); "errors": only 4xx/5xx requests. since: 15m, 2h, 1d or an ISO time. Paths only, never bodies, query strings or tokens.

Scope

read

Output

events (change events and topic messages), requests, or errors, newest first. Paths only.

Input schema

{
  "name": "tail",
  "arguments": {
    "project_id": "3b7e9a52-6c1d-4f0e-9a8b-2c4d6e8f0a1b",
    "kind": "errors",
    "env": "prod",
    "since": "2h"
  }
}

{
  "kind": "errors",
  "env": "prod",
  "requests": [
    {
      "at": "…",
      "method": "POST",
      "path": "/__appbricx/api/v1/bookings",
      "status": 422,
      "error": "RULE_REFUSED"
    }
  ]
}

RelatedGET /api/dev/v1/projects/:id/tail

Source: services/api/src/mcp/server.ts:395

sqlwrites

Run SQL. Run SQL against the dev or prod database like the builder's SQL editor: several statements in one transaction, DDL and DML, as the tenant admin (past row-level security). Returns rows (max 1000, of the last statement that returned rows), rowCount, each statement with its command and row count, and durationMs. A script that only reads runs in a rolled-back transaction and needs the read scope; writes need apply on dev and deploy on prod. Before any write on prod a database snapshot is taken and its id returned as snapshotId (undo with snapshots {action: "restore"}). Use it to hand-tune the schema (indexes, views, functions, triggers, extra tables or columns): contract apply and publish keep hand-made objects. Check the result with describe_schema. Catalog names (pg_catalog, information_schema) are refused: use describe_schema.

Scope

read for read-only scripts; writes need apply on dev and deploy on prod

Output

rows (1000 max, of the last statement that returned rows), rowCount, each statement with its command and row count, durationMs, and snapshotId for prod writes.

Errors

STMT_FORBIDDEN for catalog names (use describe_schema); a failing statement rolls back the whole script; SNAPSHOT_FAILED (503) leaves prod untouched.

Input schema

{
  "name": "sql",
  "arguments": {
    "project_id": "3b7e9a52-6c1d-4f0e-9a8b-2c4d6e8f0a1b",
    "sql": "create index if not exists bookings_date on bookings(date)",
    "env": "prod"
  }
}

{
  "rows": [
    {
      "n": 128
    }
  ],
  "rowCount": 1,
  "statements": [
    {
      "sql": "select count(*)::int as n from bookings",
      "command": "SELECT",
      "rowCount": 1
    }
  ],
  "env": "dev",
  "readOnly": true,
  "durationMs": 9
}

RelatedPOST /api/dev/v1/projects/:id/sql

Source: services/api/src/mcp/server.ts:303

edit_rowswrites

Edit rows. Insert, update or delete rows through the app's own data API, so the access rules, before-write rules, lifecycle guards, row-level security and change events (workflows on entity events) behave as in the app. insert: rows (1 to 100). update: id or ids plus patch. delete: id or ids. as: "admin" (default) writes elevated, past row-level security, like the Backend tab; as: {role} acts as an app user holding that persona role, with that role's access. Returns one result per row. Needs apply on dev and deploy on prod; a prod write takes a database snapshot first (snapshotId).

Scope

apply on dev; deploy on prod

Output

One result per row, succeeded and failed counts, and snapshotId on prod.

Errors

NO_PERSONA (409) when nobody holds the role; TABLE_FORBIDDEN; per-row RULE_REFUSED and E_LIFECYCLE_DIRECT_WRITE.

Input schema

{
  "name": "edit_rows",
  "arguments": {
    "project_id": "3b7e9a52-6c1d-4f0e-9a8b-2c4d6e8f0a1b",
    "table": "bookings",
    "op": "insert",
    "rows": [
      {
        "date": "2026-10-13",
        "party_size": 4
      }
    ],
    "as": {
      "role": "customer"
    }
  }
}

{
  "table": "bookings",
  "env": "dev",
  "op": "insert",
  "as": "admin",
  "succeeded": 1,
  "failed": 0,
  "results": [
    {
      "ok": true,
      "id": "b_9",
      "row": {
        "id": "b_9",
        "date": "2026-10-13"
      }
    }
  ]
}

RelatedPOST /api/dev/v1/projects/:id/rows

Source: services/api/src/mcp/server.ts:316

snapshotswrites

Database snapshots. List, take or restore database snapshots (pg_dump) of dev or prod. Every publish and every agent write on prod takes one automatically. list needs read; create needs apply (default env prod); restore needs deploy, replaces the whole database with the snapshot, and first snapshots the current state (undoSnapshotId) so a restore can be undone.

Scope

list: read; create: apply; restore: deploy

Output

list: snapshots. create: the new snapshot. restore: restored id, env and undoSnapshotId.

Input schema

{
  "name": "snapshots",
  "arguments": {
    "project_id": "3b7e9a52-6c1d-4f0e-9a8b-2c4d6e8f0a1b",
    "action": "restore",
    "id": "prod-2026-10-12T09-00-00Z-a1b2"
  }
}

{
  "restored": "prod-2026-10-12T09-00-00Z-a1b2",
  "env": "prod",
  "undoSnapshotId": "prod-2026-10-12T09-31-12Z-e5f6"
}

RelatedGET /api/dev/v1/projects/:id/snapshotsPOST /api/dev/v1/projects/:id/snapshots/:snapshotId/restore

Source: services/api/src/mcp/server.ts:344

deployswrites

Deploy history. List the project's deployments (status, url, git sha, timing), or roll what's live back to an earlier successful deployment (its stored build, else a rebuild of its git sha; if it answers status "running", call again with the same deploymentId). Rollback switches files only: roll the database back with snapshots. list needs read; rollback needs deploy.

Scope

list: read; rollback: deploy

Output

list: deployments. rollback: the URL and how it was restored (stored build or rebuild).

Input schema

{
  "name": "deploys",
  "arguments": {
    "project_id": "3b7e9a52-6c1d-4f0e-9a8b-2c4d6e8f0a1b",
    "action": "list",
    "limit": 5
  }
}

{
  "deployments": [
    {
      "id": "d_9",
      "environment": "production",
      "status": "live",
      "url": "https://tablefor.apps.appbricx.com"
    }
  ]
}

RelatedGET /api/dev/v1/projects/:id/deploys

Source: services/api/src/mcp/server.ts:359

runwrites

Run workflows. action "workflow": run workflow `id` now with `input` against env (default dev). Returns runId, plus status and result when it finishes within 30s (else call get_run). Server functions (on: {call: true}) run inline as `as` (a persona) or signed out; other workflows are queued, acting as `as` when given. Needs apply on dev, deploy on prod. action "get_run": one run with its log (runId). action "dead_letters": jobs that used up their retries. action "replay": queue dead letters again (ids, default all; apply, or deploy when a job ran on prod).

Scope

workflow: apply on dev, deploy on prod; get_run and dead_letters: read; replay: apply (deploy for prod jobs)

Output

workflow: runId, status and result when it finishes within 30 seconds. get_run: the run with its log. dead_letters: jobs. replay: replayed and skipped ids.

Input schema

{
  "name": "run",
  "arguments": {
    "project_id": "3b7e9a52-6c1d-4f0e-9a8b-2c4d6e8f0a1b",
    "action": "workflow",
    "id": "send-invoice",
    "input": {
      "order": "b_1"
    },
    "env": "dev"
  }
}

{
  "runId": "4f0a…",
  "status": "succeeded",
  "finished": true,
  "result": {
    "sent": true
  },
  "error": null
}

RelatedPOST /api/dev/v1/projects/:id/workflows/:workflowId/run

Source: services/api/src/mcp/server.ts:375

secretswrites

Secrets. The app's secrets (project env vars) that workflows read with ctx.secrets.get(name). list: names, env and updated-at, never values (also which names the app declares and which are missing). set: name + value (env "dev", "prod" or "all", default all; ctx.secrets reads prod or all). delete: name (env limits it to one). set and delete need the apply scope and a workspace owner or admin token.

Scope

list: read; set and delete: apply plus a workspace owner or admin token

Output

list: names, env, scope and updated-at (never values), declared and missing names. set: created or updated. delete: the envs removed.

Input schema

{
  "name": "secrets",
  "arguments": {
    "project_id": "3b7e9a52-6c1d-4f0e-9a8b-2c4d6e8f0a1b",
    "action": "set",
    "name": "SHIPPO_KEY",
    "value": "shippo_live_…",
    "env": "all"
  }
}

{
  "secrets": [
    {
      "name": "STRIPE_KEY",
      "scope": "project",
      "env": "prod",
      "secret": true
    }
  ],
  "declaredByApp": [
    "STRIPE_KEY"
  ],
  "missing": []
}

RelatedGET /api/dev/v1/projects/:id/secretsPUT /api/dev/v1/projects/:id/secrets/:name

Source: services/api/src/mcp/server.ts:408