# Fastbase for app builders

For people who build apps with an AI tool (Claude Code, Cursor, Replit, Lovable, Bolt), and for the AI tool itself.
Written 2026-10-31 and updated on 2 Nov 2026, with the notes on backups, restore and the evidence file.
Since 1 Nov 2026 the connector answers at `mcp.fastbase.sa`, on the Riyadh Sandbox
server (its end-to-end test passed there: 11 of 11 checks). Fast issues tokens for now. Sign up with Google or GitHub, with an access code while Fastbase opens in stages; email is used for invitations and notices. What is described here was
seen on a test server or on that server; what has not been tried says so.

## 1. Sample data only (read this first)
- Fastbase's Sandbox is for sample data. Whatever a tool returns, the AI tool's vendor reads in its own cloud, which is
  outside the Kingdom. Never put real people's personal data in a Sandbox project.
- Real users' data opens with Pro (join the waitlist: hsa@fast.sa); every project holds sample data until then.
- Make no residency promise to your own users for an app built through an AI tool: the AI vendor's cloud sees what the tools return.

## 2. What you get
- A Supabase-compatible backend in Riyadh for each project: Postgres, sign-in (Auth), a REST API, Realtime and file Storage.
- Your AI tool talks to Fastbase through the **connector**, an MCP server (MCP is the standard way an AI tool uses outside
  tools). Through it the AI makes the project, adds tables and security rules (RLS), runs SQL, and reads logs and keys. You
  never open a dashboard. One region (`me-riyadh-1`), one organization (`fastbase`), and USD 0.00 a month (sample data only).
- A project name has 3–30 characters: lowercase letters, digits and hyphens, starting with a letter (`test-1` is fine).

## 3. Connect
You need a Fastbase token (it starts with `fbp_`). It is shown once. Keep it like a password: never paste it into a chat, a
repository or a prompt. Fast issues tokens for now: write to hsa@fast.sa to get one.

**Claude Code**, the form its docs show:
```
claude mcp add --transport http fastbase https://mcp.fastbase.sa/mcp --header "Authorization: Bearer <your token>"
```
Claude Code keeps that header in its own settings file, `~/.claude.json`. Its docs name the file and do not say it is
encrypted, so treat the file as private. To keep the token out of every file, export it in your shell and use a
`.mcp.json` file in your project (Claude Code expands `${VAR}` in headers; not yet tried with Fastbase):
```
{"mcpServers": {"fastbase": {"type": "http", "url": "https://mcp.fastbase.sa/mcp",
  "headers": {"Authorization": "Bearer ${FASTBASE_TOKEN}"}}}}
```
- **Sign-in is a token in a header, nothing else.** There is no OAuth sign-in (the «sign in with your account» flow) yet,
  so a client has to be able to send a fixed `Authorization` header. Claude Code can (through `.mcp.json`, checked
  on 1 Nov 2026); the other AI tools are not checked yet, so do not assume it. claude.ai and ChatGPT need OAuth sign-in and
  are not available yet.
- **Options on the address:** `?project_ref=<ref>` limits the session to one project (the account tools disappear and
  `execute_sql` needs no project id); `?read_only=true` hides every write tool; `?features=database,debugging` picks
  groups from `account`, `database`, `debugging` and `development`. An option that does not exist is refused, never ignored.

## 4. What your AI can do
20 tools in four groups.
- **account:** `list_organizations`, `get_organization`, `list_projects`, `get_project`, `get_cost`, `confirm_cost`,
  `create_project`, `pause_project`, `restore_project`, `delete_project`.
- **database:** `list_tables`, `list_extensions`, `list_migrations`, `apply_migration`, `execute_sql`.
- **debugging:** `get_logs`, `get_advisors`. **development:** `get_project_url`, `get_publishable_keys`,
  `generate_typescript_types`.
- To make a project the AI asks the price (`get_cost`: USD 0.00 a month), confirms it (`confirm_cost`), then calls
  `create_project`. The answer is `COMING_UP`; the AI reads `get_project` until the status is `ACTIVE_HEALTHY`. On a test server
  that took 15 to 21 seconds. It takes minutes the first time on a new server, which pulls about 5 GB of images.
- Making a project is the promise that it holds sample data only (`fastbase_test_data_only`). A dashboard session sends
  `"fastbase_test_data_only": true` with `POST /v1/projects` (a 400 without it). A connection approved on Fastbase's consent page
  (OAuth, when it opens) makes projects only if the person ticked «I will use test data only» there (a 403 otherwise: connect again
  and tick it). A `fbp_` token from Fast needs nothing more.
- A migration is a saved, numbered change to the tables; the AI uses `apply_migration` for every change to the schema.
- Tools for Edge Functions, branching, storage and secrets are not offered.

## 5. Things to know
- **Delete needs the project's name, typed by you.** `delete_project` takes the project's exact name. The AI must ask the
  human for it and never fill it in itself. The API checks the name, and every delete is written to an audit log.
- **One live project per person (a setting; it may rise later).** A second `create_project` is refused: «Fastbase keeps 1 live sandbox project per person:
  delete one first». Paused and failed projects count; deleted ones do not. The number is the engine's setting
  (`FASTBASE_MAX_LIVE_PROJECTS`) and the message shows it as set. When the host is nearly
  full (80% of its memory) a new project is refused with «the sandbox host is full ... try again later».
- **Read-only mode stops writes, not reading.** A `read_only` call runs only SELECT, EXPLAIN and SHOW; anything else is
  refused: «read-only mode runs only SELECT, EXPLAIN and SHOW». But it reads **every table**: row-level security (RLS)
  does not apply to it. It is no way to hide rows, and it does not promise «no side effects» either (a project on the full
  profile has extensions, such as `http`, whose functions can try to send requests from a SELECT).
- **A long write can come back as an error and still finish.** The project's gateway (its front door) cuts a call at about 30
  seconds. The AI then reads: «the project's database did not answer, and the SQL may still have run: list the migrations or read the
  data again before sending it again». On a test server a 35-second migration was cut at 30.0 s and appeared in the list 5
  seconds later. So list the migrations (or read the data) before sending the write again.
- **A new table needs a moment before the REST API sees it.** After a migration the API tells PostgREST (the part that serves
  the REST API) to reload its list of tables. On a test server that took under a second, but an app that used a table made by SQL at once, on a fresh project, was
  once refused with «Could not find the table ... in the schema cache». Wait a few seconds and try again.
- **Realtime: wait for «Subscribed to PostgreSQL».** Do not rely on change events when only the join reply says
  `SUBSCRIBED`. Wait for Realtime's «Subscribed to PostgreSQL» system message: a row written between the two can be missed,
  most of all on the first join after Realtime starts.
- **The advisors and the types work.** `get_advisors` runs Supabase's own database linter in your project (type `security` or
  `performance`; there is no `health` type), so ask for the security advisors after each change: a table made without row level
  security comes back as `rls_disabled_in_public`. The findings name your tables, because the linter reads your schema.
  `generate_typescript_types` returns the TypeScript types of your `public` schema.
- **«Unauthorized ... --access-token flag» means your token.** That sentence is Supabase's wording for its own command line,
  kept as it is. In Fastbase it means the token in your `Authorization` header is wrong or revoked. Listing the tools works
  with any text there; the first tool call that reaches the API shows the error.
- **Backups: on the Riyadh server since 3 Nov 2026.** Every night (23:30 UTC) each live project is backed
  up as one archive: its databases, the Vault's secrets, its stored files, its Edge Functions and its settings, keys included, because a
  restore needs them. A backup is kept 14 days on the server (a project's newest one is kept whatever its age), and the server's copies
  go with the project when it is deleted. A second copy of each backup goes to a private storage bucket in Riyadh and is kept there 90
  days, a deleted project's too. A paused project is skipped. Each night the newest backup of every project is also restored into a
  throwaway copy and compared with what the backup recorded, to show that it works. It is sample data
  all the same: the Terms offer the Sandbox as is, with no promise of uptime and none that data will not be lost.
- **Restore, restart and rename are API calls, not AI tools.** `GET /v1/projects/{ref}/database/backups` lists the backups and
  `POST /v1/projects/{ref}/database/backups/restore` puts one back over the project's data (everything written since is lost; the restore first backs up the project as it stands, so restoring that
  newest backup undoes it, and `last_restore` in the list says how the last restore ended). The call
  needs the project's exact name in `confirm`, typed by the person: the AI must ask for it, as for a delete. The connector's
  `restore_project` brings back a *paused* project and does not restore a backup. `POST …/restart` and `PATCH …` (a new name; the ref and
  the address stay) are API calls too. A backup taken before the project moved to a newer release cannot be restored; the next
  nightly one can. Fast moves a project to a newer release itself, with a backup first and a way back: the project is down for about
  half a minute (33 to 36 seconds on a test server), and its status reads `UPGRADING` meanwhile.
- **The evidence file.** Fast can write one file for a project, on request: a readable page in English and Arabic and a JSON copy.
  It says where the project runs, each container with the image it runs, which outside places the project's settings let its data reach
  (a checklist of 28 rows, such as the email relay, an SMS provider, social sign-in or Studio's AI assistant: each `on`, `off` or
  «cannot be known from the settings»), the outbound allow-list, how the backups are kept, the last restore tests and when the keys were
  made. It is Fastbase's own record, it says what it cannot see, and it is not legal advice. There is no API path or AI tool for it yet.
- **The AI is told three of these, but a client may hide them.** The connector puts three notes in the instructions it sends every client:
  sample data only; read-only reads everything; the human types the name for delete.
  Each AI tool decides whether its model sees those instructions, so say the important ones in your own first prompt too.

## 6. Your app
Your app talks to the project's address, `https://<ref>.fastbase.sa`, with its publishable key. Ask the AI for them
(`get_project_url`, `get_publishable_keys`). The secret key goes only into server-side secrets, never into your app or a
prompt. Project addresses work: since 1 Nov 2026 a project on the Riyadh Sandbox server answers on `https://<ref>.fastbase.sa`
(an app test passed through it: sign-up, RLS, a private file and a realtime event). The address serves the five APIs
(`/auth/v1/`, `/rest/v1/`, `/realtime/v1/`, `/storage/v1/`, `/functions/v1/`) and `/graphql/v1`. There is no public database
connection yet: your app goes through those APIs, and table changes go through the AI (`apply_migration`).

## 7. Tried, and not tried yet (1 Nov 2026)
- **Tried on a test server**, with a test client (the official MCP client library, version 1.32.2), in one run of 11 checks: the
  20 tools; price, confirmation and create; a table with RLS through a migration, read back; logs with the project's
  secrets redacted; a read-only session and a one-project session; the 30-second cut; delete with a wrong name and then the
  right one.
- **Tried on a test server again (2 Nov 2026)**, the same test with two more checks, 13 in all, all ok: the advisors (a table made
  with row level security off came back as `rls_disabled_in_public`, and the table with it on did not) and the TypeScript types
  (they hold the project's tables).
- **Tried on the Riyadh Sandbox server (1 Nov 2026), with Claude Code as the client:** a project created at USD 0.00 (ready
  about 36 s after the request); a table with RLS through two migrations, checked as two users; the project's address and its
  publishable key; advisors and types, which then answered «not in Fastbase yet» (they are served since 2 Nov 2026, §5); pause (3 s) and restore (29 s) with the data
  intact; delete, after the AI asked for the project's name to be typed. Then an app test through `https://<ref>.fastbase.sa`
  passed (§6).
- **Tried on the Riyadh Sandbox server (3 Nov 2026):** the nightly backup and its restore test (each backup restored into a throwaway
  copy and matched, in about 41 s); its second copy sent to the private bucket in Riyadh, the same bytes as on the server; a night whose
  copy could not be sent failing and raising an alert, and the copy going out on the next run; the evidence file.
- **Tried on a test server, not on the Riyadh server (1 and 2 Nov 2026):** the nightly backup and its restore test while the project
  was being written to, the Vault's secrets decrypting; a move from release v0.8.2 to v0.8.3 with a way back, and a forced failure that
  returned the project to v0.8.2; and, through the API, restart, rename, the backups list and a restore from a backup (the rows, a Vault
  secret, a stored file with its headers and an Edge Function came back). **Not tried yet on the Riyadh server:** the move to a newer
  release, and those four API calls.
- **What an AI should take from it:** keep checking a new project's status until it says `ACTIVE_HEALTHY` (that session's
  AI stopped after two checks, 7 s into a create that took 36 s).
- **Not tried yet:** Cursor, Replit, Lovable and Bolt as the client (Replit, Lovable and Bolt come in a later phase);
  `list_tables` end to end through the connector on a real project.