MCP Server

motherbase mcp exposes the linked project to an AI agent over the Model Context Protocol. The agent can read your schema, lint your policies, simulate row level security as a given user, and — when you allow it — apply migrations.

The gap this closes is the one self-hosters name about the alternative's MCP: "DDL statements not supported." Here DDL works, because the admin API this is built on already does it.

Setup

The server speaks stdio, so an MCP client launches it as a subprocess. Point the client at the CLI from a directory linked to a project (motherbase link):

{
  "mcpServers": {
    "motherbase": {
      "command": "npx",
      "args": ["-y", "@motherbase/cli", "mcp"],
      "cwd": "/path/to/your/project"
    }
  }
}

Claude Code:

claude mcp add motherbase -- npx -y @motherbase/cli mcp

Authentication is the CLI's own: the console session from motherbase login plus the project from motherbase link, or MOTHERBASE_URL + MOTHERBASE_ADMIN_TOKEN for direct mode. There is no separate token to manage, and an MCP session can reach exactly what a motherbase command could, no more.

Tools

Read-only by default:

Tool	What it does
`list_tables`	Tables with their columns and row counts
`describe_table`	Columns, types, nullability, defaults, primary key, indexes
`list_policies`	RLS state per table and every policy's `USING` / `WITH CHECK`
`simulate_rls`	Runs a SELECT as `anon`, `authenticated` or a named user, and reports the rows plus the policies that decided. Always rolled back
`get_advisors`	The schema and policy lint: RLS off on an exposed table, RLS on with no policy, policies that leak through a join, `SECURITY DEFINER` callable by `anon`
`get_logs`	Recent API and database log entries
`generate_types`	The TypeScript `Database` types
`list_queues`	Queue topics, consumers and delivery state
`list_vault_secrets`	Vault secret metadata (values are never returned)
`list_wrappers`	Foreign-data wrappers and their server options
`index_advisor`	Index recommendations for a SQL statement or workload
`list_auth_audit`	Auth audit entries with filters and pagination
`execute_sql`	A read-only query. Writes are refused

Letting an agent write

motherbase mcp --write

Adds two tools:

Tool	What it does
`apply_migration`	Creates a named migration from your DDL and applies it. Recorded, so it can be rolled back
`execute_sql_write`	Arbitrary SQL, including writes. No record, no rollback

Write is off by default and there is no setting that turns it on globally: handing an agent DDL is a decision you take per session, on the command line, where you can see it.

Note also that execute_sql stays on the read-only endpoint even in write mode. The tool a model reaches for by default cannot write, whatever it believed it was doing; writing means naming apply_migration.

Warning

An agent with --write pointed at production can drop a table. Prefer a preview or staging project, and prefer apply_migration over execute_sql_write so there is something to roll back.

Implementation note

The server is about 150 lines of JSON-RPC over stdin and stdout, with no dependencies. The official MCP SDK pulls express, hono, cors, ajv and a dozen more packages, and the CLI is deliberately zero-dependency: making npx @motherbase/cli install a web framework so one subcommand can read stdin is not a trade worth making.

The ceiling that buys is worth knowing: stdio transport and the tools capability only. No resources, no prompts, no sampling, no HTTP or SSE transport. If any of those is ever needed, the right move is to adopt the SDK rather than grow the hand-rolled server into a second one.