Rebase

@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 -D @rebasepro/mcp

A project made by rebase init already has it, pinned to the CLI's version: the server drives the project's own CLI and calls its own backend, so it should be the same release as both.

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.

Run the project's copy:

pnpm exec rebase-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:

1. The environment block — REBASE_PROJECT_DIR, REBASE_BASE_URL, REBASE_API_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.
2. 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.
3. 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:

The server attempts to load .env from $REBASE_PROJECT_DIR/.env or $REBASE_PROJECT_DIR/app/.env. Those values configure the server itself. They are not passed on to the CLI or the dev server it spawns: those read the active project's own .env, and a variable handed down would outrank it, and the branch the checkout is switched to, as if you had exported it in your shell.

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, rebase_db_branch_diff, 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, and the Rebase Cloud reads rebase_cloud_status, rebase_cloud_logs, rebase_cloud_env_list, rebase_cloud_deployments_list.
• Not gated — Rebase Cloud writes: rebase_cloud_provision, rebase_cloud_deploy, rebase_cloud_env_set, rebase_cloud_rollback. Provisioning creates a project and links this directory; the others change the linked cloud project, but they spawn rebase cloud, which acts on the project .rebase/cloud.json links with the CLI's own credential and the control plane's own permission checks; they never use baseUrl or DATABASE_URL, which is all the gate can check.
• 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. A DATABASE_URL exported in the shell the server was started from wins outright. Otherwise the gate reads every DATABASE_URL and ADMIN_CONNECTION_STRING (the fallback the branch commands accept) in <root>/.env, <root>/backend/.env, DOTENV_CONFIG_PATH and the parent directory's .env, parsing each file with dotenv as the CLI does, and refuses if any of them is remote. 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

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

Schema & database (13)

Spawn the Rebase CLI in the active project directory.

Schema planning (1)

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

Documents (5)

CRUD over a collection through @rebasepro/client.

Users & roles (6)

Dev server (3)

Storage (3)

Cron (5)

Functions (1)

Project registry (7)

Rebase Cloud (9)

Spawn rebase cloud … --json in the active project directory, against the project it is linked to, with the CLI's own credential. Provisioning creates a project; deploy, env set and rollback change the linked one. The loopback gate does not apply to them, because they never use baseUrl or DATABASE_URL.

Resources

The server exposes MCP resources for AI context:

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": "pnpm",      "args": ["--dir", "/path/to/your/project", "exec", "rebase-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:

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