Connect any MCP client
MCP (Model Context Protocol) is the standard way coding agents call outside tools. Point your agent at the Appbricx MCP server and it can create projects, build and test your app as each of your users, look at the screens, read data and logs, deploy, and then operate the running app (SQL, rows, schema, snapshots, rollbacks, workflow runs, logs and secrets), all from the chat you already work in.
When you would use it
- You work in Claude Code, Cursor or another MCP client and want the agent to build on Appbricx directly. The coding agents quickstart has copy-paste setup.
- You want the agent to stay focused on one app: pin a project (below) and the agent sees that project's real table, workflow and role names.
The MCP tools do exactly what the developer HTTP API and the CLI do, so you get the same answers whichever way you connect. The server speaks Streamable HTTP.
Endpoint
https://appbricx.com/api/mcpSign in with the browser (default)
Add the URL to your client with no token. The first time it connects, it opens a browser window: sign in to Appbricx, check the permissions and the workspace, and click Authorize. The client keeps its tokens and refreshes them by itself.
# Claude Code
claude mcp add --transport http appbricx https://appbricx.com/api/mcp
# then run /mcp, pick appbricx, choose Authenticate
# Cursor: .cursor/mcp.json
{ "mcpServers": { "appbricx": { "url": "https://appbricx.com/api/mcp" } } }See and revoke authorized clients in Workspace settings, Coding agents. Revoking one stops it on its next request.
How a client discovers sign-in
This follows the MCP authorization spec (OAuth 2.1), so any compliant client works without Appbricx-specific setup:
- A request without a token gets
401withWWW-Authenticate: Bearer resource_metadata="https://appbricx.com/.well-known/oauth-protected-resource/api/mcp". - That document (RFC 9728) names the authorization server
https://appbricx.com, whose metadata is athttps://appbricx.com/.well-known/oauth-authorization-server(RFC 8414). - The client registers itself at
https://appbricx.com/api/oauth/register(RFC 7591), openshttps://appbricx.com/oauth/authorizewith a PKCE challenge (S256 only), and exchanges the code athttps://appbricx.com/api/oauth/token.
- Scopes:
read,apply,deploy(all three by default; a workspace viewer getsreadonly). - Access tokens last one hour. Refresh tokens last 90 days and rotate on every use; reusing an old one revokes the authorization.
- Redirect URIs must match the registered ones exactly. Plain
httpis accepted only for loopback (127.0.0.1,[::1],localhost). - Revocation (RFC 7009):
https://appbricx.com/api/oauth/revoke.
Use a token instead (CI)
Where no browser can open, send a personal access token from Workspace settings, Coding agents. See Access tokens.
POST https://appbricx.com/api/mcp
Authorization: Bearer apx_pat_...- A missing, invalid, expired or revoked token gets
401withcode: "UNAUTHENTICATED". - Either way, access reaches only projects in the authorized workspace. Anything else answers "Project not found".
Pinning a project
Add ?project=<project-id> to the URL (or send an x-appbricx-project header). Then:
project_idbecomes optional on every project tool and defaults to the pinned project.- The project's current table, workflow and role names appear as enums in the tool schemas (for example the
entityofquery_data), so the agent picks from what exists. They are re-read on every request, so they follow each apply. - A pin to a project the connection can't reach is ignored.
https://appbricx.com/api/mcp?project=3f2c9a10-...Tools
Read tools work with any valid token. Tools that change something need the scope shown.
| Tool | What it does | Scope |
|---|---|---|
whoami | The signed-in user, the token's scopes and workspace | read |
get_guide | The contract guide (markdown). No argument: overview and index. section: one part | read |
list_projects | Projects this token can reach, newest first | read |
create_project | Create an empty project (name, optional description) in the token's workspace | apply |
get_project | Whether the project is built, the last build failure, and its preview path | read |
get_contract | The current contract (null before the first apply). Seeds come back as "UNCHANGED" | read |
check_contract | Normalize a contract and report errors, fixes and warnings. No side effects | read |
apply_contract | Build the dev environment from a full contract. Optional force overwrites hand-edited compiled files (backed up first) | apply |
patch_contract | Apply typed edit ops (1 to 50) to the current contract and rebuild. dry_run reports only | apply |
check_component | Run one custom component through every gate (static, types, compile, server render). No project change | read |
verify | Static → data → browser checks on the dev environment, each failure with evidence and a fix | read |
screenshot | The dev preview in a real browser, signed in as a role or guest; returns a PNG plus page errors, overflow and visible text | read |
query_data | Read rows from a dev table (read-only, equality filters, max 200) | read |
sign_in_providers | List or switch the app's social sign-in. Google can run through Appbricx's own client with no setup, or your own | apply |
logs | Recent workflow runs (status, error, last log lines) and in-app notifications | read |
deploy | Publish to https://<subdomain>.apps.appbricx.com. Pass subdomain to choose a meaningful name. Runs verify first and refuses on red unless skip_verify | deploy |
describe_schema | The real schema of dev or prod: tables, columns, keys, indexes, constraints, triggers, policies, views, functions. Marks which tables the contract manages | read |
sql | Run SQL like the builder's SQL editor: several statements, DDL and DML, past row-level security. Rows capped at 1000 | read (reads), apply (dev writes), deploy (prod writes) |
edit_rows | Insert, update or delete rows through the app's own rules, RLS and change events, as admin or as a persona role | apply (dev), deploy (prod) |
snapshots | List, take or restore database snapshots of dev or prod | read (list), apply (create), deploy (restore) |
deploys | Deploy history, or roll what's live back to an earlier deployment | read (list), deploy (rollback) |
run | Run a workflow now (result if it finishes within 30s), read a run, list and replay dead letters | read (get_run, dead_letters), apply (dev run, replay), deploy (prod) |
tail | Recent change events and topic messages, or the app's request log (all requests or errors only) | read |
secrets | List (names only, never values), set or delete the secrets workflows read with ctx.secrets | read (list), apply plus workspace owner or admin (set, delete) |
Writing tools also need a non-viewer role in the workspace. The server also exposes the whole guide as the resource appbricx://docs/guide.
Tool parameters
| Tool | Parameters |
|---|---|
get_guide | section? |
create_project | name, description? |
get_project, get_contract, verify | project_id |
check_contract | project_id, contract |
apply_contract | project_id, contract, force? |
patch_contract | project_id, edits, dry_run?, force? |
check_component | name (PascalCase), source (the whole TSX file), sample? |
screenshot | project_id, route?, as? (persona id, demo login email or "guest"), width? (320 to 1600), height? (480 to 1200), full_page? |
query_data | project_id, entity, where?, order_by? (default created_at), desc? (default true), limit? (1 to 200) |
logs | project_id, workflow?, limit? (1 to 200) |
deploy | project_id, environment? (production | preview), allow_destructive?, skip_verify? |
describe_schema | project_id, env? (dev | prod, default dev) |
sql | project_id, sql, env? |
edit_rows | project_id, table, env?, op (insert | update | delete), rows? (1 to 100), id? or ids?, patch?, as? ("admin" or { role, user_id? }) |
snapshots | project_id, action (list | create | restore), env?, id? |
deploys | project_id, action (list | rollback), deploymentId?, environment?, limit? |
run | project_id, action (workflow | get_run | dead_letters | replay), id?, input?, env?, as? ({ role, user_id? }), runId?, ids?, limit? |
tail | project_id, kind (events | requests | errors), env?, since? (15m, 2h, 1d or an ISO time), limit? (1 to 500) |
secrets | project_id, action (list | set | delete), name?, value?, env? (dev | prod | all, default all) |
Operating the running app
The last eight tools work on the app after it is built, in env: "dev" (the preview, the default) or env: "prod" (the published app).
- Every prod write (
sql,edit_rows) takes a database snapshot first and returns itssnapshotId. If the snapshot fails, nothing is written. Undo withsnapshotsrestore. - Every write is recorded in the project's admin audit trail with the token, the tool, the environment and a summary.
- SQL that only reads runs in a rolled-back transaction and needs only the read scope.
- Hand-tuning: indexes, views, functions, triggers and extra tables or columns you create with
sqlare kept by contract apply and publish.describe_schemashows them asorigin: "hand-made"(tables) ormanagedByContract: false(columns). - The request log behind
tailkeeps every error and about 10% of other requests for 7 days. It stores paths only: never query strings, request bodies or tokens.
Notes
Stateless
Each request gets a fresh server and transport. There is no MCP session to keep alive, and any API replica can answer any call. The server returns plain JSON responses (no long-lived stream).
get_guide sections
Without arguments it returns the loop and rules, the contract shape, ACCESS and WORKFLOWS, and an index. Pass one of these section ids for the rest:
loop, shape, access, coordinates, seeds, workflows, functions, payments, patch, operate, pages, blocks, components, primitives, icons.
Screenshots are images
screenshot returns MCP image content (a PNG) followed by JSON with url, signedInAs, viewport, errors, overflowX and text. The default viewport is 390×844 (a phone). Before the first apply it answers NOT_BUILT.
Errors
A tool result with an HTTP status of 400 or above is flagged isError and carries the same JSON body the HTTP API sends, for example CONTRACT_INVALID with a report, PROJECT_BUSY, HAND_EDITED_FILES, VERIFY_FAILED or FORBIDDEN_SCOPE. See Developer HTTP API for the full list.
Next
- Coding agents quickstart: connect Claude Code or Cursor
- App contract
- Access tokens