dblift mcp

Serve a stdio MCP server for coding agents. Built-in tools are read-only; Pro and Enterprise add-ons register through `dblift.mcp_tools`. Requires `pip install "dblift[mcp]"`. The server exposes `dblift://history` and `dblift://pending`. This page documents OSS 5.0.0, which Enterprise 4.6.0 requires. `--mode`, `--resources`, and `--offline` shipped in 4.5.0. Applying, undoing, and cleaning stay CLI-only.

Synopsis

$ dblift mcp [--read-only] [--tools NAME[,NAME...]] [--mode {author,review}]
           [--resources NAME[,NAME...]] [--offline]

Options

FlagDescription

--read-onlyServe only tools that declare themselves read-only; an add-on tool registered read_only=False is skipped (its declaration is trusted; use --tools for an allowlist)

--toolsServe only the named tools, built-in or add-on; every other tool is skipped, and an unknown name — or an empty list — refuses to start

--resourcesServe only the named resources (history, pending — the dblift:// URI is accepted too); every other resource is skipped, and an unknown name — or an empty list — refuses to start

--offlineRefuse every tool and resource that would open a database connection, without connecting; tools that run from the project's files still answer

--mode'review' serves a review session: tools that write a file the caller names are skipped (as with --read-only) and the server instructions say the session is for review. Default 'author' applies no restriction

Startup line

At start the server prints, on stderr only, the environment it resolved and a masked database target. A configuration that fails to load is reported the same way and the server still starts. Secrets referenced by the configuration are resolved once at start, including with `--offline`. No connection is opened until a tool is called.

Built-in tool arguments

On OSS 5.0.0 two tool arguments default to false. `validate` takes `strict`: missing applied files and strict version order. The missing-file check needs a history table with applied rows. `migrate_dry_run` takes `show_sql`: the result adds `show_sql: true` and a `sql` array of `{script, version, description, statements}` for pending scripts. Resolved placeholders appear in that SQL, including secrets; an unresolved `${VAR}` stays visible. `show_sql` needs a live connection. `--offline` refuses the call. The tool still forces a dry run and does not apply. Unknown argument names are rejected before the command runs. The Pro `diff` tool (paid 4.6.0) is read-only. It refuses `generate_sql` whenever it is set; use `diff_to_sql` to write a script.

Errors and verdicts

A command that fails before producing a result — a refused connection, a history table that could not be created — is an MCP error (`isError: true`) with the CLI message. `dblift://history` and `dblift://pending` error instead of returning an empty list. A verdict, such as checksum issues, is a normal result with `success: false`. Check `success`.

Full guide: MCP Server guide — Install, client config, and the full tool list.

Workflow: MCP workflows — Day-to-day review, and the Pro and Enterprise authoring loop in 4.6.0.

Global flags apply to every command: --config, --env, --scripts, --dry-run, --quiet, --log-level. See global flags.

Examples

Start the server

$ dblift mcp

Skip add-on tools that declare themselves writable

$ dblift mcp --read-only

Allowlist specific tools

$ dblift mcp --tools info,validate,migrate_dry_run

Review session — withhold writers and instruct the agent to read and report

$ dblift mcp --mode review

Allowlist specific resources

$ dblift mcp --resources history

Refuse tools and resources that would open a database

$ dblift mcp --offline

Exit codes

CodeMeaning

0Command completed successfully

4A paid-edition feature was invoked without a valid licence (EXIT_LICENSE_REQUIRED)

Previousconfig Nextdiff