@rebasepro/mcp

@rebasepro/mcp

Model Context Protocol (MCP) server that exposes Rebase schema, database, document CRUD, user management, and dev server tools to AI assistants.

Installation

pnpm add @rebasepro/mcp

ESM-only: "type": "module" with no CommonJS build, so it is loaded with import. It needs Node >=22.22.0 (its engines floor), where require() of it resolves too: Node has supported require(esm) since 22.12.

Or run directly:

npx -y @rebasepro/mcp

What This Package Does

@rebasepro/mcp implements the Model Context Protocol over stdio, allowing AI assistants (Gemini, Claude, Cursor, etc.) to interact with a Rebase project. It provides tools and exposes collection definitions and generated schemas as MCP resources. It has native support for managing multiple local and remote projects.

Multi-Project Support

The MCP server supports managing multiple Rebase projects simultaneously. This is ideal when working in an IDE with multiple open workspaces or when interacting with both local development servers and remote staging/production environments.

• Registry: Project configurations are stored in ~/.rebase/projects.json.
• Auto-Discovery: If rebase dev is running locally, the MCP server automatically discovers the active development port and service key from .rebase/state.json inside the project directory, giving you zero-config local development.

Which project a run resolves to

One precedence, in this order:

• The environment block — REBASE_PROJECT_DIR, REBASE_BASE_URL, REBASE_API_TOKEN / REBASE_TOKEN. If any of them is set, the default project is rebuilt from them on every start. The rebuild is whole-entry: a token registered against the old projectDir is dropped rather than carried into a directory it was never issued for.
• The server's working directory, when it holds a rebase.json. ~/.rebase/projects.json is machine-wide, and a project you are standing in outranks a home-directory cache.
• The persisted default, when neither of the first two says anything.

A default derived from 1 or 2 is never written back to the registry: it is recomputed at every start, and persisting it would put one project's directory, backend URL and dev service key in the file every other project on the machine reads.

Auto-discovery fills gaps in all three cases and never overrules a value one of them supplied — not the token and not the baseUrl. Discovery reads the dev server's service key, which is an unscoped admin secret, so a narrow rk_live_* key you registered is what gets used even while rebase dev is running; likewise a project registered against https://staging.example.com stays there rather than being silently redirected to the local dev port. A baseUrl disagreement between the two is reported on stderr. Filling a gap is not: with no token registered, the SDK tools run on the discovered service key — full admin — and nothing says so.

rebase init writes "env": { "REBASE_PROJECT_DIR": "." } into the scaffolded .mcp.json — relative to the client's working directory, which for a project-level config file is the project.

Configuration

The server reads configuration from environment variables and .env files:

Variable	Default	Description
REBASE_PROJECT_DIR	process.cwd()	Project root directory (the rebase.json directory)
REBASE_BASE_URL	http://localhost:3001	Rebase backend URL, when discovery finds no dev server
REBASE_API_TOKEN / REBASE_TOKEN	(empty)	Auth token for API calls
REBASE_MCP_ALLOW_REMOTE_WRITES	false	Allow destructive tools to run against non-local targets (see below)

The server attempts to load .env from $REBASE_PROJECT_DIR/.env or $REBASE_PROJECT_DIR/app/.env.

Destructive-Tool Safety Gate

rebase_project_add accepts any baseUrl, and the CLI tools connect with whatever DATABASE_URL the project's .env declares. That means the same tool list that edits a scratch database on your laptop can drop production rows — with nothing in between but the assistant's judgement about which project is currently active.

Every tool that changes the target environment is refused unless that target is on the loopback interface. The gate is a list of what is not gated, so a newly added tool is protected by default:

• Not gated — reads: rebase_schema_plan, rebase_doctor, rebase_db_branch_list, rebase_db_branch_info, list_documents, get_document, list_users, list_roles, storage_list_objects, storage_get_download_url, cron_list_jobs, cron_get_job, cron_get_job_logs, rebase_dev_logs.
• Not gated — local only: rebase_schema_introspect, rebase_db_branch_switch, rebase_schema_generate, rebase_db_generate, rebase_generate_sdk, the dev-server tools, and the project-registry tools. These write local files or local state and have no remote target to check.
• Gated against DATABASE_URL: every other CLI tool — rebase_db_push, rebase_db_migrate, rebase_db_branch_create, rebase_db_branch_delete.
• Gated against the project baseUrl: every other SDK tool — create_document, update_document, delete_document, create_user, update_user, delete_user, rebase_auth_reset_password, storage_delete_object, cron_trigger_job, cron_toggle_job, invoke_function.

The two targets are not interchangeable: CLI tools never see baseUrl, so a localhost backend sitting next to a production DATABASE_URL is checked against the database, not the backend. create_user and update_user set roles, so they can mint an admin; invoke_function calls any function with any HTTP method; cron_toggle_job disables a scheduled backup silently. None of those is recoverable in the sense "additive" suggests, which is why the list is now the other way round.

The DATABASE_URL the gate checks is resolved the way the spawned CLI resolves it — ambient environment first, then <root>/.env, <root>/backend/.env, DOTENV_CONFIG_PATH and the parent directory, including the ADMIN_CONNECTION_STRING fallback the branch commands accept. If no connection string can be resolved at all, the DB tools are refused: an unverifiable target is not a safe one, and the child does its own resolution from files this process may not see.

Only loopback (localhost and *.localhost, 127.0.0.0/8, ::1, 0.0.0.0) counts as local — private ranges like 10.x and 192.168.x do not, since those are as likely to be a shared staging cluster as a laptop.

Set REBASE_MCP_ALLOW_REMOTE_WRITES=true to opt out.

The branch tools (rebase_db_branch_*) also require an admin, checked through GET /auth/me — which answers a signed-in user's access token only, so with a service key (including the one discovery supplies) or an rk_live_* API key every branch tool fails with "Admin authorization failed".

Untrusted Data Marking

Rows, user records, storage listings, cron jobs, function responses and CLI output are returned inside an explicit <<<UNTRUSTED_DATA …>>> envelope. Anything stored in your database was written by somebody, and it arrives on the same channel as the tool contract the assistant is following; the envelope tells the model to treat it as inert content rather than instructions. It is a marker, not a sandbox — an assistant with these tools is only as safe as the content you let it read.

Tools

42 tools, in 9 groups. Tools marked ⚠ are refused against a non-local target unless REBASE_MCP_ALLOW_REMOTE_WRITES=true — see the gate above.

Schema & database (12)

Spawn the Rebase CLI in the active project directory.

Tool	Required	Description
rebase_schema_generate	—	Generate Drizzle schema from Rebase TypeScript collection definitions
rebase_db_push ⚠	—	Apply the current Drizzle schema directly to the database (development shortcut, skips migration files)
rebase_schema_introspect	—	Introspect the live database and generate Rebase collection definitions from existing tables
rebase_db_generate	—	Generate SQL migration files from schema changes (compares current Drizzle schema against the last entity)
rebase_db_migrate ⚠	—	Run all pending SQL migrations against the database
rebase_generate_sdk	—	Generate a fully-typed JavaScript/TypeScript SDK from collection definitions
rebase_doctor	—	Detect schema drift between collection definitions, generated Drizzle schema, and the live PostgreSQL database
rebase_db_branch_create ⚠	name	Create a new database branch (Admins only)
rebase_db_branch_list	—	List all database branches (Admins only)
rebase_db_branch_delete ⚠	name	Delete an existing database branch (Admins only)
rebase_db_branch_info	name	Show information and status for a database branch (Admins only)
rebase_db_branch_switch	—	Point this checkout at a database branch, or back at the main database (Admins only)

Schema planning (1)

Ask the backend what a change would do. No CLI, no files written.

Tool	Required	Description
rebase_schema_plan	collectionId, collection	Show the SQL a collection change would run, without running any of it

Documents (5)

CRUD over a collection through @rebasepro/client.

Tool	Required	Description
list_documents	collection	List documents from a Rebase collection with optional filtering, sorting, and pagination
get_document	collection, id	Get a single document by ID from a Rebase collection
create_document ⚠	collection, data	Create a new document in a Rebase collection
update_document ⚠	collection, id, data	Update an existing document in a Rebase collection
delete_document ⚠	collection, id	Delete a document from a Rebase collection

Users & roles (6)

Tool	Required	Description
list_users	—	List all users registered in the Rebase backend, including their roles
create_user ⚠	email	Create a new user in the Rebase backend
update_user ⚠	uid	Update an existing user (email, display name, roles)
delete_user ⚠	uid	Delete a user from the Rebase backend
list_roles	—	List all roles defined in the Rebase backend
rebase_auth_reset_password ⚠	email	Reset a user's password via the admin API

Dev server (3)

Tool	Required	Description
rebase_dev_start	—	Start the Rebase development server (frontend + backend)
rebase_dev_logs	—	Read recent output from the running Rebase dev server
rebase_dev_stop	—	Stop the running Rebase development server

Storage (3)

Tool	Required	Description
storage_list_objects	—	List files/objects stored in Rebase storage
storage_delete_object ⚠	key	Delete an object/file from Rebase storage
storage_get_download_url	key	Mint a temporary signed download URL for a file in Rebase storage

Cron (5)

Tool	Required	Description
cron_list_jobs	—	List all scheduled cron jobs and their configuration status
cron_get_job	jobId	Get status and details of a specific scheduled cron job
cron_trigger_job ⚠	jobId	Manually trigger a cron job run immediately
cron_get_job_logs	jobId	Read execution logs for a specific cron job
cron_toggle_job ⚠	jobId, enabled	Enable or disable a scheduled cron job

Functions (1)

Tool	Required	Description
invoke_function ⚠	name	Invoke a custom backend Hono function (located in api/functions/:name)

Project registry (6)

Tool	Required	Description
rebase_project_list	—	List all registered Rebase projects and show which one is active
rebase_project_switch	name	Switch the active Rebase project by name
rebase_project_add	name	Register a new Rebase project
rebase_project_remove	name	Remove a registered project from the project registry
rebase_project_current	—	Show details about the currently active Rebase project, including resolved URL and auth status
rebase_project_status	—	Health-check the active project's backend by calling GET /health

Resources

The server exposes MCP resources for AI context:

URI	Description
rebase://collections/{name}	TypeScript source of a collection definition
rebase://schema	Generated Drizzle schema (schema.generated.ts)

Collection files are discovered from app/config/collections/, config/collections/, or collections/ under the active project directory.

Quick Start

Add to your AI assistant's MCP config (e.g. .gemini/settings.json):

{
  "mcpServers": {
    "rebase": {
      "command": "npx",
      "args": ["-y", "@rebasepro/mcp"],
      "env": {
        "REBASE_PROJECT_DIR": "/path/to/your/project"
      }
    }
  }
}

MCP Registry

A stable release publishes this server to the MCP Registry as io.github.rebasepro/rebase — the listing MCP clients read when they offer an install. Two files carry that identity, and they must agree:

package.json → mcpName	the ownership proof, read out of the published npm tarball
server.json	the manifest: the same name, the version, and the npm package to install

Neither is edited by hand on a release. publishable-packages.mjs --set-version writes the version into server.json alongside every package.json, and pnpm check:publishable-set refuses a tree where the two disagree — the registry validates a publish by downloading the tarball the manifest names, so a manifest left behind fails the release at its last step, once npm can no longer be rewritten.

The stable publish workflow pushes the registry entry itself, after npm, the tag and the fleet image, on the OIDC token it already holds for npm provenance. A hand-run release.sh cannot — the login is a device-code flow — so it prints the command to finish the job:

mcp-publisher login github && mcp-publisher publish

Install mcp-publisher with brew install mcp-publisher, and check a manifest without publishing anything using mcp-publisher validate.

Related Packages

• @rebasepro/client — Used internally for data and admin API calls